jira

# Jira Tool for Docs Writers Unified Jira skill for the DOCSP project. Supports both the `jira` CLI and `mcp-atlassian` MCP tools with automatic fallback. ## Critical Rules - Never modify or comment on a Jira ticket unless explicitly authorized by the user. - Always present a plan and get confirmation before making changes. - Field values are case-sensitive. - Always use Jira wiki markup in descriptions and comments, never Markdown. --- ## Tool Selection & Fallback Strategy **On the first Jira operation in a session**, determine which tool to use: 1. Check auto-memory (MEMORY.md) for a Jira tool preference entry: - "Jira CLI available" entry present → **session-preferred = CLI** — skip the probe. - "Jira MCP preferred" entry present → **session-preferred = MCP** — skip the probe. 2. If neither entry is present, run `which jira && jira me` (5-second Bash timeout). 3. If both succeed → **session-preferred = CLI**. Write a memory entry (see below) so future sessions skip this probe. 4. If either fails → **session-preferred = MCP**. Write a memory entry (see below) so future sessions skip this probe. **Session memory**: Once a tool is marked as session-preferred, use it for all subsequent operations without re-testing. **Quick-fail rule**: If the session-preferred tool fails on a specific operation, immediately try the other. Do not retry the failed tool more than once. If the fallback succeeds, switch session-preferred to the fallback. If both fail, report the error. **MCP tool names** are environment-specific (e.g., `jira_create_issue`, `jira_search`). Use whatever Jira MCP tools are available in the current session. ### Writing Probe Results to Memory After a probe (step 3 or 4), write a `feedback` memory entry to the project's auto-memory directory (path shown in system instructions) so future sessions skip the probe. | Result | Filename | name slug | Body | |---|---|---|---| | CLI succeeded | `feedback_jira_cli_available.md` | `feedback-jira-cli-available` | "User has the Jira CLI installed. Skip probe and use CLI directly." | | CLI failed | `feedback_jira_mcp_preferred.md` | `feedback-jira-mcp-preferred` | "User does not have Jira CLI. Skip probe and use MCP directly." | Also add the corresponding line to `MEMORY.md`: - CLI: `- [Jira CLI available — skip availability check](feedback_jira_cli_available.md) — User has jira CLI installed; skip probe, go straight to CLI` - MCP: `- [Jira MCP preferred — skip probe](feedback_jira_mcp_preferred.md) — User has no jira CLI; skip probe, go straight to MCP tools` --- ## Configuration - CLI binary: `jira` (`jira-cli` v1.7.0+, installed via Homebrew) - CLI config: `~/.config/.jira/.config.yml` - Auth: Bearer token (pre-configured) - Default project: DOCSP --- ## CLI Gotchas ### Custom Field Names The `--custom` flag requires **lowercase-hyphenated** display names — not the raw field key or the Jira display name. | Display Name | `--custom` Name | Field Key | |---|---|---| | Story Points | `story-points` | customfield_10555 | | Did you use AI? | `did-you-use-ai?` | customfield_27257 | Pattern: `"Display Name"` → `display-name` — lowercase and replace spaces with hyphens, but **do not strip punctuation**. jira-cli preserves characters like `?`, so "Did you use AI?" becomes `did-you-use-ai?` (trailing `?` included), not `did-you-use-ai`. Passing the wrong slug triggers an `Invalid custom fields used in the command` warning and the field is silently ignored (the command still exits 0). ### JQL ORDER BY Do NOT put `ORDER BY` inside the JQL string when using the CLI. Use flags: ```bash # WRONG — will error jira issue list -q "assignee = currentUser() ORDER BY updated DESC" # CORRECT — default order is DESC, so --order-by updated gives newest first jira issue list -q "assignee = currentUser()" --order-by updated ``` ### Transition Names vs Status Names `jira issue move` uses **transition names**, not status names. The CLI shows valid transitions on error: ```bash # WRONG — "Closed" is a status name jira issue move DOCSP-12345 "Closed" # CORRECT — "Close Issue" is the transition name (verify per ticket) jira issue move DOCSP-12345 "Close Issue" ``` When uncertain, attempt the move and read the error for valid transition names. ### Description via Stdin For multi-line descriptions, **always pipe via stdin** — not `-b "$(cat <<'EOF'...)"`. The `-b` flag with `$()` heredocs causes the CLI to hang silently. ```bash # WRONG — hangs silently jira issue create -p DOCSP -t Task -s "Title" -b "$(cat <<'EOF' description here EOF )" --no-input # CORRECT cat <<'EOF' | jira issue create -p DOCSP -t Task -s "Title" --no-input --raw h2. Overview description here EOF ``` The `-b` flag works fine for short single-line descriptions. ### Non-Interactive Mode Always pass `--no-input` for create/edit operations. Always pass `--plain` for list operations. --- ## Ticket Lifecycle Standard progression for a writing ticket: **Needs Triage → Ready for Work → In Progress → Internal Review → External Review → Closed** Use `jira_get_transitions` (MCP) or attempt `jira issue move` and read the error (CLI) to get valid transition names/IDs before transitioning. | Status | When to use | |---|---| | Ready for Work | Triaged and scheduled for near-term work | | In Progress | Writer has started work | | Internal Review | PR is open; waiting for internal (team) review | | External Review | Waiting for SME or stakeholder review | | Needs Merge | PR is approved and waiting to be merged — optional | | Blocked | Work is blocked on an external dependency | | Closed | PR merged and work complete — see Closing Issues below | Tickets typically close directly from Internal Review or External Review. Needs Merge is available but not a standard step for any team. The Close transition requires Story Points and "Did you use AI?" — see Closing Issues. --- ## Labels Apply labels when creating or updating a ticket. Labels are case-sensitive. Apply exactly one primary label; add zero or more additional labels alongside it. | Label | Type | When to use | |---|---|---| | `feature` | primary | New feature documentation driven by a product change | | `request` | primary | Stakeholder or community-submitted content request | | `proactive` | primary | Writer-initiated improvement | | `bug` | primary | Documentation error or inaccuracy | | `docs-rn` | primary | Release notes ticket | | `404` | additional | Broken link or missing page | | `seo` | additional | Redirect or metadata work motivated by SEO | | `IA` | additional | Information architecture initiative (navigation, TOC, reorganization) | | `LLM` | additional | Mercury / AI chatbot content review | | `archiving` | additional | EOL or archival work | | `nested-components` | additional | Nested tab component fix | | `taxonomy` | additional | Taxonomy or metadata classification work | ```bash # CLI — replaces existing labels; include all desired labels jira issue edit DOCSP-12345 --label feature --label seo --no-input ``` ```python # MCP — replaces existing labels; include all desired labels jira_update_issue( issue_key="DOCSP-12345", fields={"labels": ["feature", "seo"]} ) ``` --- ## Component Field Components are optional but should be set when the work's ownership is clear. If the component isn't obvious from context, ask the user which team owns the work. Use `all-docs` when the work applies to or affects all teams equally and cannot be attributed to a single team's ownership. If the component is ambiguous and the user is unsure, omit it rather than guessing. Do not use these archived components: `snooty`, `snooty autobuilder`, `snooty-autobuilder`, `snooty-frontend`, `snooty-parser`. --- ## Creating Issues | Field | CLI Flag | MCP Parameter | Notes | |---|---|---|---| | Project \* | `-p DOCSP` | `project_key="DOCSP"` | | | Type \* | `-t Task` | `issue_type` — see below | | | Summary \* | `-s "Title"` | `summary` | | | Description | `-b` or stdin | `description` | Jira wiki markup | | Component | `-C Atlas` | `components` | Infer from context; omit if unclear | | Priority | `-y "Major - P3"` | `additional_fields: {"priority": {"name": "..."}}` | | | Fix Version | — | `additional_fields: {"fixVersions": [{"name": "..."}]}` | Versioned driver or server work | | Story Points Estimate | — | `additional_fields: {"customfield_27258": <number>}` | Upfront effort estimate; use the story point scale | | Epic Name | — | `additional_fields: {"customfield_10858": "Name"}` | Required when issue type is Epic | | Labels | `--label feature` | `additional_fields: {"labels": ["..."]}` | See Labels section | \* Required **Issue type:** - `Task` — general docs work (default) - `Bug` — error, inaccuracy, or broken content - `Story` — larger feature or initiative - `Epic` — large initiative spanning multiple tickets; must include Epic Name (`customfield_10858`) **Priority:** - `Critical - P2` — urgent, blocking, or high-visibility - `Major - P3` — standard work - `Minor - P4` — low-impact or nice-to-have (default) **CLI example:** ```bash cat <<'EOF' | jira issue create -p DOCSP -t Task \ -s "Update connection string examples for Atlas shared clusters" \ -C Atlas -y "Major - P3" --label feature --no-input --raw h2. Overview Update the connection string examples... EOF ``` **MCP example:** ```python jira_create_issue( project_key="DOCSP", summary="Update connection string examples for Atlas shared clusters", issue_type="Task", description="h2. Overview\nUpdate the connection string examples...", components="Atlas", additional_fields={ "priority": {"name": "Major - P3"}, "labels": ["feature"] } ) ``` --- ## Closing Issues Before closing, confirm the PR has been merged. Tickets typically close from Internal Review or External Review — Needs Merge is not a required step. **Story Points, "Did you use AI?", and Resolution are required at close time.** The `resolution` field is screen-controlled — it can only be set during the Close transition, not via a separate edit. Omitting it leaves the ticket in an unresolved state even after it reaches Closed status, so it will continue to appear in `resolution = Unresolved` filters. **CLI approach** — set the fields first, then transition: ```bash jira issue edit DOCSP-12345 \ --custom "story-points=3" \ --custom "did-you-use-ai?=Yes" \ --no-input jira issue move DOCSP-12345 "Close Issue" ``` **MCP approach** — get the Close transition ID, then transition with required fields: ```python jira_get_transitions(issue_key="DOCSP-12345") jira_transition_issue( issue_key="DOCSP-12345", transition_id="<close-id>", fields={ "customfield_10555": 3, "customfield_27257": {"value": "Yes"}, "resolution": {"name": "Done"} } ) ``` If the MCP transition fails with "This field is required", use `jira_search_fields` to identify the missing field. ### Resolution Values | Resolution | When to use | |---|---| | `Done` | Work complete — PR merged | | `Fixed` | Bug or inaccuracy resolved | | `Won't Do` | Ticket declined or deprioritized | | `Duplicate` | Closed as duplicate of another ticket | ### Story Point Estimation Estimate based on writing effort, product knowledge required, and testing effort. Use the ticket description and any work done in the session to judge the scale. | Points | Scope | |---|---| | 0 | No work done: closing as Won't Do, Duplicate, or other non-completion resolution | | 1 | Minimal: link update, typo fix, copy-paste from ticket, release notes, backport subtask | | 2 | Light: section update, small ticket with backports | | 3 | Moderate: new page, page refactor, small feature, moderately complex procedure | | 5 | Heavy: multiple pages, complex procedure, medium to large feature | | 8 | Expert: multiple pages and subpages, several complex procedures, large feature | | 13 | Maximum: major feature with site-wide impact | **If the estimate is 8 or 13:** Flag this to the user. An 8-point ticket should be broken into subtasks; a 13-point ticket should be an epic with child tickets. Do not silently close without surfacing this. Ask the user for their estimate if the ticket scope is unclear. --- ## Common Operations ### View a ticket ```bash # CLI jira issue view DOCSP-12345 --plain jira issue view DOCSP-12345 --raw # full JSON for parsing fields ``` ```python # MCP jira_get_issue(issue_key="DOCSP-12345") ``` ### Search tickets ```bash # CLI jira issue list --plain \ -q "assignee = currentUser() AND status = 'In Progress'" \ --order-by updated --paginate "0:10" ``` ```python # MCP jira_search(jql="assignee = currentUser() AND status = 'In Progress' ORDER BY updated DESC") ``` ### Update a ticket ```bash # CLI jira issue edit DOCSP-12345 -s "New summary" --no-input jira issue edit DOCSP-12345 -y "Critical - P2" --no-input jira issue edit DOCSP-12345 -a "jane.smith@mongodb.com" --no-input ``` ```python # MCP jira_update_issue( issue_key="DOCSP-12345", fields={"summary": "New summary", "priority": {"name": "Critical - P2"}} ) ``` ### Transition a ticket ```bash # CLI — attempt and read error for valid transition names jira issue move DOCSP-12345 "Start Progress" ``` ```python # MCP jira_get_transitions(issue_key="DOCSP-12345") # get transition IDs first jira_transition_issue(issue_key="DOCSP-12345", transition_id="<id>") ```