---
description: How to create effective implementation plans with phased delivery and clear success criteria
---

# Planning

Create implementation plans that enable incremental, verifiable progress.

## Core Principles

1. **Incremental delivery**: Each phase should produce working, testable changes
2. **Clear checkpoints**: Success criteria that can be verified without ambiguity
3. **Buy-in before detail**: Confirm understanding and approach before writing specifics
4. **Explicit scope**: State what we're NOT doing to prevent scope creep

## Plan Document Structure

```markdown
# {Feature} Implementation Plan

## Overview
{1-2 sentences: what we're building and why}

## Current State Analysis
{What exists now, key constraints, file:line references}

## Desired End State
{Specification of outcome and how to verify it}

## What We're NOT Doing
{Explicit out-of-scope items}

## Phase 1: {Descriptive Name}
### Overview
{What this phase accomplishes - should be independently valuable}

### Changes Required
{Specific files and modifications with code snippets}

### Success Criteria
#### Automated Verification
- [ ] Tests pass: `{test command}`
- [ ] Lint passes: `{lint command}`

#### Manual Verification
- [ ] {Human-observable outcome}

## Testing Strategy
{Unit tests, integration tests, manual testing steps}

## References
{Links to research, related files, similar implementations}
```

## Phase Design

Good phases are:
- **Self-contained**: Completable in one session
- **Testable**: Has clear pass/fail criteria
- **Reversible**: Can be rolled back if needed
- **Incremental**: Builds on previous phases without requiring all phases

Bad phases are:
- "Refactor everything" (too broad)
- "Add helper function" (too granular)
- Phases that only work if ALL phases complete

## Success Criteria Guidelines

**Automated Verification** (agent-runnable):
- Test commands: `make test`, `npm test`, `nix flake check`
- Lint/format: `make lint`, `cargo fmt --check`
- Type checking: `make typecheck`, `tsc --noEmit`
- Build verification: `make build`, `nix build`

**Manual Verification** (requires human):
- UI/UX functionality and appearance
- Performance under realistic conditions
- Edge cases hard to automate
- Integration with external systems

**From Contribution Guidelines** (if CONTRIBUTING.md exists):
- Include any testing requirements specified
- Reference the guideline: "Per CONTRIBUTING.md: {requirement}"

## Presenting Understanding

Before writing the plan, confirm alignment:

```
Based on the requirements and my research, I understand we need to [summary].

I've found that:
- [Current implementation detail with file:line]
- [Relevant pattern or constraint]
- [Potential complexity identified]

Questions my research couldn't answer:
- [Specific technical question requiring judgment]
```

Only ask questions you genuinely cannot answer through code investigation.

## Design Options Pattern

When multiple approaches exist:

```
**Design Options:**
1. [Option A] - [1-sentence description]
   - Pro: [benefit]
   - Con: [drawback]

2. [Option B] - [1-sentence description]
   - Pro: [benefit]
   - Con: [drawback]

Which approach aligns best with [relevant consideration]?
```

Get buy-in on approach before detailing phases.