Ticket Writing

---
name: Ticket Writing
description: >-
  Write tickets someone else can actually pick up. Use whenever a bug, feature, chore, or
  security finding is being filed, rewritten, triaged, or groomed, in Linear, Jira, or GitHub
  Issues. Also fires on "file a ticket for this", "turn this thread into an issue", "write
  acceptance criteria", "is this ticket ready?", "this ticket is unworkable". Ships templates
  for bugs, features, and security findings, plus a checker that scores a draft and names the
  missing fields.
license: MIT
metadata:
  author: Amini
  version: "1.0.0"
---

# Ticket Writing

A ticket is a handoff of context. Whoever picks it up, maybe you in three weeks, maybe a new
hire, maybe an on-call engineer at 02:00, should be able to reproduce it, verify it, and close
it without reopening a chat thread that has since scrolled away.

The bar is one question: **could someone who was not in the conversation start work in under
five minutes?**

Most tickets fail that bar for boring reasons. The reporter had the failure in front of them
and wrote down the part they found surprising, which is rarely the part that locates the cause.
This skill fixes the shape of the ticket, not the writing style.

## Read these as needed

- `references/house-rules.md` is the only file you have to edit to retarget this. Tracker,
  team routing, house style, build identity, confidentiality. **Read it first**, because
  team routing and style rules change what you write.
- `references/bug-tickets.md`, `references/feature-tickets.md`, and
  `references/security-findings.md` cover the three shapes in depth.
- `references/severity-and-priority.md` is the two-axis rule that stops the arguing.
- `references/ready-and-done.md` has the ticket-level Definition of Ready and Definition of Done.
- `references/anti-patterns.md` is the list of things to stop doing, with what to do instead.
- `templates/` has the three templates as paste-ready markdown.
- `examples/deep-research-timeout/` is a real ticket as filed (30/100), the same ticket
  rewritten (100/100), both checker reports, and a gap-by-gap breakdown of what each missing
  field cost.

## Pick the shape first

Three shapes, and they fail differently.

| Shape | Fails because | Template |
| --- | --- | --- |
| Bug | Under-specified. Nobody can reproduce it. | `templates/bug.md` |
| Feature | Specified but untestable. "Done" gets decided by argument in review. | `templates/feature.md` |
| Security finding | Neither of the above. Needs CVSS, a sanitized proof of concept, and closure with proof. | `templates/security-finding.md` |

A chore, a dependency bump, or a config tweak is a small feature. Use the feature template and
a checklist instead of Gherkin.

## How to write one

1. **Pick the shape and the owning team.** File under the team that owns the work, not the team
   that noticed. Cross-team work goes to the owner with blocked-by and blocks relations for the rest.
2. **Write the title as behaviour plus condition.** `[Team or Component] <what breaks> <under
   what condition>`. The condition is the part people leave out and the part that locates the bug.
3. **Fill the template.** Every field, or an explicit statement of why it does not apply.
   "Not reliably reproducible, 1 in 20, trace from the one capture below" is a filled field.
   A blank one is a question you have deferred onto someone else.
4. **State impact separately from severity.** Impact sets priority. Severity is technical
   damage. See `references/severity-and-priority.md`.
5. **Run the checker.** Fix what it flags, then read it once as someone who was not there.
6. **Link the thread, do not paste it.** Extract the facts first.

## The rules that carry most of the weight

**One ticket per thing.** If the "and" in your title joins two unrelated failures, split it.
Bundled tickets get half-fixed and closed. One cause with several symptoms is still one ticket,
and listing all the symptoms is what points at the shared cause.

**Quote the error.** Verbatim, in a code fence, with the status code. "It failed" is not
searchable. A gateway 504, an app 500, and a proxy 404 point at completely different layers.

**Give the build identity.** Commit, tag, or image sha. Container names are opaque hashes and
prove nothing. This is also how you close a ticket honestly: the fix is not done when it is
merged, it is done when the sha carrying it is the one running.

**Put a timezone on every timestamp.** Distributed team, UTC logs, dashboards rendering local
time. Without a timezone, three readers search three different log windows.

**Describe the problem, not the fix.** "Add a retry button" has already made the design
decision and hidden the real failure. Sometimes the answer is a retry button. Sometimes the
answer is that the request should not have failed.

**Reproducibility rate is data.** 10 out of 10 and 1 out of 10 point at different root causes.
If you cannot reproduce it, say so explicitly. That is diagnostic information, not a gap.

## Check the draft

```bash
python3 scripts/ticket_check.py ticket.md
python3 scripts/ticket_check.py ticket.md --type feature   # skip detection
python3 scripts/ticket_check.py tickets/*.md --strict      # non-zero exit below 85
cat ticket.md | python3 scripts/ticket_check.py -
```

Stdlib only, no install. Paths are relative to this skill's directory.

It detects the shape from the headings, checks the fields that shape needs, and reports missing
fields, vague language, unfilled template placeholders, timestamps with no timezone, severity
and priority stated together, procedural Gherkin, happy-path-only acceptance criteria, and
anything that looks like a live credential pasted into a proof of concept. Then a score out of
100.

Rough calibration: a structured but under-specified ticket, which is the most common case,
lands around 30. A copied template with the headings still empty is clamped to 35 and labelled
as unfilled, so it cannot read as ready. Above 85 is pick-up-able.

The score is a smoke alarm, not a grade. It cannot tell whether the steps actually reproduce,
whether the acceptance criteria describe the right behaviour, or whether the impact claim is
true. Passing it is the floor.

**One hard failure.** Anything matching a live credential costs 25 points on its own and should
be fixed before the ticket is saved, not before it is submitted. Redact it and rotate the key.

## Reviewing someone else's ticket

Run the checker, then check the one thing it cannot: does the ticket describe a problem, or a
solution someone has already picked? Send it back against `references/ready-and-done.md` if it
fails the Definition of Ready. That is not obstruction. It is cheaper than finding the gap
halfway through the implementation, and much cheaper than finding it in review.

Be specific about what is missing and why it costs something. "Needs more detail" is the same
anti-pattern the ticket is guilty of.

## What not to do

Do not invent the missing fields. If the reporter did not give you a request ID, a timestamp,
or a reproduction rate, the ticket says so and asks. A confidently wrong environment sends
someone to the wrong logs, which is worse than an empty field.

Do not paste real credentials, tokens, session cookies, or user data into a ticket, including
into a security proof of concept, on the reasoning that the tracker is internal. Exports,
screenshots, and integrations all leak.

Do not restate release-stage gates in a ticket. Ticket-level Ready and Done are about one
ticket. Whether the whole product can advance to beta or GA is a different document, owned by
the engineering owner. Link it.