Writing Tickets

Writing Tickets

Write clear, actionable tickets grounded in actual codebase investigation. Produces output readable by PMs and actionable by engineers.

Announce at start: "Using writing-tickets to [write/rewrite] [ticket type] for [topic]."

Inputs

Extract from the user's message:

• Ticket type: initiative, epic, story, spike, or rewrite of existing ticket
• Topic or ticket key: what to write about, or existing ticket to rewrite
• Mode: --autonomous (no user input, self-grills, runs to completion) or interactive (default)
• Output: --direct (write to Jira without previewing) or present-first (default)
• Scope: --with-subtasks (also break into child tickets after approval)

If ticket type is ambiguous, ask: "Should I write just the [epic/story], or also break it into sub-tasks?"

Flow

digraph writing_tickets {
    rankdir=TB;
    node [shape=box];

    start [label="Invoke skill" shape=doublecircle];
    detect [label="1. Detect mode\n(interactive vs autonomous)"];
    investigate [label="2. Investigation\n(references/investigation.md)"];
    grill [label="3. Grill phase\n(references/grilling.md)"];
    write [label="4. Write ticket\n(references/writing-style.md)"];
    review [label="5. Self-review against\nwriting-style rules"];
    present [label="6. Present to user\nor write to Jira"];
    subtasks [label="7. Offer to break\ninto sub-tasks/spikes"];

    start -> detect -> investigate -> grill -> write -> review -> present -> subtasks;
}

Phase 1: Detect Mode

• Interactive (default): Ask questions, present drafts, wait for approval
• Autonomous (--autonomous): Self-grill, self-answer via investigation, run to completion. See references/autonomous.md
• Direct (--direct): Skip preview, write to Jira immediately after internal review

Phase 2: Investigation

Adaptive depth by ticket type. Always check related tickets/PRs/docs. See references/investigation.md.

Phase 3: Grill

Calibrated Q&A by ticket type. See references/grilling.md.

Phase 4: Write

Apply writing style rules. See references/writing-style.md.

Phase 5: Self-Review

Before presenting, verify:

• Problem statement leads, not solution
• Key results / end state defined
• Situated in hierarchy (parent initiative/epic, sibling tickets, dependencies)
• Related tickets, PRs, docs linked
• No hallucinated file paths, method names, or model relationships
• Acceptance criteria are non-redundant and testable
• Unresolved questions explicit with numbered list
• Spike tickets drafted for unknowns neither user nor investigation could resolve
• No section overlap: stories/tasks must NOT have an "In scope" section (that content belongs in "Desired behavior" + "Technical approach"). Use "Out of scope" for guardrails only.

Brevity checks (initiatives and epics):

• No "Current State" / "How it works today" section — that's docs or child stories
• No completed/done tickets listed in the description — they're history
• No multi-option analyses for already-decided questions — state the decision only
• No per-workstream acceptance criteria in initiatives — those go in child epics
• No user stories in initiatives/epics — those go in child tickets
• Decisions from comments/conversations surfaced in "Key decisions" section
• "Open questions" contains only genuinely unresolved questions (answered ones moved to Key decisions)
• 2-minute rule: a PM or engineer skimming this for the first time can understand problem, scope, decisions, and open questions in under 2 minutes

Phase 6: Output

Default: Present the draft in conversation. Ask: "Want me to create/update this in Jira?" --direct: Write to Jira without previewing. Jira unavailable: Present in conversation only. Note that Jira was unavailable.

Phase 7: Sub-Tasks

For epics and initiatives, after the parent ticket is approved:

• Offer to break into stories and/or spike tickets
• Each sub-task goes through phases 2-6 at its own depth level
• Spike tickets get minimal investigation (they exist to find answers)

Unknowns Handling

1. Ask the user first (interactive mode only)
2. If the user doesn't know: flag in the ticket under "Unresolved Questions"
3. If the unknown needs hands-on investigation: draft a spike ticket with clear experiment criteria
4. Autonomous mode: log assumption with confidence level (High/Medium/Low), surface all assumptions in a dedicated section

Graceful Degradation

Never fail because a tool is unavailable. Degrade gracefully, note what was skipped.

Sub-Agent Usage

Always use sub-agents for investigation, regardless of mode. This keeps the orchestrator's context lean.

Rules:

• Sub-agents do NOT spawn their own sub-agents (two-level only)
• Max 3 concurrent sub-agents
• Each sub-agent gets explicit instructions and returns structured findings
• Orchestrator synthesizes findings, never delegates writing the final ticket

After Grooming

When invoked after ticket-grooming, the grooming output is available in conversation. Use it:

• Grooming findings become investigation inputs (don't re-investigate what grooming already found)
• Grooming gaps become grill-me questions
• Grooming risk flags become acceptance criteria

Reference Files