/ticket

name: ticket
description: Turn a note from the living manual (idea, feedback, or bug in a <submission> block, or a free-form report) into an actionable developer ticket with user stories, functional requirements, and acceptance criteria, plus open questions when completeness can't be verified. Syncs the manual's queue index and, when a tracker is configured, creates or updates the matching issue (Jira via the Atlassian MCP, or GitHub Issues via the gh CLI).

Note → ticket

Input: a `<submission>` block pasted from the manual's "Make a note" modal (source, section, target, type, summary, details, and optionally relates-to / roadmap fields), or a free-form report. One ticket per submission unless it clearly contains independent requests.

Config: `.living-manual.json` at repo root supplies `tickets_dir`, `manual_path`, and `tracker`. Prose follows the plugin's `reference/writing-style.md`. `$LM` below is the plugin root; this file lives at `$LM/skills/ticket/SKILL.md`.

Targets

• `target: current behavior` → a ticket against the shipped app.
• `target: roadmapped work` → a plan-revision ticket. Ground in the

named roadmap source and planned-state text, write stories, requirements, and criteria as deltas to the plan, and surface any conflict with the plan's intent as an open question. Never write it as a change to today's implementation.

Enforce the routing for free-form reports too: a complaint about behavior that a planned item already replaces becomes a plan-revision ticket against that item, stated in the summary.

Procedure

1. Ground first. Read the named manual section, the code behind it, and the project's planning docs. Every claim about current behavior must be verifiable in code or docs. 2. Classify honestly. Designed-but-frustrating behavior is feedback naming the governing decision, not a bug. Reclassify a mislabeled submission and say so in the ticket. 3. Check for collisions: existing tickets in `tickets_dir`, planned items, roadmap docs. Duplicate of a queued ticket → treat as an addition (below) and tell the user. Covered by planned work → scope the ticket to the delta only. 4. Number it: `sh $LM/scripts/next-ticket.sh <tickets_dir>`. 5. Write `<tickets_dir>/TICKET-NNNN-<slug>.md`:

   ---
   id: TICKET-NNNN
   title: <one line>
   type: idea | feedback | bug
   target: current | roadmap:<item-id>
   status: ready | needs-answers   (later: shipped | declined)
   section: <manual section + anchor>
   created: <YYYY-MM-DD>
   issue: <tracker ref, when synced: ABC-123 or owner/name#42>
   ---
   ## Summary
   ## Origin            (submission verbatim, fenced)
   ## Current behavior  (or "Planned behavior" for roadmap tickets; with file refs)
   ## User stories      (As a / I want / so that; every FR traces to one)
   ## Functional requirements  (FR-1...; each testable and unambiguous)
   ## Acceptance criteria      (Given/When/Then; together they cover every FR)
   ## Open questions    (required when status is needs-answers)
   ## References

6. The completeness gate. `ready` only when every FR is unambiguous and testable, criteria cover every FR, and nothing rests on a guess. Otherwise `needs-answers`, and Open Questions must be sufficient: each question names the FR it blocks, proposes a default, and says what changes if the default is wrong. Answering all of them must flip the ticket to ready. Do not pad a thin submission into false precision; ask. 7. Sync the manual's queue index in one command: `python3 $LM/scripts/tickets-index.py <tickets_dir> <manual_path>`. It rebuilds the TICKETS block from the ticket files' frontmatter and Summary sections, then folds in open tracker issues no ticket file references, so the queue can't drift from either. Run it after every write or status change. It reports any issue it folded in: those are tracker issues missing their local record, and writing that record is this skill's job. On Jira the script cannot run `list` (MCP needs a session), so do that reconciliation here: list open issues in the project, and for any with no matching `issue:` frontmatter, tell the user rather than silently leaving the queue short. A resolved ticket gets `status: shipped` or `status: declined`; the file stays as the record and the index drops it automatically. 8. Tracker sync, when `tracker.provider` is not `none` (a legacy top-level `jira` block with `enabled: true` reads as provider `jira`):

• Read `$LM/reference/trackers.md` for the provider's operations.
• Run its detect step first. Unavailable: note it, skip, local

ticket stands.

• Create the issue per the provider section: title from the ticket

title, body from the ticket (stories, FRs, criteria, open questions) in the format the provider accepts, type or label mapping and any routing (component, milestone, extra labels) from config. A type may map to one label or several; apply them all, plus the global extras, each label once. Config taxonomy missing at the tracker (a label deleted since setup, say): create nothing; file the issue with the labels that do exist, and name the missing one in the report.

• Write the returned ref into the ticket frontmatter (`issue:`) and

mention it in your report.

• Additions and status changes update the same issue (comment with

the new submission, edit the description) rather than creating a twin.

• A tracker write failure never blocks the local ticket. Report the

failure and the retry path. 9. Report: ticket path, status, tracker ref if any, and open questions inline so the user can answer immediately. Answers update the same ticket in place: fold into FRs and criteria, clear resolved questions, flip status, re-sync index and tracker.

Additions (`relates-to: TICKET-NNNN`)

The user reviewed the queue and identified their note as an addition. Do