clarify

name	clarify
description	Adaptive requirements clarification with auto-depth routing. Shallow (Q&A) for simple tasks, Deep (exploration + DRAFT + PLAN) for complex ones. Escalates automatically when ambiguity persists.
required_context	[".claude/ai-context/architecture.md",".claude/ai-context/conventions.md"]
allowed-tools	["Read","Grep","Glob","Task","Write","AskUserQuestion"]

/clarify — Adaptive Requirements Clarification

Chain (MUST)

Previous	Current	Next
Session start	/clarify	EnterPlanMode() → /implement

Core Model

/clarify → Measure complexity → Clear enough?
                                ├─ Yes → EnterPlanMode()
                                └─ No  → Deeper clarify (explore, analyze, DRAFT...)
                                         → Re-measure → Repeat

Exit condition: "Is this enough info to implement?"

---

Step 0: Route — Complexity Assessment

Measure complexity internally upon receiving request (do not expose to user).

Complexity Signals

Signal	LOW	HIGH
Request length	Short and specific	Long or ambiguous
Keywords	"add", "fix", "change"	"design", "migration", "from scratch"
Uncertainty	None	"not sure", "how should I"
Impact scope	Single file/module	Cross-cutting, multiple services
Risk	Low (UI, text)	High (DB, auth, breaking API)
Existing patterns	Clearly exist	None or unfamiliar stack

• LOW → Shallow Path (completed within this file)
• HIGH → Deep Path (see deep/DEEP.md)
• Ambiguous → Start Shallow, monitor escalation conditions

---

Shallow Path (Low Complexity)

Remove ambiguity via quick Q&A, generate minimal specs, and enter Plan Mode.

Execution

1. Record: Log original request + identify ambiguous parts
2. Question: AskUserQuestion (specific options, 2-3 rounds)
3. Escalation Check: Check escalation conditions (see below)
4. Create DRAFT: Write .dev/specs/{name}/DRAFT.md (minimal version — What, Why, Scope, Success Criteria)
5. Summary + Create PLAN: Before/After comparison → Write .dev/specs/{name}/PLAN.md
6. Auto Plan: Call EnterPlanMode() — plan file은 반드시 .dev/specs/{name}/PLAN.md에 작성

Rules

• No assumptions → Ask questions
• Clarify to TDD-ready level
• Target resolution within 3 rounds

Escalation → Deep Path

Switch to Deep Path if any of these are detected:

• Scope still undefined after 3 rounds of questions
• New uncertainties keep emerging from user answers
• Impact scope expanded beyond initial estimate (single → multi-module)
• Risk indicators found (DB schema, auth, breaking changes)
• User doesn't know the approach itself ("I don't know how to do this")

On switch: Inform "Scope is more complex than expected. Exploring the codebase first." then follow the process in deep/DEEP.md.

---

Deep Path

When complexity is HIGH or escalated from Shallow.

See deep/DEEP.md for the full process.

Summary:

1. Classify intent (7 types) → Determine strategy
2. 3 parallel exploration agents → Understand codebase
3. Generate DRAFT → Interview → Continuously update
4. On user explicit request → Analysis agents → Generate PLAN → Reviewer loop
5. After approval → EnterPlanMode()

---

DECISIONS.md Recording (MUST)

Record decisions in .dev/DECISIONS.md before finalizing plan:

Situation	Required Record
New feature design	Decision background, alternatives, reasoning
Architecture choice	Considered options, selection rationale
Trade-offs	What was sacrificed and what was gained

## YYYY-MM-DD: {feature-name}
- **Decision**: What was decided
- **Reason**: Why this choice was made
- **Alternatives**: Options considered but not chosen
- **Reference**: .dev/specs/{feature-name}/PLAN.md (if exists)

---

Plan File Requirements

Plan files must include:

• Specify implementation via /implement skill
• Verification method (test execution)
• Confirmation that .dev/DECISIONS.md recording is complete

Plan File Location: Plan Mode 진입 시 plan_file 경로를 .dev/specs/{name}/PLAN.md로 지정. 시스템 Plan Mode의 .claude/plans/ 대신 .dev/specs/를 사용.

Important: Plans that do not use /implement will not be approved.

---

NEXT STEP (Auto-execute)

On plan approval, call /implement immediately. Do not ask "Should I implement?".