Ticket Builder

Turn an unstructured brief into a ticket that agents can execute without the author in the room.

The point is not documentation. It is making the author's intent survive contact with agents who lack their context. An agent that reads a ticket-builder ticket should be able to do its step correctly, know exactly where to stop, and know the difference between a decision it may make and one it must escalate.

When this applies

The user drops a brief describing sequenced work across several agents or models. It usually contains a purpose, a rough numbered sequence, opinions about who does what, and one or two absolute rules stated with force. It is almost never complete, and the gaps are the valuable part — they're where an agent would otherwise guess.

The shape of the work

1. Read the brief and the existing context (files, decisions, prior work)
2. Find the genuine forks — resolve them with the user, before any agent runs
3. Write the ticket + the vision constraint + a decision-log entry
4. Agents execute steps; a reviewer checks each output before the next step starts
5. Every ruling the user makes gets logged so nothing is re-litigated

Stop after step 3 unless the user says otherwise. The ticket is the deliverable; executing it is a separate act with its own approval.

Read context before writing anything

Look at what already exists: the project's own conventions, its decision log or equivalent, prior work of the same kind, naming patterns. A project's existing conventions outrank any generic template, including the ones in this skill. If the repo already has a way of recording decisions, use it rather than importing a new schema.

You are looking for two things specifically: what the brief assumes exists, and what contradicts it.

Find the forks first

The most valuable thing you do is catch, before any agent runs, the places where the brief could be read two ways that lead to materially different outcomes.

In the source case, the brief said "summarize sessions 1–9" while the architecture file said the level had 8 sessions. Every downstream step depended on which was true. Resolved in one question; would have cost an entire agent run to discover later.

Ask these one at a time, with a recommendation. A fork is worth asking about when the two readings produce genuinely different work. Everything else — naming, ordering, formatting, file locations — you decide yourself. Over-escalation is its own failure: an author who must answer twelve questions to get a plan has not been helped.

Record the answers as STEP 0 at the top of the ticket, plus a decision-log entry. They then bind every downstream step, and no agent reopens them.

Keep the author's rulings and your own assumptions in separate lists. STEP 0 has three parts for this reason: what the author ruled, what you assumed to keep moving, and what is still open and blocking. The failure this prevents is subtle and common: a brief is nearly complete, you fill two small gaps to make the plan coherent, and you file them under "scope calls made by the author." Three steps later an agent cites your inference as the author's decision and nobody questions it, because it is sitting in a decision log with their name on it.

The test is literal: did they say it, or answer a question you asked? If not, it goes in the assumptions list — where it still guides the work, but stays cheap to overturn and is never quoted back at them as their own ruling. Assumptions are not a lesser output; an unmarked one is.

When something genuinely can't be resolved without inventing an answer, say so and stop releasing the next step — set the ticket's status to blocked and state it at the top. A plan that reads execute-ready with open questions in a footnote will be executed.

Writing the ticket

Use assets/ticket-template.md as the starting structure. The parts that carry the weight:

Why this exists. One short section stating the problem the ticket solves, in the author's own terms. Agents reason better about a step when they know what it's for; it's also what lets a reviewer catch a step that has drifted from the goal.

Standing rules. Applies to every step, every agent. Typically: vision is binding, no guessing, never self-mark work as approved, cite every claim to a real source, update only what needs updating, log the handoff.

Briefs usually contain one or two rules stated with unusual force — "no exceptions," "that's a hard rule," "we got in trouble for that before." Lift those out of the prose and into the standing rules as their own numbered entries, and name the pressure that will try to break them: a deadline, a tempting shortcut, an agent's own judgment that this case is different. A rule written as "security has read-only production access, no exceptions — this cannot be waived by any step owner, including under deadline pressure" survives the moment it's tested. The same rule left in a paragraph does not, because the person breaking it is always the person who thinks their situation is the exception.

One section per step, each with:

