clarify · diff
git:20261105.9da51a7 to git:20261107.629412d
26 added, 11 removed. Audit A to A.
---
name: clarify
- description: Resolve the open questions of a spex spec one at a time, each with options and a recommended answer, and write the answers and the record changes back into requirements.yaml. Use when the user says "clarify", "spex clarify", "answer the spec questions", or when spex check reports REQ-QUESTION-OPEN. With --auto (nobody to ask) it takes every recommended option and marks it by: default.
+ description: Resolve the open questions of a spex spec, each with options and a recommended answer, and write the answers and the record changes back into requirements.yaml. Use when the user says "clarify", "spex clarify", "answer the spec questions", or when spex check reports REQ-QUESTION-OPEN. With "auto", or auto: true in .spex/config.yaml, a decider subagent answers every question (by: agent, with evidence and confidence) and nobody is asked; the user reads the answers at /spex:approve.
disable-model-invocation: true
- allowed-tools: Bash(node ${CLAUDE_PLUGIN_ROOT}/scripts/spex.mjs *)
+ allowed-tools: Bash(node ${CLAUDE_PLUGIN_ROOT}/scripts/spex.mjs *), Agent
---
# spex clarify
`SPEX` = `node ${CLAUDE_PLUGIN_ROOT}/scripts/spex.mjs`, from the repo root.
## Steps
1. `SPEX check <dir> --json`: the `REQ-QUESTION-OPEN` findings are the questions a person
still owes. Then read `requirements.yaml` once for gaps the records leave open: scope,
users and roles, data and its lifetime, interfaces, errors and rare cases, numbers
(latency, size, limits), security and privacy, dependencies, out of scope, terms.
- 2. If the brief does not say *why* the feature exists, that is the first question.
+ 2. If the spec does not say *why* the feature exists, that is the first question.
3. Add at most 5 new questions per run, picked by impact × uncertainty. Ask only when the
answer changes what gets built; otherwise write your call as an assumption in the record's
`rationale` and move on. Each question: `ask`, `why` (one line), 2 to 5 `options` with one
- `recommended: true`.
- 4. Ask the user one question at a time: the question, why it matters, the options, your
- recommendation. Wait for the answer before the next one.
- With `--auto`, or when there is nobody to ask: take the recommended option and write
- `by: default`.
- 5. Write each answer into `questions[]` (`answer`, `by: human | default`), then change the
- records the answer touches: text, scenarios, new records, retired assumptions.
+ `recommended: true`. Nothing open and no gap you can name: change nothing, say so and go
+ to step 7. Every question you add sends its approved records back to `draft`, and gate 1
+ runs again.
+ 4. Get the answers:
+ - Conversation: ask the user one question at a time: the question, why it matters, the
+ options, your recommendation. Wait for the answer before the next one.
+ - Auto mode (`auto` or `--auto` among the arguments, in any position, or
+ `.spex/config.yaml` has `auto: true`): nobody is asked. One `spex:researcher` per
+ question that needs outside facts, in parallel; then one `spex:decider` for the file
+ with every open question (the ones you added in step 3 too), the `spec:` document,
+ `SPEX show <dir> --inherited` and the code a question points at. Never tell it that a
+ question is the user's: there is none. Per question it returns answer, evidence,
+ confidence, needs. Every verdict → `by: agent` with `evidence` and `confidence`.
+ `needs` a file or a section, or a new question the verdicts or the facts raise → give
+ it and ask the same agent again. The user reads the answers at `/spex:approve`.
+ 5. Write each answer into `questions[]` (`answer`, `by: human | agent | default`, and
+ `evidence` and `confidence` for an agent), then change the records the answer touches:
+ text, scenarios, new records, retired assumptions.
- A record that was `approved` goes back to `status: draft`; gate 1 runs again.
- A record that is already on `main` is never edited (`SPEX check --base main` refuses it):
write a new record with `relationships: [{type: supersedes, target: <old id>}]`.
- Every new or changed record points at its source: `source: Q3`.
6. `SPEX check <dir>` until it has no error. Read the `fix` texts.
7. `SPEX report <dir> clarify --status <done|concerns> --summary "…"`, with one
`--question` for anything a person still has to settle.
## Reply
At most 15 lines. `STATUS:` first. One line per question: id, the answer, who answered
- (`human` or `default`), and the records it changed.
+ (`human`, `agent` with the evidence, or `default`), and the records it changed. Last, the
+ output of `SPEX next <dir>`, as printed.
+
+ The NEXT block is copied as `SPEX next` printed it, the two rules included, never rewritten
+ into prose or shortened, and it does not count toward the line cap.