jira

What this skill does

# Jira

Jira operations via [jira-cli](https://github.com/ankitpokhrel/jira-cli) with wiki markup formatting.

## Wiki Markup Syntax

Jira uses wiki markup, **NOT Markdown**. Use this reference when writing descriptions or comments:

| Jira Syntax | Purpose | NOT this (Markdown) |
|-------------|---------|---------------------|
| `h2. Title` | Heading | `## Title` |
| `*bold*` | Bold | `**bold**` |
| `_italic_` | Italic | `*italic*` |
| `{{code}}` | Inline code | `` `code` `` |
| `{code:java}...{code}` | Code block | ` ```java ``` ` |
| `[text\|url]` | Link | `[text](url)` |
| `[PROJ-123]` | Issue link | - |
| `[~username]` | User mention | `@username` |
| `* item` | Bullet list | `- item` |
| `# item` | Numbered list (see warning) | `1. item` |
| `\|\|Header\|\|` | Table header | `\|Header\|` |

**Wiki Markup Pitfalls (Jira Cloud):**
- `# item` numbered lists often render as h1 headings in Jira Cloud. Prefer `* item` bullets instead.
- `* *bold text*` breaks bullet lists — the bold `*` collides with the bullet `*`. Avoid bold as the first word of a bullet, or use `_italic_` instead.
- `{code}` blocks may escape parentheses and special characters when submitted via CLI. Use `{noformat}` or nested bullets for simple structured text.

See `references/syntax-reference.md` for complete documentation.

## Prerequisites

```bash
# Install jira-cli
brew install jira-cli

# Configure (interactive)
jira init

# Verify setup
jira serverinfo
jira me
```

## Troubleshooting Auth

If `jira me` fails with a token error, the token likely exists but isn't visible in the current shell. Check these locations before asking the user to generate a new one:

```bash
# 1. Is the env var set in this shell?
echo $JIRA_API_TOKEN

# 2. Is direnv loading it from a shared env file?
grep -r "JIRA_API_TOKEN" ~/.config/direnv/envrc.d/ 2>/dev/null

# 3. Is it in a project-specific .envrc that hasn't been sourced here?
grep -rl "JIRA" ~/Code/**/.envrc 2>/dev/null

# 4. Is there a dedicated env file for the Ruby scripts?
cat ~/.env.jira 2>/dev/null

# 5. Check the jira-cli config itself
cat ~/.config/.jira/.config.yml | head -10
```

Common fix: if the token is loaded via direnv in another project, add a `.envrc` to the current project that sources the same shared file (e.g. `source_env ~/.config/direnv/envrc.d/envato.sh`), then run `direnv allow`.

## Switching Projects and Boards

jira-cli stores its default project and board in `~/.config/.jira/.config.yml`. When switching teams or projects, update these fields:

```yaml
board:
    id: 2469              # Board ID (find via: jira board list -p PROJ)
    name: My Team Board   # Display name
    type: kanban           # kanban or scrum
# ...
project:
    key: EN               # Project key
    type: classic          # classic or next-gen
```

You can also override the project per-command with `-p PROJECT` without changing the config.

## Quick Reference

| Operation | Command |
|-----------|---------|
| Search issues | `jira issue list -q "JQL"` |
| View issue | `jira issue view KEY` |
| Create issue | `jira issue create -t Type -s "Summary"` |
| Edit issue | `jira issue edit KEY` |
| Assign issue | `jira issue assign KEY USER` |
| Transition | `jira issue move KEY "Status"` |
| Add comment | `jira issue comment add KEY "text"` |
| Log work | `jira issue worklog add KEY TIME` |
| Link issues | `jira issue link KEY1 KEY2 TYPE` |
| List sprints | `jira sprint list BOARD_ID` |
| List boards | `jira board list -p PROJECT` |
| Current user | `jira me` |
| Find fields | `ruby scripts/jira_fields.rb search TERM` |

## Search & List Issues

```bash
# All issues in project
jira issue list -p PROJ

# With JQL query
jira issue list -q "project = PROJ AND status = 'In Progress'"

# Filter by status, type, priority, assignee
jira issue list -p PROJ -s "To Do" -t Bug -yHigh -a "[email protected]"

# Unassigned issues
jira issue list -p PROJ -ax

# Recently created (last 7 days)
jira issue list -p PROJ --created -7d

# Issues I'm watching
jira issue list -w

# Plain output for scripting
jira issue list -p PROJ --plain --columns KEY,SUMMARY,STATUS --no-truncate

# CSV export
jira issue list -p PROJ --csv > issues.csv

# JSON output
jira issue list -p PROJ --raw
```

## View Issue

```bash
# Basic view
jira issue view PROJ-123

# With comments
jira issue view PROJ-123 --comments 5

# Open in browser
jira open PROJ-123
```

## Create Issue

```bash
# Basic creation
jira issue create -p PROJ -t Task -s "Fix login bug"

# With description and priority
jira issue create -p PROJ -t Bug -s "Login fails" -b "h2. Steps to Reproduce
* Navigate to login
* Enter credentials
* Click submit

h2. Expected
Login succeeds

h2. Actual
500 error" -yHigh

# With labels and components
jira issue create -p PROJ -t Story -s "New feature" -l backend -l "high prio" -C "API"

# Sub-task (requires parent)
jira issue create -p PROJ -t Sub-task -s "Subtask" -P PROJ-100

# With custom fields
jira issue create -p PROJ -t Story -s "Feature" --custom "customfield_10001=value"

# Non-interactive (skip prompts)
jira issue create -p PROJ -t Task -s "Quick task" --no-input
```

## Edit Issue

```bash
# Edit summary
jira issue edit PROJ-123 -s "New summary"

# Edit description
jira issue edit PROJ-123 -b "Updated description"

# Change priority
jira issue edit PROJ-123 -yHigh

# Add labels
jira issue edit PROJ-123 -l newlabel

```

## Assign Issue

```bash
# Assign to user
jira issue assign PROJ-123 "[email protected]"

# Assign to me
jira issue assign PROJ-123 $(jira me)

# Default assignee
jira issue assign PROJ-123 default

# Unassign
jira issue assign PROJ-123 x
```

## Transition (Move) Issue

```bash
# Move to status
jira issue move PROJ-123 "In Progress"
jira issue move PROJ-123 "Done"

# With resolution
jira issue move PROJ-123 "Done" -R"Fixed"

# Assign during transition
jira issue move PROJ-123 "In Progress" -a$(jira me)
```

## Comments

```bash
# Add comment
jira issue comment add PROJ-123 "Fixed in commit abc123"

# Add comment from file
jira issue comment add PROJ-123 -T comment.txt

# List comments (via issue view)
jira issue view PROJ-123 --comments 10
```

## Worklogs (Time Tracking)

```bash
# Log time
jira issue worklog add PROJ-123 2h
jira issue worklog add PROJ-123 "1h 30m"

# With comment
jira issue worklog add PROJ-123 2h --comment "Implemented feature X"
```

## Issue Links

```bash
# Link two issues
jira issue link PROJ-123 PROJ-456 "Blocks"
jira issue link PROJ-123 PROJ-456 "Relates"
jira issue link PROJ-123 PROJ-456 "Duplicate"

# Unlink issues
jira issue unlink PROJ-123 PROJ-456
```

## Sprints

```bash
# List sprints for a board
jira sprint list BOARD_ID

# Active sprints only
jira sprint list BOARD_ID --state active

# Add issue to sprint
jira sprint add SPRINT_ID PROJ-123

# Current sprint issues
jira sprint list BOARD_ID --current
```

## Boards

```bash
# List boards for project
jira board list -p PROJ

# Get board ID, then use for sprint operations
```

**Note:** `jira board list` does not support `--plain` or other output flags. It always outputs a simple table.

## Output Formats

| Flag | Description |
|------|-------------|
| (default) | Interactive TUI mode |
| `--plain` | Plain text table |
| `--csv` | CSV format |
| `--raw` | Raw JSON |
| `--no-truncate` | Show full field values |
| `--columns KEY,SUMMARY,...` | Select columns |
| `--no-headers` | Hide table headers |

## Templates

Use these templates for well-structured issues:

- **Bug Report**: `templates/bug-report-template.md` - Environment, Steps to Reproduce, Expected/Actual, Error Messages
- **Feature Request**: `templates/feature-request-template.md` - Overview, User Stories, Acceptance Criteria, Technical Approach

## Syntax Validation

Validate wiki markup before submitting:

```bash
scripts/validate-jira-syntax.sh path/to/content.txt
```

Checks for common Markdown mistakes and suggests Jira equivalents.

## Field Discovery

jira-cli cannot list available fields. Use the included Ru