/ticket-writing

name: ticket-writing
description: Use when creating or drafting tickets or issues, or when standardizing ticket output for a project

Ticket Writing

The formula for tickets humans can read in ~15 seconds. The what and why go at the top; the how and evidence go in a comment. One Story per brief or theme; consolidate rather than inflate.

Core principle

A Story is readable by a non-technical stakeholder in 15 seconds. This means: plain English, active voice, value-oriented title, high-level description. All implementation detail and verification evidence lands in the first comment -- never in the description -- so the description reads clean.

Story template

**Title:** verb + outcome, plain English, no jargon, 80 chars max.

**Description fields:**

| Field | Content | |-------|---------| | *Objective* | 1-2 sentences: what it achieves and why (high level). | | *What it covers* | 3-5 bullets of scope -- what, not how. | | *Acceptance criteria* | Checklist "Done when..." -- verifiable, not vague. | | *Links* | Brief slug / repo if applicable. |

**Evidence** -- first comment only, never in description: commit hashes, verbatim commands, anything reproducible.

Subtask template

**Title:** short action phrase, plain English. **Description:** one line -- what it is / done when X.

Process

1. **Map to a brief or theme.** One Story = one brief or coherent chunk of work. If the work spans multiple unrelated concerns, split into separate Stories. If it is one theme with sequential steps, use Subtasks.

2. **Write the title last.** Draft the Objective and What-it-covers first; the title compresses naturally from those. If the title needs jargon to be precise, the description is missing context.

3. **Write the Acceptance Criteria as done-when checks.** Each AC is a checkbox that a person (not a CI system) can verify. Vague ACs get pushed back: "migrated" means what? "History intact" means no commit lost.

4. **Move all evidence to the first comment.** After the ticket is created, post a comment with: commit hashes, commands run verbatim, output snippets. This keeps the description clean for stakeholders and the evidence auditable for engineers.

5. **Adapt to the project's board conventions.** Do not create Epics if the team does not use them. Respect the active Sprint. Use existing Labels and Components, not invented ones. Check 2-3 existing tickets before creating the first one.

6. **Consolidate, do not inflate.** Prefer fewer well-scoped tickets over many granular ones. If two Subtasks share all context, make one Subtask. If a Story has one Subtask, fold the Subtask into the Story.

Style rules

• Plain English, active voice. Write "Move repositories to Bitbucket" not

"Repository migration to Bitbucket platform will be performed."

• Title is value-oriented: what the user or team gains, not the mechanism.
• No implementation detail in the description. "Configure DNS records" belongs

in a Subtask description or the evidence comment, not the Story Objective.

• Subtasks are ultra-light: one-line description, action-phrase title.
• Fields: Assignee, Status (To Do / Done), Sprint -- set these before saving.

See `examples.md` for real tickets from the AOS migration project.

Anti-patterns

• **Evidence in the description** -- pollutes the readable summary; goes in

the first comment instead.

• **Title is the mechanism, not the outcome** -- "Run git push for all repos"

is a task; "Migrate AOS repositories to Bitbucket" is a Story.

• **One Subtask per command** -- over-granular; group related steps into one

Subtask with a multi-step description.

• **Inventing Epics or Labels** -- inconsistency with the team's board adds

noise. Adapt to what is already there.

• **Vague Acceptance Criteria** -- "Works correctly" is not verifiable.

"History intact" is verifiable only when it means "no commit missing from git log --oneline."