Fetching Jira Ticket

1. Read the retriever subagent definition
2. Dispatch the subagent with JIRA_URL
3. Interpret the structured summary it returns
4. Report the file path, counts, and warnings to the caller

Subagent Registry

Read a subagent definition only when you are about to dispatch it.

Dispatch Contract

This stage dispatches exactly one bundled retriever subagent.

• Read ./subagents/ticket-retriever.md only when you are ready to dispatch it
• Pass only the stage input contract values plus any directly derived identifiers
• Treat the retriever as the only component allowed to read raw Jira payloads, assemble the snapshot, validate the artifact, and decide whether the run is PASS, PARTIAL, FAIL, or ERROR
• Keep only the retriever's structured summary in orchestrator context; do not inspect raw payloads or rewrite the artifact in this coordinator

How This Skill Works

This skill is intentionally narrow. It coordinates retrieval, not mutation, planning, or execution. Keep only:

• TICKET_KEY and the URL needed for the next phase
• The file path written
• Counts and warnings from the retriever summary
• Any fatal reason that requires user action

This phase succeeds only when the retriever returns a structured result that matches the output contract and, when a file is written, reports validation status consistently.

This coordinator may do four things directly: read its bundled skill files, derive identifiers from the input contract (including workspace, project, and ticket key derived from JIRA_URL), dispatch the retriever, and relay the retriever's structured summary. Everything else stays inside the subagent.

1. Dispatch the retriever

Read ./subagents/ticket-retriever.md, then dispatch it with:

• JIRA_URL

The subagent owns input validation, Jira read-path discovery and auth checks, ticket and relationship retrieval, document assembly, output validation, and cleanup.

2. Interpret the structured result

Reminder: branch on the structured result fields, not on prose. This coordinator dispatches, interprets, and relays summaries; it does not inspect raw Jira payloads or rewrite the artifact.

The retriever returns the locked summary shape used by the paired tracker- fetching skills. Only the tracker-specific identity line, state line, and work-breakdown line differ:

• FETCH: PASS -> retrieval and validation succeeded
• FETCH: PARTIAL -> artifact was written and validated, but some comments or related items could not be retrieved, or related-item discovery could not be verified
• Shared rule: parent comment retrieval and subtasks / linked issues retrieval or discovery gaps use PARTIAL
• Jira-specific: ## Attachments and ## Custom Fields are populated from the retrieved parent ticket payload and do not introduce a separate unknown-discovery state
• FETCH: FAIL -> deterministic failure such as bad input, ticket not found, missing auth, rate limits after retry, or no usable Jira tools
• FETCH: ERROR -> unexpected tool or environment failure
• Failure category -> machine-readable cause for FETCH: FAIL or FETCH: ERROR

Validation is reported separately:

• Validation: PASS -> the written file satisfies the template contract
• Validation: FAIL -> the file was written but still violates the contract
• Validation: NOT_RUN -> retrieval failed before validation could happen

For count lines in the summary:

• 0/0 (where that shape applies) means the retriever verified that no items exist in that section
• <retrieved>/UNKNOWN means the parent ticket was retrieved but discovery for that section could not be verified; the retriever records a warning and treats the run as FETCH: PARTIAL
• N/A for Comments, Subtasks, or Linked issues means the parent ticket was not retrieved and those retrieval steps never ran (for example, Failure category: NOT_FOUND before any snapshot). Do not use 0/0 or <retrieved>/UNKNOWN in that case
• Attachments: <N> is the number of attachment entries under ## Attachments; use Attachments: N/A when the parent ticket was not retrieved (that section was not populated from a successful parent read)

Failure categories are:

• NONE -> no fatal failure occurred
• BAD_INPUT -> malformed or unsupported Jira URL
• NOT_FOUND -> the parent Jira ticket could not be found before a valid artifact was produced
• AUTH -> Jira access was denied or not authenticated
• TOOLS_MISSING -> no suitable Jira-capable tools were available
• RATE_LIMIT -> Jira access was rate-limited and retry budget was exhausted
• UNEXPECTED -> tool or environment failure outside the expected categories

Handle them this way:

• FETCH: PASS with Validation: PASS: report success and continue
• FETCH: PARTIAL with Validation: PASS: report success with warnings and make the incompleteness visible, including any template unknown markers
• Validation: FAIL: stop and relay contract failure (any FETCH)
• FETCH: FAIL: stop and relay the failure category plus the reason
• FETCH: ERROR: stop and relay the failure category plus the reason as an unexpected failure
• Any inconsistent pairing, such as FETCH: PASS with Validation: NOT_RUN: treat it as FETCH: ERROR and stop

Do not infer fatal cause from prose when Failure category is present. Branch on the category, then use Reason only for user-facing detail.

