Jira Tool for Docs Writers

Unified Jira skill for the DOCSP project. Supports three interchangeable backends with automatic fallback between them (see Tool Selection below).

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.
• When referencing a ticket key back to the user, include its title (e.g., "DOCSP-12345 — Fix broken link on X page") so it's identifiable without a lookup.
• When asked to "add" or "update" ticket content without a target specified, ask whether it goes in the description or as a comment rather than defaulting to a comment.

Tool Selection & Fallback Strategy

Three tools can back this skill:

• CLI — the jira binary. Reference: references/cli.md.
• mcp-atlassian — a generic Jira/Confluence MCP server. Reference: references/mcp-atlassian.md.
• DevProd MCP Gateway — MongoDB's internal MCP gateway, Jira backend (tools prefixed jira_, distinct parameter shapes from mcp-atlassian). Reference: references/devprod-gateway.md.

On the first Jira operation in a session, determine which tool to use:

1. Check auto-memory (MEMORY.md) for a stored tool preference:
   • "Jira CLI preferred" → session-preferred = CLI — skip the probe.
   • "mcp-atlassian preferred" → session-preferred = mcp-atlassian — skip the probe.
   • "DevProd Gateway preferred" → session-preferred = DevProd Gateway — skip the probe.
2. If no preference is stored, probe availability:
   • CLI: run which jira && jira me (5-second Bash timeout).
   • mcp-atlassian: check whether its tools (e.g., jira_search, jira_get_issue) are present in the session.
   • DevProd Gateway: check whether its tools (e.g., jira_search_issues, jira_get_issue) are present in the session.
3. If more than one is available, ask the user which to default to. Nudge toward the CLI when offering a recommendation — it avoids MCP tool-schema overhead and is generally more token-efficient — but let the user decide.
4. If only one is available, use it without asking.
5. Write the choice to memory (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-probing.

Quick-fail rule: If the session-preferred tool fails on a specific operation, immediately try one of the others that's available. Do not retry the failed tool more than once. If a fallback succeeds, switch session-preferred to it for the rest of the session (this does not overwrite the stored memory preference — ask the user before changing that permanently). If none succeed, report the error.

Writing Tool Preference to Memory

After determining session-preferred, write a feedback memory entry to the project's auto-memory directory so future sessions skip the probe, plus the corresponding line to MEMORY.md:

If an existing memory entry uses the old "Jira CLI available" / "Jira MCP preferred" naming from before the three-way split, treat it as CLI / mcp-atlassian respectively and update the filename/slug to the new naming next time you'd write to it.

Ticket Lifecycle

Standard progression for a writing ticket (same across all three tools — this is Jira workflow configuration, not tool-specific):

Needs Triage → Ready for Work → In Progress → Internal Review → External Review → Closed

Look up valid transition names/IDs before transitioning — see your tool's reference file.

Tickets typically close directly from Internal Review or External Review. Needs Merge is available but not a standard step for any team.

When moving a ticket to Internal Review or Needs Merge, post the PR URL as a comment (see Post a PR link comment in your tool's reference file).

Before closing, confirm the PR has been merged.

The Close transition requires Story Points and "Did you use AI?" — see Closing Issues in your tool's reference file.

Before attempting the Close transition, check whether Story Points is already set. If not, ask the user for an estimate (see Story Point Estimation below) rather than attempting the transition first and reacting to the failure.

Resolution Values

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.

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.

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. See your tool's reference file for the exact syntax to set labels.

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

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

Priority:

• Critical - P2 — urgent, blocking, or high-visibility
• Major - P3 — standard work
• Minor - P4 — low-impact or nice-to-have (default)

See your tool's reference file for field mappings and a full create example.

Link Types

Common link types (same across all three tools; syntax to create a link is tool-specific, see your tool's reference file):

Scope Creep: Follow-up Ticket Creation

When work during a session expands beyond the current ticket's original scope, create a follow-up ticket rather than expanding the current one. This keeps tickets focused and the backlog accurate.

When to suggest this: The user discovers additional work while implementing the current ticket — new pages to update, related gaps, or adjacent issues that weren't in the original scope.

Workflow:

1. Identify the out-of-scope work clearly.
2. Ask the user to confirm it should be a separate ticket, and whether it belongs under an epic (or no epic).
3. Create a new DOCSP ticket with:
   • A summary scoped to the new work only
   • A description referencing the originating ticket (e.g., "Discovered during DOCSP-XXXXX")
   • The same component and labels as the parent ticket (unless the work clearly belongs elsewhere)
4. Link the new ticket to the original with link type "Related".
5. Present the new ticket key to the user.

Example description for a follow-up ticket:

h2. Overview
Follow-up work discovered during DOCSP-12345.

h2. Scope
[Description of the additional work]