ericrisco/rsc-harness / skills/clarify
clarify
VerifiedUse when a spec exists and must be de-risked before planning — run the gap checklist over its four ASDD questions and out-of-scope, ask only what changes what gets built (one question at a time, recommendation first), record every other call as an assumption, bake the answers back into the spec. The second half of ASDD stage 2 (Spec), between `specify` (writes the spec) and `plan` (designs the build). NOT the cross-artifact consistency check (that is `analyze`).
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 14.0 KB |
| evals/README.md | markdown | 3.7 KB |
| evals/cases.yaml | config | 6.0 KB |
evals/cases.yaml
View on GitHubskill: clarify
# Prompts that MUST load the `clarify` skill. Clarify is the fourth phase of the
# rsc SDD chain: a spec already exists and needs DE-RISKING before planning —
# surface ambiguities, edge cases, unstated assumptions, ask the high-leverage
# questions, bake the answers back into the spec. It creates no new artifact; it
# sharpens the existing spec in place. It is NOT spec authoring (specify) and NOT
# the technical plan (plan).
should_trigger:
- prompt: "Here's our spec for the new billing flow — poke holes in it before we start planning."
why: "Hunting holes/ambiguities in an existing spec ahead of planning is the literal job of clarify."
- prompt: "Is this spec actually ready to build, or is something still underspecified?"
why: "Readiness-to-plan and underspecified-area detection is the de-risking gate clarify owns; phrased without naming the skill."
- prompt: "This requirements doc feels vague and I keep getting stuck whenever I try to plan from it."
why: "A vague spec that stalls planning is the exact symptom clarify exists to resolve — the gap is in the spec, not the plan."
- prompt: "Aclara el spec del onboarding: qué casos límite y supuestos nos estamos saltando."
why: "Spanish trigger ('clarify the spec', edge cases and assumptions) — clarify is bilingual and edge-cases/assumptions are core taxonomy categories."
- prompt: "Before we design the architecture, what questions about this feature do I actually need answered first?"
why: "Surfacing the high-leverage open questions to answer BEFORE design/plan is clarify's ranking-and-asking step; the user even separates it from the architecture."
- prompt: "Go through 02-DOCS/wiki/sdd/specs/checkout.md and flag every ambiguous term and missing acceptance criterion."
why: "Operating directly on a spec under the canonical SDD specs path, hunting ambiguous terms and missing acceptance criteria — taxonomy categories owned here."
- prompt: "We wrote what the feature should do but never decided what happens on the error paths or empty states — sort that out in the spec."
why: "Underspecified failure/edge behavior that needs deciding and writing back into the spec is precisely clarify's pass, no skill name used."
# NEAR-MISS prompts that must NOT load `clarify`. Each routes to a real sibling.
# The recurring trap: anything about a spec/feature that is actually authoring it
# (specify), designing the build (plan), cross-checking artifacts (analyze), or
# diagnosing a runtime fault (debug).
should_not_trigger:
- prompt: "I have a fuzzy idea for a referral feature but no spec yet — help me write one."
route_to: "specify"
why: "There is no spec to interrogate yet; turning fuzzy intent into a first spec is specify, the phase before clarify."
- prompt: "The spec is clear — now give me the architecture, interfaces, and data flow to build it."
route_to: "plan"
why: "The what is settled and the user wants the technical how; that's plan, the phase after clarify."
- prompt: "Cross-check our constitution, spec, plan, and task list for contradictions and scope drift."
route_to: "analyze"
why: "Consistency check ACROSS multiple SDD artifacts is analyze; clarify works on the spec alone, before a plan even exists."
- prompt: "Checkout throws a 500 in production sometimes — figure out why."
route_to: "debug"
why: "Diagnosing a runtime fault's root cause is debug; 'figure out why' here is about live behavior, not spec ambiguity."
- prompt: "Decide our project-wide non-negotiables: stack canon, quality bars, and conventions."
route_to: "constitution"
why: "Establishing project-wide principles is the constitution phase; clarify reads the constitution but does not author it."
# Capability scenario with a rubric to grade WITH vs WITHOUT the skill loaded.
# A skill-guided pass walks the gap checklist, resolves what the constitution already
# fixes, asks only what changes the build, records the rest as assumptions, and bakes answers back with a
# Clarifications log. An ungrounded pass typically free-associates a few
# questions and never edits the spec or records the reasoning.
capability:
- scenario: "We have a spec at 02-DOCS/wiki/sdd/specs/profile.md whose only line about photos is 'Users can upload a profile photo.' De-risk it before we plan."
must_include:
- "Reads the spec, the constitution (02-DOCS/wiki/sdd/constitution.md), and the harness profile first — citing anything the constitution already fixes (e.g. storage) as resolved rather than re-asking it."
- "Walks the gap checklist (what the user can do, what result they get, what it must respect, how it proves it, out of scope) and surfaces concrete gaps: accepted formats, max file size / dimensions, empty/no-photo state, upload-failure recovery, old-file deletion on replace, who-can-edit (actor/permission), security validation of the file type, and anything an agent might add 'just in case'."
- "Asks only if the answer changes what gets built (formats+size, security validation, old-file deletion); for the rest it picks the most reasonable option and records it in the spec as a 'suposición tomada' with its basis, so the human sees every assumption in one block at approval."
- "Asks one question at a time, as a decision with the recommended answer first so a 'yes' suffices (e.g. 'I'd make deletes soft because… — OK?'), anchored to the spec line, rather than open-ended essay prompts or a batch of questions; phrases them in the register from technical_level in user-profile.md."
- "Bakes the resolved answers BACK into the spec: tightens the photo section into bounded behavior, adds observable acceptance criteria, and bounds dropped items under out of scope."
- "Appends a dated '## Clarifications' log of Q → decision → why so the reasoning survives, and does a final re-read to confirm no new gap was opened."
- "Stays in its lane: decides WHAT, never proposes the technical HOW (no architecture/library choices) and ends by pointing to plan as the next phase."
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |