# 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 dynamic **workflow graph** against a fresh sandbox
clone of your repo. For a full explanation of how the graph is planned, how
to read node statuses live, and how cancelling and retrying work, see
[Alchemist Tickets](/docs/guides/alchemist-tickets).

## What the workflow graph does

Each ticket's graph is planned at dispatch time for that specific piece of
work. A straightforward fix might plan a short chain of research, implement,
review, and land; a larger feature typically adds security-check and
verification nodes before anything lands. You watch each step live from the
ticket's detail view.

The main node kinds you will see on a "build" ticket:

- **Research / investigation.** Read-only exploration of your codebase, logs,
  or the web. Nothing changes here -- this is how agents ground the plan in
  how your app actually works today.
- **Implement.** The agent writes the change in an isolated sandbox on a
  dedicated git branch, committing checkpoints as it goes. A large plan may
  fan out across multiple implementation nodes.
- **Review / security / verification.** Independent nodes that read the diff
  (not write it): a correctness review, an adversarial security check, and a
  check that the ticket's definition of done actually holds, including runtime
  checks against a running instance of your app.
- **Land.** Merges the finished branch into your project's base branch and
  triggers a deploy.

There is also an **investigate** mode: a read-only research flow (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.

You can also answer from inside an AI client using the `reply_to_ticket` tool
on the [Alchemist Cloud Tickets MCP](/docs/guides/alchemist-mcp-server). Never
paste a credential or secret value into a reply -- if the agent asked for a
key, use the secure submission link from its question instead.

## 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.