Writing a ticket

The ticket is the whole input. Everything Styre does downstream is derived from it, and nothing later can go back and ask you what you meant — so this is the page worth reading twice.

What Styre actually reads

You control exactly three things: the title, the description, and one label.

• The title is the only text every stage sees. Write it as a standalone claim, not a label. “Retry the checks fetch on 5xx” beats “Checks bug”.
• The description is read once, by the design stage. Everything after that works from the plan design produced, not from your words.
• The label — Bug, Feature or Improvement — decides your branch prefix and nothing else.

The ticket is read once, at the start

Styre fetches the ticket when the run begins and never looks at it again — the run works from its own record, not from the tracker. Editing a ticket mid-run changes nothing. If you need a change to land, stop the run and start it again.

The template

## What

One to three sentences, in the imperative. Name the files and symbols you
actually know. If you know the offending code, quote it with a file:line ref.

## Why

The evidence. A failing command, a log line, a measured number, a link. If you
assert a defect, prove it here. Also name the obvious alternative fixes you
already ruled out and why — otherwise design will re-derive them.

## Scope

**IN**

* Bullets, not checkboxes — see the warning below.
* Only as precise as your evidence supports.

**OUT**

* What this ticket deliberately does not do, and why.
* Name the sibling ticket that owns the excluded work, if there is one.

## Acceptance criteria

- [ ] Self-contained, observable, specific. Each line becomes one test.
- [ ] Your project's gate — build, tests and lint all pass.

## Refs

* Sibling tickets, design docs, links to the evidence.

A checkbox anywhere is an acceptance criterion

Styre scans the whole description for - [ ] items. It has no concept of sections, so a checkbox in your Scope block becomes an acceptance criterion, gets a test written against it, and is gated on.

Use - [ ] under Acceptance criteria and nowhere else. Use * bullets everywhere else.

Also worth knowing: indentation is ignored, so nested checkboxes flatten into peers, and - [x] is treated exactly like - [ ] — pre-ticking a box does not skip it.

Acceptance criteria decide the outcome

This is the part that matters most. Each checklist item becomes one test, written before the work starts, that must fail on today’s code and pass when the work is done.

Four rules.

1. Always write a checklist

If your description contains no checkboxes at all, the entire description is treated as a single coarse criterion. One vague test then stands in for the whole ticket. It is the worst result available to you, and it is the default if you forget.

2. Each criterion must stand on its own

The step that writes your tests sees the criterion text and nothing else — not your What, not your Why, not the other criteria. Anything that depends on context elsewhere in the ticket is unverifiable.

Instead of	Write
Handle the error case.	parseFoo("") returns an empty array rather than throwing.
The message explains the problem.	When the file was deleted, the message says it was created and since removed, and tells the agent not to search for it.
Retries work.	A 503 from the checks API is retried three times with backoff before the run gives up.

A good test: cover up the rest of the ticket. Can someone still write the test?

3. Name an observable output, with a specific value

returns 200 is not a criterion — a stub that returns 200 {} satisfies it without doing any of the work. Say what the response contains. For anything numeric or algorithmic, state the actual value the fixed code must produce, not a property that would hold either way.

4. It must be false today

Every criterion needs to be something that fails on current code for the right reason. If it already passes, it is not testing your change.

What a vague criterion actually costs

Styre checks its own tests. A test that only pokes at a surface — one a trivial stub would satisfy — gets rejected and rewritten. If the same criterion produces a weak test twice, the run stops and asks for a human.

That chain is the most common way a run ends up back in your lap, and it starts with one woolly checkbox. The fix is upstream, in the sentence you write.

End the checklist with your project’s real gate, whatever that is:

- [ ] `npm run build`, `npm test` and `npm run lint` all pass.

Scope, and how much you need to know

Always write Scope OUT. It is a decision, not a discovery — you can say “don’t touch the auth module” without knowing anything about the code. It costs nothing and it is your only defence against a change that sprawls.

Write Scope IN only as precisely as you have earned. If you have investigated, name files and quote lines. If you have not, describe the outcome you want and stop there.

You are not expected to know the files

The design stage reads your repo before it plans — that is its job, and it is told not to guess paths it can look up. A ticket that names no files at all is completely fine.

A confidently wrong path is worse than no path: it is barely checked, and it will quietly pollute the plan. Name paths only when you have actually verified them.

Do not list the test files that prove your criteria, either. Styre names and writes those itself.

Two things that work differently than you would expect

A richer ticket does not buy a shorter pipeline. Design always runs at full strength, no matter how well-specified the ticket is. More detail improves the plan; it never skips a stage.

One ticket, one concern. Two unrelated problems in one description produce a plan that solves both halfway. Split them, and use Refs to keep the pieces connected.

Before you hand it over

• The title is a standalone claim.
• Exactly one label: Bug, Feature or Improvement.
• There is a real checklist under Acceptance criteria.
• There are no checkboxes anywhere else.
• Every criterion reads and verifies with the rest of the ticket covered up.
• Every criterion names an observable output and its expected value.
• No criterion would be satisfied by a trivial stub.
• Every criterion is false on today’s code.
• The last criterion is your project’s build, test and lint gate.
• Any file path you named, you have verified. Naming none is fine.
• Scope OUT is present.
• Why cites real evidence and rules out the obvious alternatives.
• One concern.

---

Next: The run loop — what Styre does with the ticket once you hand it over.