clarify

# Clarify — the de-risking gate before planning A spec written in one sitting always lies a little. It states what the author *thought of*, and stays silent on everything they didn't — the edge cases, the unstated defaults, the words that mean two things. Those silences don't disappear; they get discovered later, mid-implementation, where they cost ten times as much to fix. **Clarify is the gate that drags those silences into the open while they are still cheap.** This is the fourth phase of the rsc SDD chain (`constitution` → `specify` → **`clarify`** → `plan` → `tasks` → `analyze` → `implement` → `verify` → `review` → `ship`); the method itself lives in `../sdd/SKILL.md`. `specify` turned a fuzzy intent into a spec; clarify interrogates that spec, asks the user the questions that actually change the build, and writes the answers back so the spec becomes safe to plan from. It produces **no new artifact** — it sharpens the existing one in place. The line is **specify creates, clarify de-risks, plan designs**: if you find yourself proposing how to *build* it, you have left clarify. **Model tier: `balanced`** — this phase ranks and asks the few high-leverage questions, it does not design architecture. Resolve and apply it per `../sdd/references/model-routing.md`; routing is off unless `models.enabled: true` in `02-DOCS/wiki/sdd/config.yaml`. **Accompaniment dial.** Read the level from `02-DOCS/wiki/harness/user-profile.md` (the dial and the `02-DOCS/wiki/` convention are owned by `../harness/SKILL.md`). Clarify is question-heavy, so the dial matters here more than almost anywhere — it sets **how many questions you ask and how you frame them**. With no profile: default to non-technical framing, ask the two gauging questions (technical level + accompaniment) first, then proceed at the stated level. | Dial | Ask | | --- | --- | | **L0** "cavernícola" | ONLY the questions whose answer changes the architecture or scope. Propose safe defaults for everything else and list them tersely as "assumed unless you object". Minimal prose. | | **L1** "breve" | The high-leverage batch, one line of *why* per question. | | **L2** "explica decisiones" | The batch plus the trade-off behind each option, so the user chooses informed. | | **L3** "acompañamiento total" | Walk the taxonomy out loud, explain what each kind of gap costs if left unresolved, ask broadly (including the medium-leverage questions), and teach the *why* as you go. Ideal for non-technical users who benefit from seeing the hidden decisions. | ## Read first — the inputs Clarify never works blind. Before asking a single question, load three things: 1. **The spec.** Read the target spec under `02-DOCS/wiki/sdd/specs/<slug>.md` end to end. If the path wasn't given, find the most recently touched spec or ask which one. Its *Points to clarify* is a **typed** handoff, not a question list — read the types before you plan a single question (below). 2. **The constitution.** Read `02-DOCS/wiki/sdd/constitution.md` if it exists. Its principles (stack canon, quality bars, conventions) resolve a surprising number of "ambiguities" without bothering the user — if the constitution already fixes the auth method or the data region, that's answered, not open. 3. **The harness profile.** `02-DOCS/wiki/harness/user-profile.md`, for the dial above. Citing what you read ("checked the constitution — auth is already fixed to OAuth, so that's not an open question") shows your work and prevents re-litigating settled decisions. ## The typed handoff — what `specify` already decided *Points to clarify* holds four different objects, and each one gets a different action from you. Treating all four as questions is how clarify re-asks what was already decided and disturbs what was deliberately deferred: | Type in the spec | What it means | Your action | | --- | --- | --- | | **pregunta abierta** | Formulable, unanswered | Ask it — this is your queue | | **suposición tomada** | `specify` decided it; the basis is written | **Validate**, don't re-ask: state the assumption and its basis back, and ask only whether it still holds | | **decisión diferida** | Sharp, out of this cycle on purpose | Leave it. Do not reopen scope the author closed | | **área no formulable** | Known to be coming, not yet phrasable | Note it. If your pass sharpens it into a real question, it graduates — say that it did | **Declare what you did with each entry.** Close the pass with one line per point: asked, validated (held / broke), left deferred, or graduated. An entry you silently dropped is the gap that comes back at implementation time. **An untyped entry** (an older spec, or a hurried one) is read as **pregunta abierta** — the costliest reading, so nothing gets skipped by accident. Type it as you go, so the spec improves on the way through. Sharpness, not difficulty, is what separates a question from an unformulable area: *can you state it precisely now?* Not *can you answer it?* ## The ambiguity taxonomy — where specs hide their gaps Scan the spec against these categories. Most real gaps fall into one of them; walking the list is how you find the ones the author didn't think to write down. | Category | What to hunt | Tell-tale phrasing in the spec | | --- | --- | --- | | **Underspecified behavior** | A described feature with a missing branch — what happens in the *other* case | "the user logs in" (and if it fails? locked out? wrong password vs no account?) | | **Unstated assumptions** | Defaults the author assumed everyone shares | no mention of auth, tenancy, currency, timezone, locale | | **Edge & boundary cases** | Empty, zero, max, duplicate, concurrent, first-run, offline | lists with no empty-state, counts with no upper bound | | **Ambiguous terms** | A word doing two jobs | "user" (end-user or admin?), "delete" (soft or hard?), "fast" (how fast?) | | **Missing acceptance criteria** | A goal with no observable done-condition | "should be performant", "easy to use", "handle errors gracefully" | | **Scope edges** | What's explicitly OUT vs left dangling | features hinted at but never bounded — "for now", "eventually" | | **Data & state** | Lifecycle, ownership, retention, migration of existing data | new entity with no story for what happens to old records | | **Failure & recovery** | What happens when a dependency is down, a write half-completes, input is hostile | happy-path-only flows | | **Non-functional** | Performance, scale, security, accessibility, i18n targets | vague "non-functional requirements" or none at all | | **Actors & permissions** | Who can do each thing | a verb with no subject — "can be edited" (by whom?) | You are not filling every cell for every spec. You are scanning all ten so the gaps that *do* exist surface instead of hiding. ## The pass — five steps Run in order. The discipline is: find many candidate gaps, keep only the ones that change the build, ask those well, write the answers back. 1. **Inventory.** Walk the spec against the taxonomy above. Produce a raw list of every candidate ambiguity, edge case, and unstated assumption. Over-collect here; you'll prune next. Note for each which category it is and where in the spec it lives. 2. **Resolve what you already can.** For each candidate, check the constitution and the spec's own later sections before asking the user. Many "gaps" are answered elsewhere. Mark each candidate **resolved-internally** (cite the source), **inferable** (a safe default you'll propose, not silently assume), or **must-ask** (only the user can decide). 3. **Rank by leverage.** Sort the must-ask list by impact: how much does the build change depending on the answer? A question whose two answers lead to two different architectures ranks above a cosmetic one. Cut low-leverage questions — clarify is not an interrogation, it's the *few* questions that matter. Cap the batch to the dial. 4. **Ask — one focused batch, sized to the dial.** How you ask determines whether you get a usable answer: - **Make it a decision, not an essay prompt.** "Should deletes be soft (recoverable, hidden) or hard (gone immediately)? I'd recommend soft because the spec mentions an audit trail — confirm?" beats "How should deletion work?". - **Carry your own recommendation** when there's a defensible default, matched to the constitution. The user confirms or overrides — far less effort than authoring from scratch. - **Quote the spec.** Anchor each question to the exact line or section it came from, so the user sees *why* it's open. - **One batch, ranked, then stop.** Don't drip questions one at a time over many turns unless the dial is L3; don't dump thirty at once. Then wait: never ask and answer in the same breath, and never assume the user's intent on a must-ask item. 5. **Bake the answers back into the spec.** This is the deliverable — an un-baked answer is a lost answer. For each resolved item, edit the spec in place: - Tighten the relevant section with the decided behavior. - Add or sharpen acceptance criteria so the decision is now observable. - Append a `## Clarifications` log to the spec: dated entries of `Q → decision → why`, so the *reasoning* survives, not just the result. - Move anything explicitly dropped into an `## Out of scope` section so it's bounded, not dangling. Then re-read the spec once more: did resolving one gap open a new one? If so, one more short loop. Otherwise, the gate is passed. ## Worked micro-example Spec line: *"Users can upload a profile photo."* Clarify's inventory against the taxonomy: ```text - Ambiguous term : "photo" — which formats? (PNG/JPG/HEIC/SVG?) - Boundary : max file size? max dimensions? what if it's 50 MB? - Edge case : no photo uploaded — is there a default/placeholder? - Failure : upload fails mid-transfer — retry, or lose it? - Data lifecycle : replacing a photo — is the old file deleted or orphaned? - Actors : can an admin change another user's photo? - Non-functional : is the image resized/compressed server-side? stored where? - Security : is the file type validated, or can someone upload an .svg with script? ``` Resolved-internally (cite): constitution fixes storage to the project's object store → "stored where" is answered. Must-ask, ranked: formats + max size (changes validation and UX), security validation (changes the upload path), old-file deletion (changes data model). Cosmetic placeholder choice → propose a default, don't burn a question on it. After baking back, the spec line becomes a bounded, testable behavior with acceptance criteria ("rejects files >5 MB with a clear message", "accepts PNG/JPG/HEIC only", "replacing a photo deletes the prior file") and a `## Clarifications` entry recording why. ## Anti-patterns | Anti-pattern | Why it breaks the gate / do instead | | --- | --- | | Skipping clarify because the spec "reads clear enough" | Clear to the author ≠ unambiguous. Run the taxonomy; the gaps you can't see are exactly the expensive ones. | | Assuming the sensible default and moving on | An assumption is an unrecorded decision. Either it's resolvable from the constitution (cite it) or it's a must-ask. Silent defaults resurface as bugs — and "the user is busy" is not an exception; a wrong guess costs more than a one-tap question. | | Sketching how you'd build it while you're in there | That's `plan`. Clarify decides *what*, not *how*. Proposing architecture means you left the gate. | | Asking everything you can think of, to be safe | Thirty questions is noise that buries the three that matter. Rank by leverage, ask the few, default the rest — and batch them once instead of dripping one per turn. | | Answering the questions in your head and leaving the spec as-is | The deliverable is the *edited spec* plus the Clarifications log, not a clean conscience. | | Leaving edge cases "to the implementer" | Edge cases are *spec* problems. Resolving them now is the whole point of the gate. | ## Exit gate The gate is passed when the spec, constitution and profile were all read (settled questions cited, not re-asked); **every typed point in the handoff has its declared outcome** (asked / validated / left deferred / graduated), with nothing silently dropped; all ten taxonomy categories were considered; only the build-changing gaps were put to the user, as dial-sized decisions with recommendations; every answer is baked into the spec body with observable acceptance criteria, logged under `## Clarifications` and bounded under `## Out of scope`; and the final re-read opened no new gap. ## Result envelope End with the parseable block every SDD phase shares, so the dispatcher can chain without interpreting prose (contract: `../sdd/SKILL.md`): ```json result-envelope { "status": "complete|blocked|failed", "executive_summary": "Open points resolved; the spec is de-risked and ready to plan against.", "artifact": "02-DOCS/wiki/sdd/specs/<slug>.md", "next_recommended": "plan", "risk": "low|medium|high", "skill_resolution": { "used": ["clarify"], "missing": [], "fallback": [], "compact_rules": ["Ask only what changes the spec.", "An unanswered question is recorded, never invented."] }, "evidence": ["answers folded back into the spec", "remaining open points listed with their owner"] } ``` ## Next in the chain Hand off to **`plan`** — turn the now-sharp spec into a technical implementation plan (architecture, interfaces, data flow, testing strategy, risks), deferring stack specifics to the relevant stack skill. The chain continues: clarify → **plan** → tasks → analyze → implement → verify → review → ship. `debug` is callable any time if what you are "clarifying" turns out to be a runtime fault, not a spec gap. ## Orientación (siempre) Cierra cada turno con el **bloque-brújula** (📍 dónde estás · ✅ qué hiciste · 🧭 por qué · ➡️ siguiente, terminando en pregunta), calibrado al dial de `02-DOCS/wiki/harness/user-profile.md`. **Nunca termines en seco.** Protocolo completo: skill `orient` → `skills/orient/references/orientation-contract.md`. (Defiere a `suggest` el "¿instalo la skill que falta?".)