Locked summary line order:

1. FETCH
2. Validation
3. Failure category
4. File written
5. Tracker identity line (Ticket: ... on Jira)
6. Tracker state line (Status: ... | Type: ... on Jira)
7. Comments
8. Work-breakdown line (Subtasks: ... on Jira)
9. Linked issues
10. Attachments
11. Warnings
12. Reason

3. Report only the summary

Using only the subagent's structured summary, tell the caller:

• The file path written, when one exists
• The ticket identity (Ticket: <TICKET_KEY>: <Summary>)
• The ticket state (Status: ... | Type: ...)
• Retrieved versus discovered counts for comments, or N/A when the parent ticket was not retrieved
• The attachment entry count (Attachments: <N>), or N/A when the parent ticket was not retrieved
• Retrieved versus discovered counts for subtasks and linked issues, where the discovered total may be UNKNOWN when discovery could not be verified, or N/A when the parent ticket was not retrieved and discovery never ran
• Any warnings or fatal reason
• Any failure category, when one exists
• That this phase is retrieval only and does not mutate Jira

Output Contract

Primary artifact:

docs/<TICKET_KEY>.md

Treat docs/<TICKET_KEY>.md as a preserved workflow artifact for resumability. Do not commit it as part of implementation history.

The document must contain every top-level heading from the fenced Markdown snapshot shape in ./subagents/ticket-retriever-template.md. Repeated nested headings, such as comment entries or per-related-item subsections, appear only when their parent section has material to render. If a top-level section has verified empty data, the heading still appears and the section body is _None_. If the retriever could not verify whether a section is empty, the artifact must use the template's unknown marker instead. Downstream skills rely on stable headings rather than best-effort prose. If retrieval is partial, the artifact must record that explicitly in ## Retrieval Warnings and use the template's placeholder shapes for any subtask or linked issue that could not be hydrated, or the template's unknown marker when a section could not be verified as empty.

Treat ./subagents/ticket-retriever-template.md as the authoritative snapshot shape bundled with this skill. The section tables below are the scan-friendly summary of that contract.

Locked-core sections (same names and relative order across the paired issue/ticket-fetching skills; the platform-slot heading—## Child Issues on GitHub and ## Subtasks on Jira—occupies the locked position between ## Retrieval Warnings and ## Linked Issues):

Locked platform-slot section (shared concept; the parallel issue-fetching skill uses ## Child Issues):

Top-level snapshot order is ## Metadata, ## Description, ## Acceptance Criteria, ## Comments, ## Retrieval Warnings, ## Subtasks, ## Linked Issues, then the platform-extension sections below.

The retrieval preamble must include Retrieved on, Source: <JIRA_URL>, and Workspace: <workspace> | Project: <project> | Ticket: <TICKET_KEY>. In ## Metadata, keep stable identity rows for Ticket Key, Workspace, Project, and URL.

Platform-extension sections (Jira-specific; expected to differ across tracker-fetching skills). All stay stably present, using _None_ only when their absence was verified:

Escalation

Branch on the retriever's structured status fields, not on prose:

Example

1. Read ./subagents/ticket-retriever.md

2. Dispatch ticket-retriever with JIRA_URL

3. Subagent returns:

   FETCH: PASS Validation: PASS Failure category: NONE File written: docs/JNS-6065.md Ticket: JNS-6065: Implement dark mode toggle Status: In Progress | Type: Story Comments: 4/4 Subtasks: 3/3 Linked issues: 1/1 Attachments: 2 Warnings: None Reason: None

4. Report: "Ticket fetched to docs/JNS-6065.md. JNS-6065: Implement dark mode toggle is In Progress (Story). Retrieved 4/4 comments, 3/3 subtasks, 1/1 linked issues, and 2 attachments. Retrieval only; Jira was not modified."

   </example>

1. Read ./subagents/ticket-retriever.md

2. Dispatch ticket-retriever with JIRA_URL

3. Subagent returns:

   FETCH: PARTIAL Validation: PASS Failure category: NONE File written: docs/JNS-7001.md Ticket: JNS-7001: Audit webhook retries Status: To Do | Type: Task Comments: 2/2 Subtasks: 1/2 Linked issues: 0/0 Attachments: 0 Warnings: Could not retrieve JNS-7002 (404 Not Found) Reason: None

4. Report: "Ticket fetched to docs/JNS-7001.md with retrieval warnings. JNS-7001: Audit webhook retries is To Do (Task). Retrieved 2/2 comments, 1/2 subtasks, 0/0 linked issues, and 0 attachments. Warning: Could not retrieve JNS-7002 (404 Not Found). Retrieval only; Jira was not modified."