dev-design

What this skill does

**Announce:** "Using dev-design (Phase 4) to propose implementation approaches and obtain user approval."

**Iteration topology:** one-shot + fresh-subagent plan review (dev-plan-reviewer)

### Context Check

Before starting this phase, check remaining context:

| Level | Remaining | Action |
|-------|-----------|--------|
| Normal | >35% | Proceed |
| Warning | 25-35% | Finish the current step, then invoke dev-handoff |
| Critical | ≤25% | Invoke dev-handoff immediately — resume fresh |

At Warning/Critical: Read `${CLAUDE_SKILL_DIR}/../../skills/dev-handoff/SKILL.md` and follow its instructions.

## Contents

- [The Iron Law of Design](#the-iron-law-of-design)
- [What Design Does](#what-design-does)
- [Process](#process)
- [Approach Categories](#approach-categories)
- [PLAN.md Format](#planmd-format)
- [Design Facts](#design-facts)
- [Output](#output)

# Architecture Design with User Gate

Propose implementation approaches, explain trade-offs, get user approval.
**Prerequisites:** SPEC.md finalized, exploration complete, clarifications resolved.

## Prerequisite: dev-clarify Must Be Complete

**dev-design REQUIRES dev-clarify to be complete. This is not optional.**

Before writing PLAN.md, verify these clarify gates passed:
- [ ] Testing approach documented (unit/integration/E2E)
- [ ] Test framework specified
- [ ] First test described
- [ ] Test command documented
- [ ] User workflow confirmed

**If ANY gate is unchecked → DO NOT START DESIGN. Return to dev-clarify.**

<EXTREMELY-IMPORTANT>
## The Iron Law of Design

**YOU MUST GET USER APPROVAL BEFORE IMPLEMENTATION. This is not negotiable.**

After presenting approaches:
1. Show 2-3 options with trade-offs
2. Lead with your recommendation
3. **Ask user which approach**
4. **Wait for explicit approval**

Implementation CANNOT start without user saying "Yes" or choosing an approach.

**STOP - you're about to implement without user approval.**
</EXTREMELY-IMPORTANT>

## What Design Does

| DO | DON'T |
|----|-------|
| Propose 2-3 approaches | Implement anything |
| Explain trade-offs clearly | Make the choice for user |
| Lead with recommendation | Present without opinion |
| Get explicit approval | Assume approval |
| Write PLAN.md | Skip the user gate |

**Design answers: HOW to build it and WHY this approach**
**Implement executes: the approved approach** (next phase, after gate)

## Process

### 1. Review Inputs

Before designing, ensure the following exist:
- `.planning/SPEC.md` - final requirements
- Exploration findings - key files, patterns
- Clarified decisions - edge cases, integrations

### 2. Propose 2-3 Approaches

Each approach should address the same requirements differently:

**Approach A: Minimal Changes**
- Smallest diff, maximum reuse
- Trade-off: May be less clean, tech debt

**Approach B: Clean Architecture**
- Best patterns, maintainability
- Trade-off: More changes, longer implementation

**Approach C: Pragmatic Balance**
- Balance of speed and quality
- Trade-off: Compromise on both

### 3. Present with Trade-offs

Use the AskUserQuestion tool to present approaches:

```python
# AskUserQuestion: Present 2-3 architecture approaches with trade-offs for user selection
AskUserQuestion(questions=[{
  "question": "Which architecture approach should we use?",
  "header": "Architecture",
  "options": [
    {
      "label": "Pragmatic Balance (Recommended)",
      "description": "Extend existing AuthService with new method. ~150 lines changed. Balances reuse with clean separation."
    },
    {
      "label": "Minimal Changes",
      "description": "Add logic to existing endpoint. ~50 lines changed. Fast but increases coupling."
    },
    {
      "label": "Clean Architecture",
      "description": "New service with full abstraction. ~300 lines. Most maintainable but longest to build."
    }
  ],
  "multiSelect": false
}])
```

**Key principles:**
- Lead with recommendation (first option + "Recommended")
- Concrete numbers (lines changed, files affected)
- Clear trade-offs for each
- Reference specific files from exploration

#### Log the review pattern (observe → record → offer)

After the user makes this `decision` selection, append one line to `.planning/LEARNINGS.md` recording **what the user attended to** before choosing — e.g. "compared lines-changed across options", "asked for the dependency graph", "approved on the recommendation without detail", "wanted to see affected files". Do NOT build any visualization speculatively.

**Offer rule:** if `.planning/LEARNINGS.md` shows the **same review artifact requested 3+ times** across episodes (e.g. the user keeps asking for a dependency graph or a diff summary before approving), offer to bundle a script under `skills/dev-design/scripts/` that generates that view automatically. Build it only after the 3rd occurrence — observed behavior first, automation after.

When the offer triggers, map the observed request to a concrete artifact:

| If the user keeps asking for… | Consider building |
|-------------------------------|-------------------|
| "show me what changed / a diff" | Interactive diff explorer (self-contained HTML) |
| "what's the architecture / dependencies?" | Dependency graph or codebase tree |
| "which files does this touch?" | Affected-files map from PLAN.md `affects:` |
| "how big is each approach?" | Lines-changed / files-touched comparison table |

Bundle the script in `skills/dev-design/scripts/`; the phase offers to run it — it never forces it.

### 4. Feature Decomposition Check

**CRITICAL:** Before writing PLAN.md, check if this is actually multiple features.

Review the scope and ask:

```python
# AskUserQuestion: Determine if feature should be split into independent tasks
AskUserQuestion(questions=[{
  "question": "Is this one cohesive feature or multiple independent features?",
  "header": "Scope",
  "options": [
    {
      "label": "One feature",
      "description": "Implement everything together in one branch/worktree"
    },
    {
      "label": "Multiple features",
      "description": "Break into separate features, each with own branch/worktree/PR"
    }
  ],
  "multiSelect": false
}])
```

**If "Multiple features":**

1. **List the independent features** identified from SPEC.md:
   ```
   Based on the requirements, this breaks into:
   1. Theme infrastructure (color system, theme provider)
   2. Settings UI (theme selector component)
   3. Component updates (update 20+ components to use theme)
   4. Persistence layer (save user preference)

   Each can be implemented and PR'd independently.
   ```

2. **Ask which to tackle first:**
   ```python
   # AskUserQuestion: Prioritize which feature to implement first
   AskUserQuestion(questions=[{
     "question": "Which feature should we implement first?",
     "header": "Priority",
     "options": [
       {"label": "Theme infrastructure (Recommended)", "description": "Foundation that others depend on"},
       {"label": "Settings UI", "description": "UI for theme selection"},
       {"label": "Component updates", "description": "Apply themes to components"},
       {"label": "Persistence layer", "description": "Save user preference"}
     ],
     "multiSelect": false
   }])
   ```

3. **Write PLAN.md for ONLY the chosen feature**

4. **Document remaining features** in `.planning/BACKLOG.md`:
   ```markdown
   # Feature Backlog

   ## Dark Mode Implementation

   ### Completed
   - [ ] None yet

   ### Next Up
   - [ ] Theme infrastructure
   - [ ] Settings UI
   - [ ] Component updates
   - [ ] Persistence layer

   **Current Focus:** Theme infrastructure
   ```

**If "One feature":**

Proceed to write PLAN.md for the entire scope (step 5 below).

**Why this matters:**

- Multiple features in one branch = massive PR, review hell, merge conflicts
- Separate features = clean PRs, incremental progress, easier reviews
- After first feature PR merges, come back and tackle next feature

### 4b. Prose Section Audit (MANDATORY)

**Before writing PLAN.md, scan