krzysztofsurdy/ticket-writer

Ticket Writer

Pick the right ticket type, then fill in only the fields that type demands. A story is not a bug; an epic is not an initiative. Each type has a distinct audience, scope, and definition of done -- mixing them produces vague, unactionable tickets that bloat backlogs.

Core Principles

| Principle | Meaning | |---|---| | Type drives structure | The type decides the required fields -- never use a single template for everything | | Outcomes over outputs | Describe the change the work creates, not the activity performed | | Small enough to finish | Stories and subtasks fit a sprint; epics fit a quarter; initiatives span multiple quarters | | Testable acceptance | Every story, subtask, and bug has acceptance criteria that a reviewer can verify | | Context, not prose | Prefer tables, lists, and labelled sections over paragraphs -- readers skim | | One ask per ticket | If a ticket has two unrelated goals, split it |

---

Type Hierarchy and Selection

Tickets form a hierarchy. Pick the highest level where the work still has a single, coherent purpose.

Initiative  (multi-quarter strategic outcome)
  Epic      (quarter-scale goal, one product area)
    Story   (sprint-scale user-visible value)
      Subtask  (implementation slice of a story)
    Bug     (defect against current behaviour)
    Issue   (anything else -- chore, spike, question)

When to Use Each Type

| Type | Audience | Scope | Typical Duration | Key Question | |---|---|---|---|---| | Initiative | Execs, product leadership | Cross-team strategic goal | 1-4 quarters | What outcome do we want for the business or users? | | Epic | Product, engineering, design | Single product area, multiple stories | 1 quarter | What capability or experience are we delivering? | | Story | Dev team, QA, PM | One user-facing change | Fits in a sprint | As a [user], what can I now do? | | Subtask | One developer | Technical slice of a story | Hours to 1-2 days | What specific implementation step does this cover? | | Bug | Dev team, QA | A deviation from intended behaviour | Fix-sized | What is broken, and how do I reproduce it? | | Issue | Dev team | Chore, spike, question, tech debt, docs | Variable | What needs attention that isn't user-facing work? |

Type Decision Tree

1. Is this a deviation from intended behaviour? -> Bug
2. Is this a strategic goal spanning multiple teams or quarters? -> Initiative
3. Is this a large body of work that needs to be broken down but belongs to one product area? -> Epic
4. Is this user-visible value that fits in a sprint? -> Story
5. Is this an implementation slice of an existing story? -> Subtask
6. None of the above (chore, spike, investigation, tech debt, question)? -> Issue

---

Workflow

Phase 1: Type Selection

