Writing tickets
An AI agent does the build, so the ticket is the plan it works from and the standard we check its pull request against. Writing tickets is everyone’s job, not just the product manager’s.
What goes in a ticket
Section titled “What goes in a ticket”A ticket has eight sections:
- Why
- Solution
- Program design
- Diagram
- Back pressure
- Evidence
- Observability
- Rollout & rollback
Small tickets don’t need every section filled in at length; use your initiative.
Describe the problem, who has it, and what solving it is worth to the client or the business. Two or three sentences is enough.
Solution
Section titled “Solution”Say what we’re going to do, and how.
Program design
Section titled “Program design”What are the significant architectural design changes? New concepts, classes,
detail about where the change will be made and the shape of it. Are you adding
three new LangGraph nodes, or dropping a god function into a new utils
folder? Decide here, before the agent decides for you.
Diagram
Section titled “Diagram”Show what we’re doing as a diagram. We suggest Mermaid: it’s plain text, so it lives in the ticket and the agent can read it. Small tickets don’t need a diagram; use your judgement. If a ticket has one, the PR that delivers it should reference it.
Back pressure
Section titled “Back pressure”How will the agent know when it’s wrong? List anything that makes it correct itself without a person stepping in: tests, types, evals, rules files. See back pressure for more.
Evidence
Section titled “Evidence”How will we know it works before release? Describe the proof you’ll show: the demo, the test results, the eval scores. It should answer “give me irrefutable proof that this works”.
Observability
Section titled “Observability”How will we know it keeps working, and that it hasn’t broken anything else? Describe the metrics, alerts and cloud agents that will watch it after release.
Rollout & rollback
Section titled “Rollout & rollback”How will we roll it out safely, and how can we roll it back quickly? Deploying covers feature flags and how to test risky changes on staging.
Template
Section titled “Template”Copy this into the description of a new Linear issue:
## Why
_What's the problem, who has it, and what is solving it worth?_
## Solution
_What are we doing, and how?_
## Program design
_What are the significant architectural design changes? New concepts, classes, detail about where the change will be made and the shape of it._
## Diagram
_A Mermaid diagram of what we're doing. Skip it for small tickets._
## Back pressure
_How will the agent know when it's wrong? Tests, types, evals, rules files._
## Evidence
_How will we know it works before release? Demo, test results, eval scores._
## Observability
_How will we know it keeps working and hasn't broken anything else?_
## Rollout & rollback
_How will we roll it out safely, and how can we roll it back quickly?_