/brief-spec

name: brief-spec
description: Use when the user wants to capture a feature as a brief or spec before planning it -- "arma un brief para esto", "necesito un spec antes de planear", "definamos el alcance de la feature", "write a brief for this", "spec this out before we plan it".

Brief Spec

Brief Spec is how the orchestrator turns what it agreed with the user into a brief: an objective, observable acceptance criteria, the decisions taken, and the boundaries, ready for gaia-planner. The brief is the contract the plan is audited against, so the orchestrator owns its content and owns checking the plan that comes back.

The database is the brief

A brief is a row in `briefs` plus its child rows (`acceptance_criteria`, `brief_decisions`, `milestones`), written and read only through `gaia brief`. What `gaia brief show` prints is a rendering of those rows: nothing on disk is authoritative and there is no file to write. Code or docs that still describe `.claude/project-context/briefs/` are legacy -- flag them in `cross_layer_impacts` instead of editing them as a side effect.

**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/decision 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.

Cuando llegas aquí

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

1. Resumir los acuerdos que ya emergieron -- no re-descubrirlos desde cero. 2. Preguntar sólo lo que falte para que cada AC sea observable, o dejarlo marcado como pendiente de aclarar. 3. Materializar el brief con `gaia brief new --headless` y presentarlo al usuario para validar.

Process

1. **Ask only for the gaps, never the obvious**, one question per round via AskUserQuestion: surface type (ui, api, job, cli); the problem it solves; the constraints that matter; for each AC, what an agent would observe when it holds and what symptom would show it failing silently; what is explicitly out of scope. For substantial work the gaps include the hard parts the user may not have considered, and once, at capture, offer the goal the feature serves beyond itself. Stop when every AC is observable or explicitly marked unresolved (step 4).

2. **Create the brief:**

   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>" \
     --out-of-scope="<explicit non-goals>"

The slug is derived from the title. `draft` is the review window; move it to `open` only when the user is ready to plan against it.

3. **Add each acceptance criterion as an observation:**

   gaia brief ac add <slug> --id=AC-1 --description="<what an agent observes>"

An AC says what is true and visible when the work is done, precisely enough to disagree with ("p95 under 200ms on /search", not "fast"), and visible to an agent: a state it reads, an output it runs, a page it drives. An AC only the user can observe is the exception, written as theirs with its reason -- a judgment of taste, or a check they asked to make -- because it becomes a gate the user judges (`gaia-planner` step 5). It does not prescribe the proof: which test, command or rubric shows it is the planner's proposal, authored as gates. Fixing a mechanism here, before anyone has read the code, turns a guess into a requirement. Set `--evidence-type` / `--evidence-shape` only when the user asked to see the result a particular way ("a screenshot of the dashboard"). Evidence itself is recorded during execution with `gaia evidence add`, never as a path declared in advance.

4. **Mark what is not settled.** Where the user has not decided something the plan depends on, write `FALTA ACLARAR: <question>` into the field it affects (the AC description, the objective, the approach). The planner does not plan past such a mark: it returns `NEEDS_INPUT` with the list, and planning resumes once the answer replaces the mark (`gaia brief ac edit` or `gaia brief edit --headless`). `gaia brief verify` reports every field and AC still carrying the mark (`unresolved_clarification`, advisory like its other checks); it matches the literal text, so spell it exactly.

5. **Record decisions in their own field:**

   gaia brief decision add <slug> --text="<the decision>" --rationale="<why>" \
     [--supersedes=<id>]

A decision that changes an earlier one names it with `--supersedes`, so `gaia brief show` lists the current answer apart from the one it replaced. Appending a new paragraph to `approach` instead leaves two answers to the same question with nothing saying which one holds.

6. **Confirm.** Run `gaia brief show <slug>`, read it back, ask "Does this capture what you want?", and when confirmed dispatch gaia-planner.

Maintaining a brief

| Need | Command | |------|---------| | Patch one field | `gaia brief edit <name> --headless --field=<objective\|context\|approach\|out_of_scope\|description\|title\|surface_type> --content="..."` | | Edit an AC in place | `gaia brief ac edit <name> --id=AC-1 --description="..."` | | Change status | `gaia brief set-status <name> <status>` (`draft -> {open, closed, archived}` -- the last two are the shortcut for a brief small enough to skip planning -- then `open -> in-progress -> closed -> {archived, open}`; `archived` is terminal; illegal transitions are refused) | | Read | `g