If the user provided a type as an argument, use it. Otherwise present a selectable menu (use AskUserQuestion or the platform's equivalent interactive prompt) listing the six types with their one-line descriptions from the table above. Never dump the full table as plain text -- keep the menu compact.

If the user's intent is clear from context (e.g., they said "write a bug report" or "create an epic for checkout redesign"), skip the menu and confirm the inferred type with a single yes/no prompt.

Phase 2: Load the Type-Specific Reference

Read the matching reference file for the selected type:

| Type | Reference | |---|---| | Story | references/story.md | | Subtask | references/subtask.md | | Issue | references/issue.md | | Bug | references/bug.md | | Epic | references/epic.md | | Initiative | references/initiative.md |

Each reference contains:

• The required fields
• The optional fields
• A field-by-field questionnaire (questions, options, follow-ups)
• The output template
• Quality checks specific to that type

Phase 3: Run the Questionnaire

Ask only the questions the reference lists for the selected type. Follow these rules:

1. Batch compatible questions (3-4 per prompt) when using an interactive menu tool. Use free-text prompts only when the answer is genuinely free-form (title, description, reproduction steps).
2. Skip optional fields silently if the user says "skip" or leaves them blank -- do not add empty placeholders.
3. Follow-up on ambiguous answers -- if the user says "it's slow", ask "slow compared to what, and by how much?"
4. Never invent facts. If the user cannot provide environment info, reproduction steps, or metrics, leave those fields out and note the gap in a ## Open Questions section rather than fabricating values.

Phase 4: Assemble the Ticket

Use the type's output template. Apply these universal formatting rules:

• Title: Imperative mood for stories/subtasks/issues ("Add password reset via email"), descriptive for bugs ("Payment confirmation email not sent after successful charge"), outcome-oriented for epics/initiatives ("Reduce checkout abandonment by 30%").
• Body: Markdown with section headings. No emojis unless the user explicitly requests them.
• Labels: Suggest labels based on type and content (e.g., bug, severity:high, area:checkout).
• Links: Leave placeholders for parent epic / related tickets / PRs rather than inventing IDs.

Phase 5: Quality Check

Before showing the final output, run the checks listed in the type's reference file. Common failure modes to catch:

| Symptom | Fix | |---|---| | Acceptance criteria describe implementation ("implement X service") | Rewrite in terms of observable outcomes ("when user does X, system does Y") | | Bug has no steps to reproduce | Mark as "Open Questions" and ask the user to provide them | | Epic has no success metric | Add a metric or downgrade to a story | | Story doesn't name a user ("we need to...") | Rewrite with a concrete persona ("As a returning customer, I want...") | | Initiative lists features instead of outcomes | Reframe key results as measurable changes, not shipped features | | Subtask is larger than its parent story | Split the story or merge the subtasks |

Phase 6: Deliver

Show the final ticket to the user in a code block so they can copy-paste it. Then offer:

1. Edit a field
2. Change the type (if the content no longer fits)
3. Write a related ticket (e.g., a story under the epic just written)
4. Done

---

Quick Reference: Field Matrix

Which fields are required (R), optional (O), or not used (-) per type.

| Field | Story | Subtask | Issue | Bug | Epic | Initiative | |---|---|---|---|---|---|---| | Title | R | R | R | R | R | R | | User persona | R | - | O | O | O | O | | User story sentence | R | - | O | - | O | - | | Problem statement | O | - | O | R | R | R | | Acceptance criteria (Given/When/Then) | R | R | O | R | O | - | | Steps to reproduce | - | - | - | R | - | - | | Expected / actual behaviour | - | - | - | R | - | - | | Environment | - | - | - | R | - | - | | Severity | - | - | - | R | - | - | | Priority | O | O | O | R | O | O | | Scope / out of scope | O | - | O | - | R | R | | Success metrics | - | - | - | - | R | R | | Key results | - | - | - | - | O | R | | Objective | - | - | - | - | O | R | | Milestones | - | - | - | - | O | R | | Parent link | O | R | O | O | O | - | | Child list | - | - | - | - | O | O | | Definition of done | R | R | O | R | O | - | | Technical notes | O | O | O | O | O | - | | Estimate | O | O | O | O | O | - | | Dependencies | O | O | O | O | O | O |

---

Integration with Other Skills

| Situation | Recommended Skill | |---|---| | Writing the PRD that the stories will flow from | product-manager | | Designing the architecture behind an epic | architect | | Writing acceptance criteria and test plans for a story | qa-engineer | | Planning sprints and setting sprint goals | scrum | | Tracking initiatives as part of a delivery plan | project-manager | | Writing the commit and PR for a story once implemented | pr-message-writer | | Kicking off the ticket workflow after writing | ticket-workflow |

---

Reference Files

| Reference | Contents | |---|---| | story.md | User story fields, INVEST checklist, Given/When/Then acceptance criteria, full template and example | | subtask.md | Subtask fields, parent linkage rules, technical acceptance criteria, Definition of Done guidance | | issue.md | Generic issue template for chores, spikes, tech debt, questions, and docs tasks | | bug.md | Bug report fields, severity vs priority matrix, environment capture, reproduction rigor | | epic.md | Epic fields, problem statement, success metrics, in/out of scope, milestones, child stories | | initiative.md | Initiative fields, OKR alignment, objective and key results, outcome vs output, epic roll-up |