Shaping a Ticket

Shaping a Ticket

An agent pays for every file it opens. A ticket written for a person makes it read 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 once per issue.

/lean-agent:shape-ticket writes or refines an issue in the shape below.

Search before filing

Search the open issues and open pull requests for the same area or problem. If an issue fits, the new item joins its Covers checklist with its own check under Done when. If an open pull request already covers it, say so there. File new only when it is separate. One ticket per repository.

Size

One agent pass is one ticket: whatever one agent can finish in one focused pass. That is one pull request or a short stack, in one repository, on the same code area or the same kind of fix, reviewable together. Split only when it is too big for one pass. Security fixes stay separate unless they are the same fix.

The shape

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

The Risks row

Most of what a review finds falls into categories you can name before a line is written. Keep only the lines that apply.

• Untrusted input reaching a URL, a header, CSS, HTML, SQL or a log. 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. Never silently.
• 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.

Spec review

For a ticket that touches more than one area, or anything in Risks, one fresh agent on the cheap model reads the ticket and the code it names and lists what could go wrong. What it finds goes into Risks and Done when. It reads. It does not build.

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.

Why batching matters

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. A docs pass fixed 197 wrong or stale claims in about ten batched pull requests for roughly 8 thousand tokens a finding. README section 0 has the detail.