Recipes: tickets that work

Each recipe is a ticket you can paste into the Create ticket form and adjust. It names the Type and Mode to pick, what a typical run leaves behind, and the knobs worth turning once you have seen one run. For why a ticket is written this way, see Write a ticket an agent can finish.

The ticket text goes in the description. Replace anything in backticks with your own.

Fix a reported bug

Type: Task. Mode: Auto. Working directory: the repo.

Bug: exporting a list with a comma in a title produces a broken CSV
(the title splits into two columns).

Reproduce: create an item titled "a, b" and click Export.
Done when: the export quotes fields correctly, a regression test covers
the comma case, and the existing test suite passes.

A typical run: a failing test first, then the fix, both on the ticket’s branch; the run ends In Review with the diff, its commits and the checks it ran.

Tune it: paste the stack trace or the log line instead of describing it. If the agent fixes the symptom in one caller, say “find every caller” in the ticket, or send it back with a line comment on the diff (Review and merge).

Add tests to an untested module

Type: Task. Mode: Auto.

Add unit tests for `src/billing/invoice.py`. Cover the rounding rules,
the empty invoice and a refund. Do not change the module's behaviour;
if a test exposes a bug, stop and ask before fixing it.
Done when: coverage of that file is at least 80% and the suite passes.

A typical run: one new test file, a coverage figure in the final checks, and a question on the ticket if a test exposed a bug.

Tune it: turn on the code quality gate so the coverage floor is enforced rather than promised (Hold agents to a quality bar).

Build a feature you want to shape first

Type: Task. Mode: Interactive plan (or Plan for a text plan).

Add a dark mode toggle to the settings page. It follows the system setting
until the user picks one, and the choice survives a reload.
I care about: where the toggle sits, and that no page flashes white on load.

A typical run: the ticket parks in Pending Action with an interactive plan. You annotate what you want changed, click Send to agent, and Accept plan once it is right; the agent then implements it and agrees a set of verification checks with you on the way.

Tune it: list what you care about, as above: the plan spends its detail there. See Review and annotate a plan.

Refactor under a size budget

Type: Task. Mode: Plan.

`server/routes.py` is 2,400 lines. Split it into modules by resource
(users, billing, admin) without changing any route's behaviour.
Done when: no module is over 600 lines, every route still answers the same,
and the test suite passes.

A typical run: a text plan naming the new modules, then one commit per module moved.

Tune it: with the quality gate set to warn or block, the ratchet stops the agent making any function worse on the way. Ask for “one commit per step” if you want to review the moves one by one.

A codebase wide rename as a Loop

Type: Loop. Uncheck Enabled in its schedule once it is created, so it only runs when you click Run now.

Rename `UserAccount` to `Account` across the repo. One subticket per
top-level package (api, worker, web, cli), each renaming inside its own
package only. Then one agent node summarises what each strand changed,
and a human approval gate before anything is merged.

A typical run: the Loop pipeline section drafts the graph from the text: four subticket nodes that run at the same time, a join, a gate. Each run dispatches four child tickets on their own branches and parks on the gate for you.

Tune it: open the pipeline with Expand and adjust nodes before the first run. For a change that is really one coupled edit, a plain Task is cheaper; see Which tool when.

A weekly dependency audit

Type: Loop, made from the Report library.

On the Create ticket form, open the Report library, pick Dependency audit and choose Schedule.

A typical run: every Monday at 09:00, a new run writes a markdown report of outdated and vulnerable packages with a suggested upgrade order, attached to the run as an artifact.

Tune it: change the day and time in the Loop’s Schedule tab. See Run a repo report for the other reports and for adding your own.

A research report with no repo

Type: Task. Mode: Auto. Working directory: leave it empty.

Compare three hosted Postgres providers for a 50 GB database with
point-in-time recovery: price per month, restore time, regions in the EU.
Deliver a one-page report with a comparison table and your recommendation,
with a link for every number.

A typical run: the ticket runs in a scratch directory with nothing to merge, and ends with the report attached as an artifact.

Tune it: name the format you want (a table, an HTML page, a PDF). If the agent needs a site that asks you to sign in, it asks you to do that step on the ticket’s computer; see Let an agent use a browser.

A 3D printed part

Type: Task. Mode: Auto. Working directory: empty, or a repo for your models.

Design a wall bracket for a 25 mm round rail: two screw holes for 4 mm
screws, 5 mm walls, printable without supports. Model it in OpenSCAD
so I can tweak the dimensions, and attach the STL.

A typical run: a .scad source and an .stl attached to the ticket, shown in the 3D viewer with Open in Bambu Studio.

Tune it: give measurements, not adjectives. See Print a 3D model.

Upgrade until the suite is green, as a Goal

Type: Goal.

Objective: Upgrade the app from Django 4.2 to 5.1.
Done when: The full test suite passes on 5.1 and no deprecation warning remains.

A typical run: each iteration takes one bite (a batch of deprecations, one broken module), adds a row to the ledger and reports whether to continue. The Goal stops when the objective is met, when it reports it is blocked, or when a cap is reached.

Tune it: set the caps before the first run. See Run a Goal until it is done.

Review a branch before you merge it

Type: Command. Command: security-review.

Or, on a ticket that is already In Review, click Request review in its Git integration section.

A typical run: findings graded by severity, posted on the ticket; each can be sent to the agent to fix.

Tune it: turn on the automatic review lane to have every ticket reviewed as it reaches In Review (Review and merge).

Write a ticket an agent can finish, for what makes a ticket work.
Which tool when, to pick the type and mode.
Split big work into subtickets, when one ticket is not enough.