/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 | Present PLAN inline → /implement |

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)

| When | File | |------|------| | Tagging provenance on key decisions/assumptions / probe decisions | `references/provenance.md` | | Pre-PLAN user confirmation | `references/checkpoint.md` | | When document authority/reading order is unclear | `references/doc-roles.md` | | Full Deep path procedure | `deep/DEEP.md` | | PLAN/DRAFT structure (Lite/Full + Clarify Verdict) | `templates/` |

> 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

| 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 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:

| 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**: 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?".