Shape the Ticket

Shape the ticket for the agent

Section 0 of the method. Write each ticket so one agent pass finishes it with nothing else to read.

My issues were written for me, or for a developer: a problem, why it matters, a rough idea of the fix. An agent reads them differently. Every issue it opens costs it the issue, the linked issues, the repository rules and the code around the change, and a backlog of small issues about one area makes it read the same files again for each one. The expensive part of a ticket is not the change. It is everything around it.

The numbers, from one day on one project. A typical pull request cost 150 to 250 thousand tokens to build, 100 to 150 thousand for the adversarial review, and 30 to 100 thousand per fix round. For a small ticket, the fixed part of that, reading, building, reviewing, merging, is most of it. The same day, a docs pass fixed 197 wrong or stale claims in about ten batched pull requests for roughly 8 thousand tokens a finding. As 197 tickets with their own agent, review and CI run each, it would have cost more than ten times as much. That was an extreme case, because the findings were tiny, but it is the mechanism.

So the front half of the loop changes.

Refine before anyone starts. Spend a few days asking and revising while the plan is still moving. A ticket started early gets overtaken, and a third of that docs pass was fixing claims that drifted because the work moved faster than the plan.

Consolidate when you file, not later. Before filing anything, search the open issues for the same area or problem. If one fits, add the new item to its checklist with its own check. Merging later costs a whole triage pass; merging now costs one search.

One agent pass is one ticket. Anything an agent can finish in a single focused pass, one pull request or a short stack in one repository, the same code area or the same kind of fix, reviewable together, is one ticket. One ticket per repository. Security fixes stay separate unless they are the same fix. Split only when a group is too big for one pass, because a review stays sharp only on a focused diff, and that is where the reviews found real defects.

Write it so the agent needs nothing else.

Part	What goes in it
Goal	One sentence: what is true when it is done
Where	The files and code areas, so the agent does not search
Covers	The absorbed issues, as a checklist
Done when	Runnable checks: tests that fail before the fix and pass after, the preflight command, docs to update
Risks	The review's questions answered for this change, each with a check under Done when
Constraints	The repository rules that apply: contract version, public API, migrations, style
Out of scope	What not to touch

Foresee the review. Most of what the adversarial reviews found in a day fell into categories anyone could name before a line was written:

• untrusted input reaching a URL, a header, CSS, HTML, SQL or a log, where the hostile inputs are known in advance: //host, /\host, quotes, </style>, url(, control characters;
• a bound nobody stated, on rows, upstream calls, memory, time or a cache, and what happens past it, which must never be silent;
• two writes that must commit together, and what a crash in between or a second run does;
• two runs of the same thing overlapping;
• whoever already depends on this: published packages, stored data, defaults, a contract version;
• the real target environment, which a copy does not reproduce.

The Risks row is that list, answered for the change in hand, and only the lines that apply. For a bigger ticket, one cheap agent reads the ticket and the code it touches and lists what could go wrong before anyone builds. That is one agent reading, not building, and a fraction of a code review. The review after the code still runs, because the finder and the judge have to stay separate and some defects only exist in the real diff. It just finds less, which means fewer fix rounds, and each fix round was one of the costs above.

---

Home | Next: Triage inline, no agents