Comment types

A gaia_comment carries a Markdown body (format gaia_rich) and a free-text gaia_comment_type, default comment. The GAIA skills agree on the values below; the cockpit matches them exactly. The narrative is on Handoffs & comments.

Type	Written at	By	Read by	Holds
comment	any time	anyone	the next step's agent, people	free text
qualification	qualification (or by the /gaia create skill at creation)	the qualification step	the entry guard of every work state; the spec/diagnose step	acceptance criteria, classification, work:* labels, reproduction (bugs), scenario_required, a provenance hash of the description, handoff_version
spec	spec	the spec step	the coding step; people confirming the plan	design decisions, rejected alternatives, risks, acceptance mapping
plan	spec	the spec step	the coding step	the implementation plan as a checkbox list
test	spec	the spec step	the coding and review steps	the test plan — which checks gate the change
debug_diagnose	diagnose	the diagnose step (bugs)	the coding step	the reproduced defect, root cause, the regression test to write first
acceptance	coding	the coding step	the review step; people	each acceptance criterion with PASS/FAIL and its command, observed result and commit
scenario	coding, when a browser walkthrough applies	the coding step	the review step; people	the concrete browser path: user, URL, actions, expected result
summary	the end of every step	the step owner	people first — the cockpit's Overview leads with it	outcome, evidence, links, the one next action

Where the cockpit shows them

• Overview leads with the newest summary, then the newest spec and plan when present, then the description. The match on the type is exact — a typo in the type means the comment is listed under Comments but not surfaced on Overview.
• Comments lists every comment newest first, each under a — <type> · <author> · <created> marker.
• gaia ui <id> | cat prints the same content in section order.

Writing one

The type is a plain attribute on the create envelope; the format must be named:

{
  "data": {
    "type": "gaia_comment--gaia_comment",
    "attributes": {
      "body": { "value": "…Markdown…", "format": "gaia_rich" },
      "gaia_comment_type": "comment"
    },
    "relationships": {
      "ticket_id": { "data": { "type": "gaia_ticket--gaia_ticket", "id": "<ticket uuid>" } }
    }
  }
}

gaia_rich strips raw HTML, so an HTML body renders as an empty comment. Handoff types are reserved by convention for the steps that own them — a hand-written qualification comment would be taken at face value by the guard that reads it.

Next

• Handoffs & comments — reading and writing them in practice
• gaia dropsh — the create verb and the pm profile
• The ticket lifecycle — which step writes what