write-ticket

name	write-ticket
description	Use when the user asks to create, edit, promote, drop, close, or durably capture a repository workflow ticket.
argument-hint	[topic/description for new ticket, or ticket path to edit]

Write Ticket

Target: $ARGUMENTS

Invariants

• Ticket conventions: Run ws-print-infra ticket-conventions.md (Bash) — path format, status flow, phase rules, stem rules, templates.
• Never Read a ticket file other than the current target — delegate any other ticket inspection to an Explore subagent.
• Epic tickets stay lightweight milestone boards; put detailed discussion, implementation phases, and slice-specific decisions in child tickets.

On: invoke

0. Classify category/status; apply judge: spec-gate only when the operation creates or moves a non-epic, non-research ticket into ready/.

1. If $ARGUMENTS references an existing ticket, read it.

2. Create (new ticket): a. Determine category from the topic. b. Choose initial status directory (idea/ for vague, todo/ for accepted actionable backlog — see judge: initial-status). c. Write the ticket using the frontmatter template and a clear problem/goal statement. Populate related-mental-model with the mental-model stems (filename without .md) that were consulted or arose during the current session — recovery hint for future sessions, not a validated link. Omit if no mental-model docs were relevant. d. If category is epic: write only scope, non-scope, child ticket board, cross-child decisions, and done/drop/defer criteria; reference existing/planned children and start a separate /write-ticket invocation for any child creation or child edit. e. If category is not epic and multiple phases are warranted (see judge: phase-need), structure as ### Phase N: <title> sections. Note inter-phase dependencies explicitly. f. After drafting, verify scope — see judge: ticket-scope. g. If status is ready/: add an entry to the ## Ticket Queue section in ai-docs/_index.md. Format: `stem` — one-line purpose and dependency notes.

3. Edit (existing ticket): a. Read the ticket first. b. Apply the requested changes (update phase, move status). c. If the target is an epic, keep edits at board level; for detailed implementation discussion, stop after the epic edit and start a separate /write-ticket invocation for the child ticket. d. For moves, git mv and add completed: date in frontmatter (→ .done/).

4. Phase content — for non-epic actionable tickets, carry everything from discussion that informs implementation: goals, constraints, rationale, rejected alternatives, suggested approaches (pseudo code, struct shapes, data formats, algorithm sketches). Leave to the plan: codebase-derived details (file paths, existing type reuse, integration patterns, function signatures, testing classifications).

5. Intent review — re-read the written/edited ticket against the preceding conversation:

   • Are decisions, constraints, rejected alternatives, and suggested approaches captured?
   • Does the ticket distort or omit any discussed intent?
   • If the ticket is an epic, did detailed implementation material stay out of the epic and get routed to a separate child-ticket invocation?
   • Fix gaps in-place; present a brief summary of corrections (or confirm nothing was missed).

6. Spec-stem check — skip epic and research: a. If status is todo/: preserve any existing spec: links as optional recovery hints; do not require stem discovery, do not fire judge: missing-spec-entry, and do not suppress the proceed prompt. b. If status is ready/: run ws-list-spec-stems <spec-file> on the relevant spec file(s) to confirm canonical stems. c. If status is ready/: ensure the ticket frontmatter spec: field lists every stem the phases implement. Add missing stems. If a phase implements behavior with no spec entry, see judge: missing-spec-entry. d. If status is ready/: remind that commits implementing this ticket should include a ## Spec section with those stems.

7. Commit — in a single Bash command, stage the ticket file (if git mv was used, git add <new-path> is sufficient) then commit: git add <file> && git commit -m "$(cat <<'EOF'\n...\nEOF\n)". Do not use git add -A. Chaining in one invocation minimizes interleave risk from concurrent sessions. If separate child invocations changed child tickets, those invocations own their own commits and outputs.

8. Proceed prompt — if the ticket is epic, do not suggest proceeding on the epic path; suggest creating, promoting, or proceeding a child ticket instead. Otherwise suggest /proceed as the next step after ticket authoring, unless judge: missing-spec-entry fired in step 6. Proceed routes to skeleton, plan, or implementation based on artifacts and session warmth.

   Emit the created ticket path as a completion artifact on its own line at the end of output, in the form Ticket: ai-docs/tickets/<status>/<stem>.md. For epics, also state that this path is a board artifact, not an implementation target. This allows callers (e.g. /proceed) to capture the path when invoking /write-ticket as a prefix stage.

Judgments

judge: spec-gate

Fires on any non-epic, non-research action that creates or moves a ticket into ready/. idea/ creation and idea/ → todo/ triage are ungated.

Identify the relevant spec file for the topic. Run ws-list-spec-stems <spec-file> (Bash) if a spec file is identifiable. If no relevant spec file exists, or no entry covers this behavior → stop. Name the uncovered behavior; suggest /write-spec before continuing.

judge: initial-status

Place in idea/ when the topic is exploratory or underspecified; place in todo/ when the scope and goal are accepted actionable backlog. todo/ spec: links are optional recovery hints; ready/ is the spec-gated implementation queue. When uncertain, prefer idea/ — triage is cheap.

judge: ticket-scope

Over ~200 lines is a soft signal; over 300 lines, act. First, prune plan-level detail (file paths, function signatures, integration specifics) — that belongs in a plan document. If an epic is still large, move details into child tickets; if a non-epic is still large, introduce an epic and split into child tickets.

judge: phase-need

Applies only to non-epic actionable tickets. Prefer more phases over fewer inside one cohesive child ticket; split unrelated reviewable units into separate child tickets. Single-component, single-concern work may be one phase.

judge: missing-spec-entry

Fires when a phase implements caller-visible behavior with no entry in any spec file. Stop the authoring flow, tell the user which phase surfaces un-specced behavior, and suggest /write-spec before continuing. Skipping this loses traceability for the new behavior and bypasses the canonical chain's spec-impact gate.

Doctrine

A ticket is the primary context-recovery artifact — a fresh session with no prior conversation must reconstruct the full decision context from the ticket and its linked plans. Every authoring choice optimizes for recoverability of intent: decisions, constraints, and rejected alternatives are captured at the point of writing so that downstream skills (/implement) never re-derive what was already settled. When a rule is ambiguous, apply whichever interpretation better preserves recoverability.