clarify

You run the clarify loop: find where the objective is silent or contradictory, resolve the few ambiguities that most change the spec, and surface the rest as flagged assumptions — so a human at Gate A ratifies a spec with no invisible gaps. You drive this from the Architect role; intake.sh start has already armed the intake sentinel, so the round budget, the ask↔record coupling, and the coverage floor are mechanically enforced (see The boundary below) — hold the discipline and the gates stay quiet.

The core rule — F1: the budget routes, it never drops

The round budget bounds how many times you interrupt the human, not how much of the objective you resolve. These are different things, and conflating them mechanically enforces under-elicitation on exactly the high-stakes specs this system exists to serve.

• Every eligible ambiguity is surfaced. The top items by Impact × Uncertainty get a human question within budget (interactive); every remaining eligible ambiguity becomes a flagged [ASSUMED · <category> · confidence:low|med] entry in ## Assumptions — there is NO CAP on assumptions.
• The budget therefore keeps human questions few (don't fatigue the human) while guaranteeing nothing is left unsurfaced. Zero residual [NEEDS CLARIFICATION] is the post-condition, reached by either a ## Clarifications answer or an ## Assumptions entry — never by silently dropping the ambiguity.
• The human may trigger another clarify round even at zero rounds remaining (intake.sh clarify <spec>) — intent-clarity outranks the quota. The budget only bounds agent-initiated questioning.

Question taxonomy — the canonical coverage set

Every unresolved point maps to exactly one canonical category. The categories are defined in ONE machine-readable source — harness/intake-categories.json (id + canonical name + cluster) — and this skill, the spec-reviewer, the spec template, and the deterministic coverage floor all defer to it, so the taxonomy can never drift across copies again. Use a category's canonical id as the AskUserQuestion header and as the disposition slug in the ## Deferrals ledger.

The set is broad by design and grouped into 12 clusters (read the enum for every id):

• Scope & Intent — what the system does / does not do, who it is for, "done" signals, competitive positioning
• Domain & Data — entities, persistence, migration, data quality, lineage, time/clock
• Interfaces & Integration — APIs, contracts/versioning, interoperability, eventing
• UX & Interaction — flows, accessibility (assistive + reduced-motion), responsiveness, motion, inclusivity
• Content & Brand — content design / information architecture, visual brand, content-source fidelity, copy
• Quality: Performance & Efficiency — latency, throughput, capacity, resource utilization
• Quality: Reliability & Resilience — availability, fault tolerance, recoverability, predictability
• Quality: Security — confidentiality, integrity, authn/authz, secrets, tenancy, privacy
• Quality: Safety — operational constraints, hazard handling, fail-safe, ML output safety
• Quality: Maintainability & Flexibility — modularity, testability, portability, scalability
• Operational & Lifecycle — deployment, observability, rollout/rollback, disaster recovery, cost
• Constraints, Risk & Governance — compliance/consent, licensing, data residency, supply-chain, mandated stack

Breadth is the SAFE direction: the floor checks presence, not adequacy, so a category that does not apply is one deliberately N/A — <reason> line (defaults are pre-fillable). Accessibility, the split reliability/availability/operability axes, and the broadened security/safety set are deliberate: a load-bearing infra/multi-agent system under-covers these if NFR is narrowed to "performance & scale".

Ranking — Impact × Uncertainty

Only unresolved categories are eligible (a category fully covered by an FR/SC/edge case, or marked N/A in ## Deferrals, is skipped). Score each eligible category on two axes, 1–3:

• Impact — blast radius if the answer changes: reshapes the architecture / many FR / the task graph (3), affects one story or a few FR (2), polishes an edge (1).
• Uncertainty — how silent or contradictory the objective is here: no signal (3), a hint but underspecified (2), mostly clear with a small gap (1).

Rank by the product, descending. Ask the top item first. Re-score after each answer — an answer often resolves or raises siblings and reorders the queue. Stop early when the top remaining product falls to a diminishing-returns threshold (≤ 2 — nothing both impactful and uncertain remains), even with budget left.

One-at-a-time protocol

loop:
  1. score eligible categories → rank by Impact × Uncertainty
  2. if queue empty OR top product ≤ 2 OR asked == budget:  break  → route the REST to ## Assumptions
  3. ask the single top-ranked question via AskUserQuestion (interactive only)
  4. record it as a "### Round N — <date>" entry in ## Clarifications, and PROPAGATE the answer into the
     live FR/SC/story text, removing the resolved [NEEDS CLARIFICATION] marker
  5. asked += 1 ; goto 1   (re-score — the queue may have changed)

Never batch unrelated questions. Asking and recording are coupled: step 4 (log and propagate) for round k must be on disk before round k+1 is asked — the clarify-gate denies the next ask otherwise.

Recording format (one entry per AskUserQuestion round; the ### Round N header is what the round counter keys on):

### Round 1 — 2026-01-15

- **Q (security):** How should users authenticate? → **A:** Session token. _(propagated to FR-003, SC-002)_

Option format: multiple-choice, 2–5 options, mapped to AskUserQuestion. Exactly one option marked (Recommended) and listed first (the safest/most conventional default); the tool's free-text "Other" is always available.

Interactive vs autonomous

• Mode: interactive — run the loop, asking via AskUserQuestion, within the round budget, one at a time. Route every un-asked eligible ambiguity to a flagged [ASSUMED …].

• Mode: autonomous — never ask (there is no human; the clarify-gate denies AskUserQuestion entirely, and an unattended ask would hang). For every eligible ambiguity — not just the top N — write a flagged assumption, decoupled from the budget entirely:

  - [ASSUMED · security · confidence:med] Authenticate via session token. **Chosen because** it matches
    existing flows with no new infra. **Discarded:** OAuth 2.0, API key. _(propagated to FR-003, SC-002)_

  Propagate each assumed answer into the live spec and clear the marker, so the spec is internally consistent — and the human at Gate A sees exactly what to ratify or overturn.

Coverage sweep (F2 — before you declare the spec ready)

Walk every canonical category (the set in harness/intake-categories.json). Each must be one of: covered (covered by FR-NNN — an FR / SC / edge case exists), deliberately N/A (deliberately N/A — <reason>, recorded in the ## Deferrals / Out of scope ledger so the human can ratify the omission), or surfaced (surfaced — <ref> — a ## Clarifications answer or a flagged [ASSUMED …]). Every category appears exactly once in the ledger, by canonical id; a category that is none of these is an elicitation gap — close it before Gate A. (The Stop floor greps each canonical id for one of these dispositions — presence, never adequacy.)

Self-check before ready (F3 — enumerable, symmetric to the Task-Breakdown self-check)

Confirm, all verifiable by reading (no judgment call):

1. the coverage sweep over every canonical category (harness/intake-categories.json) is complete (each covered / deliberately N/A / surfaced);
2. zero orphaned [NEEDS CLARIFICATION] / [PLACEHOLDER] remain;
3. every P1 story has ≥ 1 explicit edge case and ≥ 1 failure/error-path scenario;
4. every story with latency / volume / availability implications has ≥ 1 NFR SC-NNN;
5. every [ASSUMED …] carries its Chosen because / Discarded and a propagation note;
6. the ## Deferrals / Out of scope surface lists the categories consciously skipped or N/A.

The boundary (WIRED, not advisory)

This skill describes the behaviour; the hooks are the boundary, and they are live:

• pre-tool-use-clarify-gate.sh (PreToolUse on AskUserQuestion, the real-time enhancement) denies the round beyond the budget, denies > the per-call question cap, denies AskUserQuestion entirely in autonomous mode, and denies the next round until the prior round is logged (ask↔record coupling). A human grant (intake.sh clarify) lifts the ceiling.
• stop-gate-intake.sh (Stop, the carrier-independent F1 guarantee) blocks the agent from declaring the spec done while any [NEEDS CLARIFICATION] remains, the round count exceeds budget, autonomous has any asked round, or the coverage sweep / F7 ## Deferrals surface is incomplete. This floor holds even if the AskUserQuestion gate is absent — the guarantee never rests on it.

Beyond these hooks sit the Gate-A two-party restatement (the spec-reviewer subagent, an understanding.md projection, and a human ratification token) and the Gate-B FR↔task traceability check — see the Architect role for the full cycle.