Appearance
The ticket lifecycle
You'll learn which states a ticket moves through, what happens in each, who acts, and which states are final.
Every ticket carries a workflow that fixes its states and transitions in code. Three workflows are for work — gaia_feature, gaia_bug, gaia_chore — and two are operational (gaia_deployment, gaia_verification; see Workflows & states). All three work workflows start in qualification, end in done or cancelled, and differ in one state and one shortcut.
Feature
A feature always passes review before it is done.
Bug
A bug has diagnose where a feature has spec: the root cause and a failing regression test come before any fix. Review is optional — a small fix may go from coding straight to done.
Chore
A chore is the feature shape with the bug's optional review.
What happens in each state
Every non-terminal state is claimable: the conductor set on the ticket may pick it up and start an agent on it. The agent runs the skill that owns that step, publishes a typed handoff comment, and ends its run by writing the next state.
| State | What the agent does | Where you come in |
|---|---|---|
qualification | reads the ticket, writes the acceptance criteria, classifies it (labels, sub-works), routes it to spec or diagnose | a ticket created through the /gaia skill or the cockpit's agent is qualified as it is created; one created by hand waits here for a conductor |
spec | writes the design, the implementation plan and the test plan | you confirm the plan (or ask for changes) in the agent's tab before it moves to coding |
diagnose | reproduces the bug, names the root cause, proposes the regression test | you confirm the diagnosis and the test |
coding | implements in an isolated worktree, drives the tests green, opens the merge request | you confirm the result and choose review — or, on a bug or chore, done |
review | an independent review of the change against the acceptance criteria: OK or Not OK | you confirm the verdict; OK → done, Not OK → back to coding |
done | — | terminal: the run is retired, the worktree is reaped, the ticket leaves the default lists |
cancelled | — | terminal: no reopen; start a new ticket if the work resumes |
Two transitions run backwards on purpose. requalify sends a ticket from spec, diagnose or coding back to qualification when the guard at a work state finds the qualification handoff missing, stale or contradictory. to_coding from review is the ordinary Not OK outcome.
Terminal means terminal
Neither done nor cancelled has an outgoing transition. A cancelled ticket stays cancelled and a done ticket stays done — the history stays honest, and follow-up work gets its own ticket.
Blockers, parents and branches
Blocked by. A ticket lists the tickets it waits for in blocked_by. It is not dispatched while any of them is still open, even if its own state is claimable.
Parent and sub-tickets. Tickets nest. A sub-ticket's base branch — the branch its worktree starts from and its merge request targets — is its parent's branch; a top-level ticket's base branch is the project repository's default branch. The base branch is computed, never set by hand.
Carrier tickets. To base several tickets on a long-lived integration branch, create one ticket whose branch_name is that branch (the name is fixed at creation and immutable afterwards) and hang the real tickets under it as children. The carrier is a container: nothing is implemented on it directly.
Runs have a lifecycle of their own
Each visit to a state is one run: claimed when the conductor gets the lease, running once the agent session is up, done when the state write retires it. expired is a claim that was never started before its lease ran out; failed is a dispatch that threw before the agent could work. Run a ticket follows one run from claim to done.
Next
- Create a ticket — the four ways a ticket comes into being.
- Handoffs & comments — what each step writes and where to read it.
- Workflows & states — every workflow, state and transition as a table.