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)

Core Model

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

Exit condition: "Is this enough info to implement?" — Critical Unknown=0 + remaining items are made visible (Provenance).

Reference Files (load as needed — chaining)

Inline essentials only: probe-don't-tag (if cheaply verifiable, measure instead of tagging), PLAN=intent · WRAP/DECISIONS=fact, do not hide inferences. Details in the references above.

Step 0: Route — Complexity Assessment

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

Complexity Signals

• 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 present the PLAN inline.

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. Present PLAN: Present the PLAN inline in the conversation (do NOT enter plan mode), then immediately call /implement. The plan file must be written to .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. Present PLAN inline → immediately call /implement (no plan mode entry)

DECISIONS.md Recording (MUST)

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

## 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: The PLAN must be written to .dev/specs/{name}/PLAN.md.

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

NEXT STEP (Auto-execute)

After presenting the PLAN inline, call /implement immediately. Do NOT enter plan mode; do not ask "Should I implement?".