majiayu000 @.claude/shared-imports/constitution.md @.claude/templates/clarification-checklist.md
Specification Clarification
Purpose: Systematically eliminate ambiguity from specifications through structured questioning before implementation planning.
Constitutional Authority: Article IV (Specification-First Development), Article V (Template-Driven Quality)
Phase 1: Load Specification and Detect Ambiguities
Step 1.1: Read Current Specification
Identify current feature from SessionStart hook context or user input.
Read specs/<feature-number>-<name>/spec.md
Step 1.2: Scan Against Ambiguity Categories
Use @.claude/templates/clarification-checklist.md categories:
10+ Ambiguity Categories:
- Functional Scope & Behavior: What exactly does "process" mean? Which actions are in/out of scope?
- Domain & Data Model: What entities exist? What are their relationships and cardinality?
- Interaction & UX Flow: How do users navigate? What's the exact sequence of screens/actions?
- Non-Functional Requirements: Performance targets? Scale expectations? Security requirements?
- Integration & Dependencies: Which external systems? What data flows in/out?
- Edge Cases & Failure Scenarios: What happens when X fails? How to handle boundary conditions?
- Constraints & Tradeoffs: Budget limits? Technology restrictions? Compliance requirements?
- Terminology & Definitions: What does "active user" mean? How is "completion" defined?
- Permissions & Access Control: Who can do what? What are the authorization rules?
- State & Lifecycle: What states can entities be in? What triggers transitions?
Step 1.3: Identify Gaps and Mark Coverage
For each category, assess coverage:
- Clear: Well-defined, no ambiguity
- Partial: Some aspects defined, others unclear
- Missing: Not addressed in specification
Output: Coverage matrix showing which categories need clarification
Phase 2: Prioritize Clarification Questions
Step 2.1: Extract [NEEDS CLARIFICATION] Markers
Count existing markers in specification (Article IV limit: max 3).
Step 2.2: Prioritize by Impact
Priority Order (Article IV, Section 4.2):
- Scope (highest impact) - Affects what gets built
- Security - Affects risk and compliance
- UX Flow - Affects user experience
- Technical (lowest impact) - Implementation details
Maximum 5 Questions Per Iteration (Article IV requirement)
Step 2.3: Generate Questions with Recommendations
Each question MUST include:
- Context: Why this matters
- Question: Specific, focused inquiry
- Options: 2-3 recommendations based on common patterns
- Impact: What depends on this answer
Example:
**Question 1: Authentication Method** (Priority: Security)
Context: Specification mentions "user login" but doesn't specify authentication approach.
Question: How should users authenticate?
Options:
A) Email/password (simplest, industry standard)
B) Social login only (Google, GitHub - reduces friction)
C) Both email/password + social (maximum flexibility)
Recommendation: Option C provides flexibility while maintaining control.
Impact: Affects data model (user table schema), security requirements (password hashing, OAuth), and UX flow (login screens).
Intelligence Evidence:
- project-intel.mjs found: src/auth/login.tsx:12 (existing email/password flow)
- Recommendation aligns with existing pattern
Phase 3: Interactive Clarification
Step 3.1: Present Questions Sequentially
ONE QUESTION AT A TIME for complex topics (Article IV requirement).
Present question with:
- Numbered options
- Recommendation highlighted
- Impact analysis
- Evidence from intelligence queries (if available)
Step 3.2: Capture User Response
Record answer with rationale:
**Answer to Q1**: Option C (both methods)
**Rationale**: Need to support existing email users while enabling social login for new users.
**Additional Context**: Google and GitHub OAuth only (not Facebook).
Step 3.3: Update Specification Incrementally
After EACH answer:
- Edit specification to incorporate answer
- Remove or resolve [NEEDS CLARIFICATION] marker
- Add functional requirement with answer
- Verify no contradictions introduced
Example Update:
## Functional Requirements
- **FR-001**: System MUST support email/password authentication
- **FR-002**: System MUST support OAuth2 social login (Google, GitHub)
- **FR-003**: Users MUST be able to link multiple auth methods to one account
Remove:
- **FR-XXX**: System MUST authenticate users via [NEEDS CLARIFICATION: auth method not specified]
Phase 4: Validation and Completion
Step 4.1: Verify Consistency
Check for contradictions:
- Do new requirements conflict with existing ones?
- Are priorities consistent?
- Do user stories align with clarifications?
Step 4.2: Update Clarification Checklist
Mark categories as Clear after resolution:
## Clarification Status
| Category | Status | Notes |
|----------|--------|-------|
| Functional Scope | Clear | All features defined |
| Domain Model | Clear | User/Auth entities specified |
| UX Flow | Clear | Login/register flows documented |
| Non-Functional | Partial | Need performance targets |
| Integration | Clear | Google/GitHub OAuth |
...
Step 4.3: Report Completion
Output:
✓ Clarification complete: <N> questions resolved
Resolved:
- Q1: Authentication method → Email/password + Social (Google, GitHub)
- Q2: User roles → Admin, User, Guest with specified permissions
- Q3: Data retention → 90 days for inactive accounts
Updated Specification:
- Added FR-001 through FR-008 (authentication requirements)
- Updated User Stories with auth flow details
- Removed all [NEEDS CLARIFICATION] markers
Remaining Ambiguities: 0 (ready for planning)
Next Step: Use create-implementation-plan skill to define HOW
Phase 5: Re-Clarification (If Needed)
When to Re-Run
Trigger clarification again if:
- Implementation planning reveals new ambiguities
- User requests changes to requirements
- New [NEEDS CLARIFICATION] markers added during planning
Iterative Approach
Each iteration:
- Maximum 5 new questions
- Focus on highest-priority gaps
- Update specification incrementally
- Validate consistency
Anti-Patterns to Avoid
DO NOT:
- Ask more than 5 questions per iteration (Article IV limit)
- Ask open-ended questions without recommendations
- Present all questions at once (use sequential for complex topics)
- Make assumptions instead of asking
- Skip updating specification after each answer
- Accept ambiguous answers (press for specifics)
DO:
- Prioritize by impact (scope > security > UX > technical)
- Provide 2-3 options with recommendations
- Use intelligence queries for context
- Update spec incrementally (after each answer)
- Verify consistency after updates
- Limit [NEEDS CLARIFICATION] markers to max 3
Example Execution
Input: Specification with markers:
- **FR-004**: System MUST handle [NEEDS CLARIFICATION: concurrent user limit?]
- **FR-005**: Data MUST be stored [NEEDS CLARIFICATION: how long?]
- **FR-006**: Errors MUST be [NEEDS CLARIFICATION: logged where?]
Phase 1: Scan shows Missing coverage for:
- Non-functional requirements (no performance targets)
- Integration (no error logging system specified)
Phase 2: Generate 3 questions (all markers + 1 gap):
Q1: Concurrent User Limit (Priority: Technical/NFR)
Options:
A) 100 concurrent users (small team)
B) 1,000 concurrent users (department)
C) 10,000+ concurrent users (enterprise)
Recommendation: B (1,000) based on "department-scale" in problem statement
Q2: Data Retention Policy (Priority: Security/Compliance)
Options:
A) 30 days (minimal retention)
B) 90 days (standard)
C) Indefinite (until user deletes)
Recommendation: B (90 days) balances compliance and user needs
Q3: Error Logging Destination (Priority: Technical)
Options:
A) File-based logging (local files)
B) Centralized logging service (Sentry, DataDog)
C) Both (files + service)
Recommendation: C (both) for redundancy
Additional Gap:
Q4: Response Time Target (Priority: NFR)
Options:
A) < 200ms p95 (fast)
B) < 500ms p95 (standard)
C) < 1000ms p95 (acceptable)
Recommendation: B (500ms) standard for web apps
Phase 3: Present Q1, get answer (Option B), update spec:
- **FR-004**: System MUST support 1,000 concurrent users with < 500ms p95 latency
Phase 4: After all questions resolved:
✓ 4 questions resolved
✓ 0 [NEEDS CLARIFICATION] markers remaining
✓ Specification ready for implementation planning
Skill Version: 1.0.0 Last Updated: 2025-10-19