| name | issue-tracker-ingestion |
| description | Pull issue/PR/ticket details from Jira, GitHub Issues, Linear, or Azure Boards via MCP into `01-spec.md` `## Source`. Use at the start of `/spec` whenever the user references an external ticket. |
| when_to_use | ["Phase 1 (Specify) — converting a tracker ID into a spec.","Verifying that a spec's `## Source` accurately reflects the ticket."] |
| authoritative_references | ["docs/platform-mapping.md (MCP wiring)",".github/templates/spec.template.md"] |
Issue tracker ingestion
Supported sources
| Source | MCP server | Identifier shape |
|---|
| Jira (Atlassian) | atlassian | SHOP-1422 |
| GitHub Issues | github | owner/repo#42 or URL |
| GitHub Pull Requests | github | owner/repo!42 or URL |
| Linear | linear | ENG-123 |
| Azure Boards | azure-devops | AB#54321 |
If no MCP is configured, fall back to user-provided text. Never invent a ticket.
Recipe (per source)
-
Resolve identifier → MCP fetch.
-
Capture: title, description, status, labels, assignee, comments (last 10), attachments (filenames only), URL, fetched-at timestamp.
-
Write a verbatim block in 01-spec.md:
## Source
- **System:** Jira
- **ID:** SHOP-1422
- **URL:** https://example.atlassian.net/browse/SHOP-1422
- **Title:** Apply gift card at checkout
- **Status:** In Progress
- **Fetched:** 2026-04-18T10:00:00Z
### Description (verbatim)
> Users should be able to apply a gift card during checkout. It should reduce the order total. If the card has been used, show an error.
### Comments (last N, verbatim)
> [PM, 2026-04-15]: Confirmed only authenticated buyers in scope.
> [Eng lead, 2026-04-16]: Use existing error envelope.
-
Extract candidate ACs only from the verbatim text. Do not paraphrase requirements; quote the source line and put your AC under it. If a candidate AC has no source line, it goes to ## Open Questions as a Q-NNN.
No-invention enforcement
If a source field is missing (e.g. no acceptance criteria in the ticket), the agent does not fill it from imagination. It writes:
- **Q-001** — Source ticket has no explicit acceptance criteria. Need user to confirm AC list before proceeding to AC drafting.
/spec then halts and asks the user.
Updating after the ticket changes
If the user re-runs /spec and the ticket has changed:
- Re-fetch.
- Diff old vs new in
## Out-of-Band Inputs ("ticket updated 2026-04-19; description gained paragraph about partial redemption").
- Add
Q-NNN for any new requirement not yet in AC.
Anti-patterns
- "The ticket says X" without quoting it.
- Summarizing comments instead of quoting.
- Pulling AC from the ticket title alone.
- Silently ignoring an unread comment that contradicts the description.
- Assuming the ticket assignee = the spec author.
