/brief-spec

name: brief-spec
description: Use when the user wants to create a brief or spec for a feature before planning

Brief Spec

Conversational brief creation. The orchestrator loads this inline to co-create a brief with the user before dispatching to gaia-planner. The brief you write here is the contract you will audit the plan against: **you own the resulting plan -- its tasks and its acceptance criteria** -- and the planner produces it *for you to check*, not to approve on your behalf.

DB is the source of truth (read this first)

Briefs live in the Gaia substrate database (`~/.gaia/gaia.db`). They are created and mutated through the `gaia brief` CLI -- never by writing files on disk. The DB row IS the brief: there is no `brief.md`, no `<status>_<slug>/` directory, no frontmatter on disk. When in doubt, there is no file to write -- there is a CLI command to run.

**Execution follows authority.** The orchestrator co-creates the brief and may use its trusted Gaia CLI lane for bounded reads and user-confirmed `new`/headless `edit`/`set-status`/AC writes. `gaia-operator` remains the alternative for batching or operational separation. Destructive deletion is outside the direct lane. The orchestrator owns the questions, confirmation, and content whichever executor carries the command.

If you find code, docs, or skills that still describe a filesystem layout under `.claude/project-context/briefs/`, that is legacy: flag it in `cross_layer_impacts` -- do not edit it as a side effect of a brief task.

Cuando llegas aquí

El orquestador cargó esta skill porque la conversación entró en Cerrar: el usuario y él han acordado varias cosas y es momento de materializarlas. No estás aquí porque la petición superó un umbral de tamaño. Estás aquí porque hay acuerdos que capturar.

Tu trabajo: 1. Resumir los acuerdos que ya emergieron en la conversación previa -- no re-descubrirlos desde cero. 2. Preguntar sólo lo que falte para convertir los acuerdos en AC reproducibles (evidence types, surface type). 3. Materializar el brief en la DB con `gaia brief new --headless`, y presentarlo al usuario para validar.

Process

1. **Ask questions** -- Target gaps, not completeness:

• **Surface type** (always, before AC): Is this a UI a human uses, an API,

or a background job? Determines valid evidence types for the ACs.

• What problem does this solve?
• What constraints matter? (cloud, performance, security, timeline)
• How will you verify each AC yourself? (reproduce steps, not just "it works")
• What artifact do you want to review after execution?

(log file, screenshot, JSON snapshot, HTTP response, diff)

• If this failed silently, what symptom would you look for?
• What is explicitly NOT in scope?

One question per round via AskUserQuestion. Stop when each AC has a declared evidence type and every question above has an answer or an explicit "N/A".

2. **Create the brief in the DB (headless)** -- Run through the trusted Gaia CLI lane:

   gaia brief new --headless \
     --title="<human title>" \
     --status=draft \
     --surface-type=<ui|api|job|cli> \
     --objective="<1-3 sentences>" \
     --context="<project constraints>" \
     --approach="<high-level strategy, 3-5 sentences>" \
     --out-of-scope="<explicit non-goals>"

The slug is derived from `--title` (kebab-case). The CLI writes a row to the `briefs` table and prints the slug back. **Do not write any file in `.claude/project-context/briefs/`.** No directory, no `brief.md`, no frontmatter on disk. The DB row IS the brief.

`--status=draft` is the canonical entry point. Move it to `open` only when the user is ready to plan against it.

3. **Add Acceptance Criteria** -- ACs are rows in the `acceptance_criteria` table, added one at a time with `gaia brief ac add` per AC:

   gaia brief ac add <slug> \
     --id=AC-1 \
     --description="<user observation>" \
     --evidence-type=<command|url|playwright|artifact|metric> \
     --evidence-shape='<free-form string or JSON>'

Do not predeclare a repository-relative artifact such as `evidence/AC-1.txt`. During execution, persist the actual result with `gaia evidence add`; Gaia stores small results inline and larger blobs below `~/.gaia/evidence/`, then returns the canonical record/path.

Remove one the same way, dispatching `gaia brief ac remove <slug> --id=AC-1`. The shapes per evidence type are under "Evidence Types" below; the `## Acceptance Criteria` section that `gaia brief show` renders is the human summary of these rows.

4. **Confirm with the user** -- run `gaia brief show <slug>`, which prints the full row. Read it back and ask: "Does this capture what you want?" When confirmed, suggest dispatching to gaia-planner.

How to update a brief

For a single field, run the headless patch -- scriptable, no editor:

gaia brief edit <name> --headless \
  --field=<objective|context|approach|out_of_scope|description|title|surface_type> \
  --content="..."

The interactive form, `gaia brief edit <name>` (no `--headless`), opens the full body in `$EDITOR` -- it needs a human at a terminal, so it is never the form to dispatch; use the headless form always in this flow.

How to change status

Run `gaia brief set-status <name> <new-status>`. The CLI validates the state machine and rejects illegal transitions:

draft -> open -> in-progress -> closed -> {archived, open}

Examples:

gaia brief set-status my-feature open          # ready to plan against
gaia brief set-status my-feature in-progress   # work has begun
gaia brief set-status my-feature closed        # AC verified
gaia brief set-status my-feature archived      # closed -> archived
gaia brief set-status my-feature open          # closed -> reopened

There is no "rename the directory" step. Status is a column.

How to delete a brief

Dispatch gaia-operator to run `gaia