/ticket-creator

name: ticket-creator
description: "Create well-structured tickets as reviewable markdown files, then push to any tracker (Jira, Linear, Trello, Asana, Shortcut) via MCP or CLI after user review. Grounds each ticket in actual code by calling /flagrare:codebase-explore before drafting, and polishes the Context section via /flagrare:write-docs. Use when the user asks to create tickets, file bugs, write stories, create tasks, build a backlog, or convert specs/TDDs into implementation tickets."

Ticket Creator

Create tickets as **reviewable markdown files** first. Present them for review. Only push to the tracker when the user explicitly approves.

---

Keep tickets short

A ticket is a pointer, not a document. The reader is an engineer who will open the linked spec and read the code; the ticket's job is to orient them and define done, not to reproduce everything. Aim for a body that fits on one screen (rough target: 40 lines). If a ticket needs more, it is either too big (split it) or it is restating a spec it should just link.

Concretely:

• **Context**: 2 to 4 sentences of prose that tell the *story*: what the system does, why this case is the exception, what breaks if ignored. Lead with the narrative, not the mechanics. Link the spec/TDD; do not paraphrase it.
• **Grounding**: **at most 2 to 3 pointers, and only ones that change how the reader thinks.** Two-or-three is a ceiling, not a quota; one good pointer beats five. Prefer weaving the pointer into the Context prose ("the `processPayment()` flow isn't wrapped in a transaction") over a separate bulleted `file:line` list. A bulleted wall of `path/file.kt:42` lines is the #1 enumeration smell; it reads as your exploration trail, not as help.
• **What needs to happen**: the intent and the simplest approach, in prose. The engineer owns the how; do not write the implementation for them or list every file they'll touch.
• **Acceptance criteria**: 3 to 4 testable lines that capture what *done* means. Not an exhaustive matrix; do not enumerate every table, field, or branch.

Say it once

Each fact appears once per ticket. The usual repeats, all of which read as padding:

• **Context previews the bullets.** If "What needs to happen" lists the change, Context says why it's needed, not the change again.
• **Acceptance criteria restate the bullets.** Criteria say what *done* looks like from the outside (a test passes, a screen shows X), not "the endpoint from step 2 exists".
• **The same caveat in two sections** ("everything is additive" in Context, "all additive" in the criteria). Keep the one where the reader acts on it.
• **Long dependency lines.** "Enables: every frontend ticket" beats a list of six ticket titles.

Across a backlog, the same rule holds at the epic level: the product story and the glossary live in the epic, not in every ticket (see *Write for three readers*).

Brevity is a feature: a scannable ticket gets picked up; a wall of text gets skipped. **The test: would a teammate skimming this understand why it matters and what done looks like, without you in the room?** You are writing for a person who will act, not documenting your own exploration.

Enumeration vs. narrative: a worked example

Same ticket, two ways. The first is the trap; the second is the target.

**❌ Enumeration trap** (dense, machine-facing, reads as an exploration dump):

> **Context:** `processPayment()` calls `chargeCard()` then `recordLedgerEntry()`, but the two aren't in a transaction, so a crash between them leaves a charged card with no ledger row. Reproduced in staging; see `PaymentService.kt` flow. Affects retries via `RetryQueue`. > > **Suspect Code:** > - `service/PaymentService.kt:142`, `processPayment()`, no transaction wrapper > - `service/PaymentService.kt:160`, `chargeCard()` call site > - `service/PaymentService.kt:168`, `recordLedgerEntry()` call site > - `dao/LedgerDao.kt:55`, insert that never runs on crash > - `queue/RetryQueue.kt:30`, replays the whole method, double-charges > > **Acceptance Criteria:** `processPayment()` wraps charge + ledger in one transaction · rollback on ledger failure · retry does not double-charge · `LedgerDao.insert` covered by test · `RetryQueue` idempotency test added · metric emitted on rollback

**✅ Narrative target** (prose-first, human-facing, pointers woven in):

> **Context:** When a customer pays, we charge their card and then write a ledger entry, but those two steps aren't wrapped in a transaction. If the service dies in between (or the retry queue replays the call), the card gets charged with no matching ledger row, or charged twice. It's rare, but it's real money and it's silent: nothing alerts when the two drift apart. The fix is to make the charge-and-record pair atomic so one can't happen without the other. > > **Where to look:** `PaymentService.processPayment()` is where the charge and the ledger write happen sequentially without a transaction; the retry queue replays that whole method, which is what turns a gap into a double-charge. > > **Acceptance Criteria:** A failure after the charge never leaves a card charged without a ledger entry · a retried payment doesn't double-charge · both are proven by tests.

The second is shorter *and* clearer. The first makes the reader reconstruct the story from fragments; the second hands them the story and trusts them to open the code.

---

Write for three readers

Every ticket ships to at least three audiences, and it fails if any of them bounces:

• **A junior developer** must understand exactly what work to do without asking anyone. If a term would send them to Slack ("LAPI"? "the sweep"?), gloss it on first use: "the shared core database (LAPI)", "the hourly job". Prefer the plain description alongside the term of art ("both safe to call twice" next to idempotent).
• **A PM** must see how the work adds value. A standalone ticket opens with the product story, not the mechanics: what the user does, what goes wrong today, what this tic