ericrisco 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:
- The spec. Read the target spec under
02-DOCS/wiki/sdd/specs/<slug>.mdend 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). - The constitution. Read
02-DOCS/wiki/sdd/constitution.mdif 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. - 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.
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.
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).
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.
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.
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
## Clarificationslog to the spec: dated entries ofQ → decision → why, so the reasoning survives, not just the result. - Move anything explicitly dropped into an
## Out of scopesection 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:
- 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):
{
"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?".)