The /to-clarify Skill
A relentless interview to eliminate assumptions, challenge condition sufficiency, sharpen domain vocabulary, and score readiness (0–100) before planning or coding.
"Examine your guess. Is it possible to satisfy the condition? Is the condition sufficient to determine the unknown? Or insufficient? Or redundant? Or contradictory?" — George Pólya, How to Solve It (1945)
/to-clarify @docs/spec/checkout-spec.md Interrogate assumptions, test condition sufficiency, and calculate readiness score.What it does
to-clarify is a stateful ambiguity interrogation skill. It reads your existing codebase and subjects your target specification or plan (docs/spec/, docs/prd/, or docs/plan/) to an unsparing Socratic grilling session. It isolates unverified assumptions ([ASSUMPTION-XXX]), audits condition sufficiency across 5 analytical axes (Goal & Premise, 5 UI States, Sad Paths, Seams, Scope Boundaries), challenges fuzzy adjectives, and calculates an objective Readiness Score (0–100).
It writes real documentation into your repo as it goes: resolved domain terminology is immediately recorded into CONTEXT.md, hard-to-reverse architectural decisions are persisted into docs/adr/, and the complete audit trial is saved to docs/audit/{slug}-{phase}-clarification.md. It refuses to write application source code; its sole purpose is to guarantee that the condition is fully determined before a single line of code is written.
When to reach for it
Where the work currently lives decides whether this is the right skill:
| The work is… | Reach for |
|---|---|
| A freshly drafted Technical Specification with provisional assumptions | /to-clarify @docs/spec/{slug}-spec.md (grill assumptions before planning) |
| An Implementation Plan ready for sanity checking | /to-clarify @docs/plan/{slug}-plan.md (verify seams & tracer bullets before coding) |
| Requirements full of fuzzy adjectives ("fast", "scalable", "user-friendly") | /to-clarify to force quantitative thresholds and measurable types |
| An open-ended greenfield idea with no codebase yet | /to-explore |
| Formal architecture, schema, and API contract design | /to-spec |
| Decomposing an approved specification into tracer bullets | /to-plan |
| Writing functional application code | /to-code (clarify strictly forbids coding) |
Prerequisites
- Target Document in Context: Must provide the path to a PRD (
docs/prd/), Spec (docs/spec/), or Plan (docs/plan/). - Proactive Codebase Discovery: The agent MUST inspect your repository files and
docs/ARCHITECTURE.mdbefore asking questions. It never asks what code can answer. - Safe Documentation Seams: Writes strictly to
docs/audit/, updatesCONTEXT.md, and creates ADRs indocs/adr/. Application source code remains untouched.
The paper trail
Three distinct artifacts emerge from an interrogation session:
| What resolved | Where it lands |
|---|---|
| A domain term: the project's canonical word for an entity or concept | CONTEXT.md, inline, the exact moment it resolves (with rejected terms under _Avoid_) |
| An architectural trade-off: hard to reverse, surprising without context, and high impact | An Architecture Decision Record under docs/adr/NNNN-{slug}.md |
| Audit Findings & Readiness Score: 0–100 score with assumption mitigations | docs/audit/{slug}-{phase}-clarification.md (increments iteration headers) |
What one run does
A clarification run executes the disciplined "Grill Me" Protocol to de-risk requirements without causing cognitive fatigue:
- Autonomous Codebase Reconnaissance: Inspects repository files, schemas, and
docs/ARCHITECTURE.mdfirst. It never asks questions that existing code can already answer. - One Question Only: Never bombards you with a list of 5+ questions. Asks exactly ONE sharp, focused question per response.
- Concrete A/B Options: Proposes 2–3 concrete technical alternatives (Option A vs. Option B) grounded directly in existing repository patterns.
- Senior Principal Recommendation: Clearly indicates which option is recommended from a Clean Architecture and long-term maintainability perspective, explaining why.
- Continuous Artifact Settling: Updates
CONTEXT.mdimmediately as domain terms resolve, drafts ADRs indocs/adr/for irreversible trade-offs, and scores readiness indocs/audit/.
Common questions
It ran, but no ADRs appeared. Is something broken?
No, that is working as designed. An Architecture Decision Record requires meeting three conditions simultaneously: it must be hard to reverse, surprising without context, and a genuine trade-off. Most clarifications refine existing requirements or settle domain terminology (which go straight to CONTEXT.md). A clarification session with zero ADRs is completely normal.
Why does the agent only ask one question at a time instead of giving me a full questionnaire?
Multi-question lists cause cognitive overload, leading to hurried, shallow responses. By focusing on one architectural frontier at a time with concrete A/B choices, each decision builds upon the previous one without ambiguity drift.
What happens when the Readiness Score reaches ≥ 80/100?
The agent pauses and presents the Good Enough Quality Gate: choose PROCEED (the agent automatically resolves remaining 20% minor details with its recommended defaults and finalizes the report) or REFINE (continues drilling the remaining secondary questions).
It's working if
CONTEXT.mdchanges during the session, term by term, rather than appearing in one lump at the end.- Questions the codebase can answer get answered by inspecting existing code, not asked of you.
- Every question presents concrete technical options (Option A vs. Option B) with a clear Senior Principal recommendation.
- It challenges unmeasurable adjectives ("fast", "scalable") and proposes quantitative thresholds or strict types.
- It never asks you to write code or offers to patch production files itself.
Where it fits
to-clarify is the recurring quality gate across the Pólya SDLC pipeline:
/to-explore → /to-prd → /to-spec → 🥊 /to-grill-me → 🔍 /to-clarify → /to-plan → 🛑 PAUSE → /to-code → /to-review → /to-docs
It is invoked after /to-spec or /to-grill-me (to formalize decisions and eliminate spec ambiguity) or after /to-plan (to stress-test tracer bullets). Once the Readiness Score passes the ≥ 80 threshold, it hands off to /to-plan or /to-code.