To Tickets
Break plan/spec/conversation into tickets — tracer-bullet vertical slices, each declaring tickets that block it. Publish per consumer repo's tracker conventions (AGENTS.md).
Reproducibility invariant
Full issue set, replayed in dependency order — features and bugfixes alike — must build roughly same application, regardless of who or what implements.
Issue stream = buildable spec. Every rule below serves this.
Self-containedness
Every outcome-shaping decision lives in issue itself, or durable docs it references — ADRs (writing-adrs), glossary terms (docs/glossary/). Never conversation context, tribal knowledge, implementer discretion.
Litmus test: two independent implementers could build meaningfully different things → ticket underspecified. Add decision to ticket, or record as ADR/glossary term + reference.
New vocabulary
Ticket introducing a domain concept declares it under ## Introduces — one slug per line, each linked as if the term file already existed (docs/glossary/<slug>.md, link-as-if-exists convention). Implementation creates the file; until then --lint reports broken cross-reference — that IS the enforcement, not a bug. The list = durable record of vocabulary the ticket adds.
Bugfixes = spec corrections
Never patch instruction ("change Y to X in file Z"). State correction to spec stream:
- Issue N implied X; implementation did Y; X correct. — or
- Issue N specified Y; Y wrong; X′ now correct.
Replay then builds X directly, not bug + patch. Bugfix reveals spec-level decision → ADR + reference from issue.
Reconciliation on completion
Ticket not finished until it reflects what was built. Before close: fold deviations, mid-session scope, decisions back into issue (or its ADR/glossary refs). Else replay builds first draft, not final state. documenting-decisions after-task step performs this.
Grilling gate
Tickets are load-bearing. No grilling session (docs/glossary/grilling-session.md) in context → stop, ask user: "No grilling session found — really skip?" Proceed only on explicit confirmation; note skip in parent issue/PR.
Process
1. Gather context
Work from conversation context. User passes reference (spec path, issue number/URL) → fetch, read full body + comments.
2. Explore codebase (optional)
Understand current code state. Titles/descriptions use glossary vocabulary (uvx disambiguate <term>); respect ADRs in touched area.
Look for prefactoring opportunities. "Make the change easy, then make the easy change."
3. Draft vertical slices
Break work into tracer bullet tickets:
- Each slice: narrow but COMPLETE path through every layer (schema, API, UI, tests) — vertical, NOT horizontal slice of one layer
- Completed slice demoable/verifiable alone
- Sized to one fresh context window
- Prefactoring first
Each ticket declares blocking edges — tickets that must complete first. No blockers → start immediately.
Apply litmus test to every draft: drafting decisions (interfaces, naming, sequencing trade-offs) go into ticket body, ADR, or glossary term — mark per documenting-decisions.
Wide refactors: exception to vertical slicing. One mechanical change (rename column, retype shared symbol), blast radius spans codebase — single edit breaks thousands of call sites, no slice lands green. Sequence as expand–contract. Expand: new form beside old, nothing breaks. Migrate: call sites in batches sized by blast radius (per package/directory), each batch own ticket blocked by expand — CI stays green, old form still exists. Contract: delete old form once no caller remains, blocked by every batch. Batches can't stay green alone → keep sequence, share integration branch, all block final integrate-and-verify ticket — green promised only there.
4. Quiz user
Numbered list. Per ticket:
- Title: short name
- Blocked by: gating tickets, if any
- What it delivers: end-to-end behaviour made to work
Ask:
- Granularity right? (too coarse/fine)
- Blocking edges correct — only genuine gates?
- Merge or split any?
- Any ticket failing litmus test — decision still only in conversation?
Iterate until approved.
5. Publish
One issue per ticket, dependency order (blockers first) → edges reference real issue numbers. Native blocking relation where tracker has one, else "Blocked by" section. Apply ready-for-agent label unless told otherwise — tickets agent-grabbable by construction.
Work the frontier: any ticket with all blockers done. Linear chain → top to bottom.
Do NOT close/modify parent issue.
Issue template:
Ticket prose: written and checked with the writing-prose skill if available, surface ticket — precision and understandability must not suffer.
No file paths/code snippets — stale fast. Exception: prototype snippet encoding a decision more precisely than prose (state machine, reducer, schema, type shape) → inline, note prototype origin, trim to decision-rich parts.
Work frontier one ticket at a time, clearing context between tickets.