Scope lock deserves its own emphasis. The most common agent failure is not doing too little — it's helpfully doing the next step too. In the source case, STEP 2 had to say "design at session level only, do NOT write the curriculum files" because writing them early would have destroyed the entire purpose of the plan. State what must not happen and why it would hurt.

Blocker register. A table of genuine blockers: who raised it, when, what the fork is, and its resolution. Blockers stay visible until ruled on. This is where "no guessing" becomes real rather than aspirational.

Step ledger. One row per step: owner, status, handoff artifact, date. The ticket's own progress tracker, and the first thing a resuming agent reads.

The vision constraint

Write it as a separate file, and log it as a real decision. If it lives only in the ticket's prose it reads as preamble; as its own rule with a decision ID behind it, an agent treats it as binding. Use assets/vision-constraint-template.md.

It says: agents may suggest improvements, bounded by the vision. They may not add, remove, merge, reorder, or optimize away anything specified, substitute their judgment for a stated instruction, or silently resolve an ambiguity by guessing.

Include the other half or the rule backfires: cosmetic choices are the agent's own call. Wording, file naming, section ordering, formatting. Without this, agents escalate everything and the author becomes the bottleneck for trivia.

Reviewing agent work

Every step's output gets reviewed before the next step starts, ideally by a different model than produced it. This is where most of the value shows up — in the source case, review caught a deleted source still being cited fifteen times, a session that re-taught earlier material, a tool that didn't exist as a product, and two silently upgraded status labels.

references/review-playbook.md has the recurring failure modes and how to catch each one. Read it before reviewing any step output.

Three habits matter more than the checklist:

Verify, don't accept. Re-derive the finding from the actual file, not from the agent's reasoning about it. An agent's explanation of why its work is correct is not evidence that it is.

Attribute honestly. When you find a problem, say whether it came from the agent or from the ticket. In the source case, two findings traced to ambiguous instructions the ticket author had written — including one the reviewer wrote himself. Saying so is not politeness; the ticket gets fixed instead of the agent getting blamed for following it, and the same defect stops recurring.

Check your own findings against the vision before raising them. Some will be enforcement of rules the author already set. Others will be your own taste. Label which is which and let them dismiss the second kind cheaply. An author who asks "is this actually within my vision?" is right to ask.

Log every ruling

Each fork the user resolves becomes a decision entry — what was decided, why, what it supersedes, what it affects. Without this, the same question resurfaces at every step, and an agent three steps later has no way to know the answer was already given.

Two things worth recording beyond the decision itself:

• How the error got in. "An agent cited a prior blueprint as a source rather than as a floor" is reusable diagnosis; "the session was wrong" is not.
• Standing lessons. When a defect could recur in a different form, state the general rule. An item on a scope list is not evidence a usable product exists. Scope lists record intent, not availability.

Writing dispatch prompts

Steps often get handed to agents in other tools. See references/dispatch-prompts.md. The core: front-load the binding rules and scope lock into the opening third, point at the ticket rather than restating it, name the files to read, and always include stop conditions.

Things that go wrong

The ticket contradicts its own source. An agent rewrites a file it was told to compile from, then keeps citing the deleted content. Before a step deletes or replaces a file, check whether anything cites it — preserve the cited part as an appendix if so.

Later steps re-do earlier work. When a step builds on prior material, require it to state in one line what it does that the prior material didn't. If it can't, the step's design is wrong. This makes the guard automatic instead of relying on someone noticing.

A resource that doesn't exist. Something named in a brief is not proof it's available. Anything named only in a scope list must resolve to a real, verified thing before a step depends on it.

Status inflation. Agents resolve ambiguity upward — "proposed" becomes "confirmed" when nobody said which it was. Any decision assigning something a role must also state its status explicitly.

Premature completion. An agent marks its step Done when the exit criteria require the author's ruling. Check exit criteria literally before accepting a Done.