| name | clarify |
| description | [Internal pipeline stage — run by the planning stages; invoke directly only as a power user.] Bounded clarification gate for resolving product, domain, API, security, or architecture uncertainty without exhausting the user. |
Clarify Skill
Use this skill when a BRD, story, design, or implementation plan contains uncertainty that materially affects behavior, data shape, security, privacy, architecture, or story readiness.
This is not an open-ended interview. The goal is to unblock progress with the smallest useful number of questions.
Clarification Budget
- Default budget: 10 questions.
- Hard cap: 15 questions.
- Continue past 10 only if the user explicitly asks to keep going.
- Never exceed 15 questions in one clarification session.
Ask one question at a time unless the questions are tightly coupled and can be answered together without cognitive overhead.
Before Asking
First try to answer from local context:
- Existing code and tests
CONTEXT.md or CONTEXT-MAP.mddocs/adr/specs/brd/specs/stories/specs/design/project-manifest.json.claude/program.md
If local context gives a reasonable answer, record it as an assumption instead of asking.
Ask Only Load-Bearing Questions
Ask only when the answer materially changes one of:
- User-visible behavior
- Story readiness
- Acceptance criteria
- Data model
- API contract
- Security or privacy posture
- Architecture direction
- External integration behavior
- File ownership or implementation sequencing
Do not ask preference questions that can be safely decided by existing project conventions.
Question Format
Each question should include:
- The decision being made.
- Your recommended answer.
- Why the answer matters.
Example:
Question 3/10 — Password reset token expiry
Recommendation: 30 minutes.
Why it matters: This affects the API contract, data model, tests, and security posture.
Should we use 30 minutes, or do you need a different expiry?
Stop Conditions
Stop before the budget if:
- The artifact is implementable.
- Remaining uncertainty is low-risk and can be captured as assumptions.
- The user says to proceed.
- The user is repeating answers or uncertainty is not decreasing.
At question 10, stop and present:
- Confirmed decisions
- Assumptions you will proceed with
- Unresolved risks
- Recommendation: proceed, split a story, or pause for human decision
Only continue to questions 11-15 if the user explicitly asks.
Outputs
Write clarification outcomes into the artifact being prepared:
- BRD:
Open Questions, Assumptions, or relevant requirement sections
- Story:
Acceptance Criteria, Notes, Readiness, and Breakdown Reason
- Design:
api-contracts.md, data-models.md, component-map.md, or docs/adr/
- Implementation plan: plan assumptions and risks
If a term is clarified and CONTEXT.md exists, update it. If no CONTEXT.md exists, create it only when the clarified term is domain-level and likely to recur.
Offer an ADR only when all are true:
- The decision is hard to reverse.
- The decision would surprise a future maintainer without context.
- Real alternatives were considered.
Gotchas
- Do not interrogate by default. Prefer code/docs discovery and explicit assumptions.
- Do not ask trivia. If the answer does not change behavior or architecture, skip it.
- Do not block on polish. If the artifact is good enough to proceed, proceed.
- Do not exceed the budget. More questions can reduce quality by exhausting the user.
