ASK BEFORE DESIGNING. This is not negotiable.

After exploration, you now know:

• What exists in the codebase
• What patterns are used
• What integrations are needed

Use this knowledge to ask informed questions about:

• Edge cases the code will need to handle
• Integration points with existing systems
• Behavior in ambiguous scenarios

If you catch yourself about to design without resolving ambiguities, STOP.

What Clarify Does

Clarify answers: WHAT EXACTLY should happen in specific scenarios Design answers: HOW to build it (next phase)

Process

1. Review Exploration Findings

Before asking questions, review:

• Key files you read
• Patterns discovered
• Architecture insights
• Integration points identified

2. Identify Ambiguities

Common areas needing clarification after exploration:

Integration Points:

• "The existing auth system uses JWT. Should the new feature use the same token or create a new session type?"

Edge Cases:

• "What happens if [condition discovered in code]?"

Scope Boundaries:

• "The existing feature handles X. Should the new feature also handle X or is that out of scope?"

Behavior Choices:

• "I found two patterns in the codebase for this. Pattern A in file.ts:23 and Pattern B in other.ts:45. Which should we follow?"

3. Ask Questions with AskUserQuestion

Present questions with context from exploration:

AskUserQuestion(questions=[{
  "question": "The auth middleware at src/middleware/auth.ts:78 validates tokens synchronously. The new endpoint needs user data. Should we: validate synchronously (faster, simpler) or fetch fresh user data (slower, always current)?",
  "header": "Auth pattern",
  "options": [
    {"label": "Sync validation (Recommended)", "description": "Faster, uses cached token claims, matches existing patterns"},
    {"label": "Fresh fetch", "description": "Slower, always current, needed if user data changes frequently"}
  ],
  "multiSelect": false
}])

Key principles:

• Reference specific files/lines from exploration
• Lead with recommendation based on codebase patterns
• Explain trade-offs clearly
• One question at a time for complex topics

4. Update SPEC.md

After each answer, update .claude/SPEC.md:

• Add clarified requirements
• Document decisions made
• Note trade-offs accepted

## Clarified Requirements

### Auth Pattern
- Decision: Sync validation
- Rationale: Matches existing patterns, user data changes infrequently
- Reference: src/middleware/auth.ts:78

### Edge Case: Expired Token
- Decision: Return 401, let client refresh
- Rationale: Consistent with other endpoints

Question Categories

Must Ask (based on exploration)

• Integration points with existing systems
• Patterns to follow (when multiple exist)
• Edge cases revealed by code reading

Optional (if unclear)

• Performance requirements
• Error handling preferences
• Backward compatibility needs

Don't Ask (already decided)

• What the feature does (that's brainstorm)
• Whether to build it (user already decided)
• Architecture approach (that's design)

Red Flags - STOP If You're About To:

Output

Clarification complete when:

• All integration points clarified
• Edge cases resolved
• Pattern choices made
• .claude/SPEC.md updated with final requirements
• No remaining ambiguities

Phase Complete

REQUIRED SUB-SKILL: After completing clarification, IMMEDIATELY invoke:

Skill(skill="workflows:dev-design")