planning-patterns

What this skill does

# Writing Plans

## Overview

Write comprehensive implementation plans assuming the engineer has zero context for the codebase and questionable taste. Document everything they need to know: which files to touch for each task, code, testing, docs they might need to check, how to test it. Give them the whole plan as bite-sized tasks. DRY. YAGNI. TDD. Frequent commits.

**Plans are prompts.** The plan will be consumed by an AI agent with zero prior context. Write it as you would write a prompt: specific, complete, unambiguous. If a different agent could misinterpret a step, the step is underspecified.

Assume they are a skilled developer, but know almost nothing about the toolset or problem domain. Assume they don't know good test design very well.

**Core principle:** Plans must be executable without asking questions.

## The Iron Law

```
NO VAGUE STEPS - EVERY STEP IS A SPECIFIC ACTION
```

"Add validation" is not a step. "Write test for empty email, run it, implement check, run it, commit" - that's 5 steps.

## Bite-Sized Task Granularity

**Each step is one action (2-5 minutes):**

- "Write the failing test" - step
- "Run it to make sure it fails" - step
- "Implement the minimal code to make the test pass" - step
- "Run the tests and make sure they pass" - step
- "Commit" - step

**Not a step:**

- "Add authentication" (too vague)
- "Implement the feature" (multiple actions)
- "Test it" (which tests? how?)

Treat plan phases as a directed acyclic graph — each phase may only depend on predecessors, never on future phases. The plan-review-gate enforces this ordering.

**Decomposition trigger:** If a step touches 3+ files or takes more than one sentence to describe, split it. If a phase has >5 tasks, consider splitting the phase. Individual steps target 2-5 minutes; task clusters (a full RED-GREEN-REFACTOR cycle) up to 15 minutes.

## Plan Document Header

**Every plan MUST start with this header:**

```markdown
# [Feature Name] Implementation Plan

> **For Claude:** REQUIRED: Follow this plan task-by-task using TDD.
> **Design:** See `docs/plans/YYYY-MM-DD-<feature>-design.md` for full specification.

**Goal:** [One sentence describing what this builds]

**Architecture:** [2-3 sentences about approach]

**Tech Stack:** [Key technologies/libraries]

**Prerequisites:** [What must exist before starting]

**Durable Decisions:** [Foundational choices that apply across all phases — route structures, DB schema shape, key data models, auth approach, third-party service boundaries. Every phase references these.]

---
```

If a design document exists, always reference it in the header.

## Task Structure

```markdown
### Task N: [Component Name]

**Files:**
- Create: `exact/path/to/file.ts`
- Modify: `exact/path/to/existing.ts:123-145`
- Test: `tests/exact/path/to/test.ts`

**Step 1: Write the failing test**

```typescript
test('specific behavior being tested', () => {
  const result = functionName(input);
  expect(result).toBe(expected);
});
```

**Step 2: Run test to verify it fails**

Run: `npm test tests/path/test.ts -- --grep "specific behavior"`
Expected: FAIL with "functionName is not defined"

**Step 3: Write minimal implementation**

```typescript
function functionName(input: InputType): OutputType {
  return expected;
}
```

**Step 4: Run test to verify it passes**

Run: `npm test tests/path/test.ts -- --grep "specific behavior"`
Expected: PASS

**Step 5: Commit**

```bash
git add tests/path/test.ts src/path/file.ts
git commit -m "feat: add specific feature"
```
```

## Context is King (Cole Medin Principle)

**The plan must contain ALL information for a single-pass implementation.**

A developer with zero codebase context should be able to execute the plan WITHOUT asking any questions.

### Context References Section (MUST READ!)

**Every plan MUST include a Context References section:**

```markdown
## Relevant Codebase Files

### Patterns to Follow
- `src/components/Button.tsx` (lines 15-45) - Component structure pattern
- `src/services/api.ts` (lines 23-67) - API service pattern

### Configuration Files
- `tsconfig.json` - TypeScript settings
- `.env.example` - Environment variables needed

### Related Documentation
- `docs/architecture.md#authentication` - Auth flow overview
- `README.md#running-tests` - Test commands
```

**Why:** Claude forgets context. External docs get stale. File:line references are always accurate.

### Distillation Rule

Plans MUST use distilled content, not summarized. Distilled = lossless compression preserving every entity, relationship, decision, and constraint. Summarized = lossy reduction that drops specifics. If a plan section can be shortened without losing any fact the builder needs, distill it. If shortening requires dropping facts, keep the full version. Test: Could a builder agent execute from this plan alone without re-reading source files? If not, the plan is under-distilled.

## Validation Levels

**Match validation depth to plan complexity:**

| Level | Name | Commands | When |
|-------|------|----------|------|
| 1 | Syntax & Style | `npm run lint`, `tsc --noEmit` | Every task |
| 2 | Unit Tests | `npm test` | Low-Medium risk |
| 3 | Integration Tests | `npm run test:integration` | Medium-High risk |
| 4 | Manual Validation | User flow walkthrough | High-Critical risk |

**Include specific validation commands in each task step.**

## Production-Like Verification Planning

When the request needs real APIs, seeded data, browser flows, background jobs, or stress/load behavior, read `references/live-verification-strategy.md` before finalizing the plan.

Use that reference to add a `### Live Verification Strategy` section that names:
- harness manifest path
- setup, reset, seed, health, and cleanup commands
- first-party system boundaries vs external dependencies
- named proof scenarios with Given/When/Then
- stress profile and pass thresholds when load behavior matters

Do not silently downgrade production-like verification into replay-only, unit-only, or manual-only steps. If the live harness does not exist yet, keep that gap explicit in the plan.

## Requirements Checklist

Before writing a plan:

- [ ] Problem statement clear
- [ ] Users identified
- [ ] Functional requirements listed
- [ ] Non-functional requirements listed (performance, security, scale)
- [ ] Constraints documented
- [ ] Success criteria defined
- [ ] Existing code patterns understood
- [ ] Context References section prepared with file:line references

## Plan Completeness Gate

Before saving, verify every phase passes:

| Criterion | Test |
|-----------|------|
| **Definition of done** | Exit criteria are demonstrable and testable (not "Foundation complete") |
| **Measurable deliverables** | Each task names exact files to create/modify with file:line |
| **Realistic estimates** | No task exceeds 5 minutes; no phase exceeds 1 hour |
| **Dependencies explicit** | Phase N references only predecessors, never future phases |
| **Risk mitigation present** | Every risk with Score > 8 has a mitigation row |
| **Testable at each phase** | Each phase exit criteria can be verified by running a command |
| **Cross-phase contracts** | Phase N exit criteria include the exact data shape, API contract, or file structure that Phase N+1 expects |

A plan missing any row is incomplete. Revise before saving.

**Exit criteria by example:** Do not write "Phase 1 complete when auth works." Write "Phase 1 complete when `curl -X POST /api/auth/login -d '{"email":"[email protected]","password":"pass"}' returns 200 with `{token: string}`." Concrete input/output examples prevent misinterpretation.

## Risk Assessment Table

Classify each risk into one of four dimensions before scoring:

| Dimension | What to assess |
|-----------|---------------|
| **Technical** | Complexity beyond team experience, unknown libraries, integration unknowns |
| **Timeline** | Estimation uncertainty, resource availability, external dependency delivery dates |
| **Quality** | Testing ga