Handoffs & comments

You'll learn what the agent writes on a ticket at each step, how to read it, and how to add a comment of your own.

GAIA steps do not talk to each other in memory. Each one publishes a comment on the ticket — Markdown, with a type — and the next step reads it. Those typed comments are the handoffs. For you they are the record of what was decided and why, in the order it happened.

The comment types

The type is free text on the control plane; these are the conventional values every GAIA skill uses:

Type	Written by	What it holds
qualification	the qualification step (or the /gaia create skill)	the acceptance criteria, the classification (feature / bug / chore), the work:* labels, whether a browser scenario is required, a provenance hash of the description
spec	the spec step	the design decisions, alternatives rejected, risks, and how each acceptance criterion will be met
plan	the spec step	the implementation plan as a checkbox list
test	the spec step	the test plan — which checks gate the change, and an honest statement when there is no runtime to test
debug_diagnose	the diagnose step (bugs)	the reproduced defect, the root cause, the regression test to write first
acceptance	the coding step	the acceptance criteria with a PASS/FAIL per criterion and the command, result and commit behind each
scenario	the coding step, when a browser walkthrough applies	the concrete path a human can click through
summary	every step, at its end	where the work stands: outcome, evidence, links, the one next action
comment	anyone	free text

Guards use them too: a work state whose latest qualification handoff is missing, stale or contradicts the ticket is sent back to qualification rather than worked on a bad basis.

Reading them in the cockpit

Open a ticket in gaia ui. The Overview tab leads with the latest summary — the fastest answer to "where is this?" — and the latest spec and plan. The Comments tab lists every comment newest first, rendered as Markdown, with its type. When a step asks you for a decision, it does so in its agent's terminal tab, not in a comment; the comment is the durable record of what was decided.

Markdown, always

Comment bodies and ticket descriptions are stored in the gaia_rich text format, a CommonMark Markdown format. Write Markdown.

HTML disappears without an error

gaia_rich strips raw HTML. An HTML body is accepted by the write, stored, and then renders as an empty comment. Nothing errors — the handoff simply is not there when the next step looks for it. Every GAIA skill therefore names format: gaia_rich explicitly and writes Markdown.

Writing a comment yourself

From the shell, write the body to a file and send it as a gaia_comment with the type you mean:

cat > note.md <<'EOF'
Please target the `release/2026-09` branch for this one — the customer's freeze starts Monday.
EOF

jq -n --arg id "<ticket uuid>" --rawfile body note.md \
  '{data:{type:"gaia_comment--gaia_comment",
          attributes:{body:{value:$body,format:"gaia_rich"},gaia_comment_type:"comment"},
          relationships:{ticket_id:{data:{type:"gaia_ticket--gaia_ticket",id:$id}}}}}' > comment.json

gaia dropsh --auth-profile pm create gaia_comment --bundle gaia_comment --data @comment.json --dry-run
gaia dropsh --auth-profile pm create gaia_comment --bundle gaia_comment --data @comment.json

The agent reads every comment on the ticket at the start of each step, so a note like this reaches the next run.

Next

• The ticket lifecycle — which step writes which handoff.
• Comment types — the same table as reference, with who reads each.
• Using gaia ui — the Overview and Comments tabs.