# Alchemist: Working with Tickets

Write effective tickets, follow the pipeline, and review the work the agents ship.

---

A ticket is one unit of work. When you open a ticket, the platform spawns an agent run that executes a structured pipeline against a fresh sandbox clone of your repo.

## The five passes

A "build" ticket flows through five passes in order. You can watch each one live from the ticket's detail view.

1. **Plan.** A planner reads the ticket, explores the repo (fanning out read-only sub-agents over the codebase and docs), and writes an implementation plan. This pass is read-only. No files change.
2. **Implement.** The agent picks up the plan and edits the code, running tests as it goes. This is the longest pass and accounts for most of the cost of a ticket. A large plan may be split into ordered pieces, each implemented in its own fresh session.
3. **Review.** A separate agent re-reads the diff, runs tests, and either approves it or sends targeted feedback back to Implement. Most tickets pass on the first attempt. Some loop once.
4. **Security.** A dedicated pass audits the diff for vulnerabilities, secret leaks, auth gaps, and tenant-isolation mistakes.
5. **Docs.** Project documentation affected by the diff (README, CLAUDE.md, topic docs) is updated and the diff is tidied before the branch merges.

There is also an **investigate** mode: a single read-only research pass (no code changes, no deploy) that reads the codebase, and the web when relevant, and posts findings back. Use it for "how does X work?" or "where would I change Y?" questions.

## Answering agent questions

Sometimes an agent pauses on something only you can answer: a business-logic ambiguity, a missing credential, a design choice that isn't in the ticket. When that happens the run moves to **Awaiting input** and you'll see a banner until you reply. If you've opted in, you also get an email.

Open the ticket, find the **Pending question** card, and type your answer. The agent resumes within a few seconds and continues from where it paused. Long-running tickets can pause and resume multiple times. There's no penalty for letting one sit.

## Tips for good tickets

- **Describe the outcome, not the implementation.** "Users should be able to sign in with Google" beats "Add an OAuth handler to /api/auth/google."
- **Reference concrete URLs or files when you have them.**
- **Don't pre-decompose.** One ticket per outcome works better than a ticket per file. The agent handles cross-file changes natively.
- **Include reproduction steps for bugs.** "Click X, type Y, see Z" is worth more than a paragraph of theory.

## Writing tickets for AV domain logic

The agent knows software. It does not know your line card, your labour rates, or how your service tiers work. Put that context in the ticket rather than assuming it.

Weak: "Add margin calculation to the quote page."

Strong: "On the quote page, add a margin column. Margin is (sell price minus cost) divided by sell price, shown as a percentage to one decimal. Flag any line under 22% in amber and under 15% in red."

*AVCodex · Your AV expertise. Amplified by AI.*