Plan documentation

Plan Documentation

Generate structured plan files when starting large features, refactoring efforts, or multi-phase work. Plans create a paper trail that survives context resets and helps collaborators understand what was planned, what changed, and why.

When to Generate Plan Files

Create a plan document when:

• The task spans more than 2 files or requires multiple coordinated changes
• Work will take more than one session or phase
• Multiple approaches exist and the chosen path should be documented
• Other people (or future you) need to understand the sequence of work

Do NOT create plan files for:

• Single-file fixes or tweaks
• Routine maintenance (dependency updates, formatting)
• Tasks that can be completed in under 15 minutes

Plan Document Template

Create the plan at plans/<task-slug>-plan.md in the project root.

# Plan: <Task Title>

Created: <ISO date>
Status: IN_PROGRESS | COMPLETE | ABANDONED

## Summary

<2-3 sentences explaining what this work accomplishes and why it matters.>

## Phases

### Phase 1: <Phase Title>
- [ ] Step 1 description
- [ ] Step 2 description
- [ ] Step 3 description

**Acceptance Criteria:**
- <What must be true when this phase is done>
- <Measurable or verifiable condition>

### Phase 2: <Phase Title>
- [ ] Step 1 description
- [ ] Step 2 description

**Acceptance Criteria:**
- <Condition>

### Phase N: <Phase Title>
...

## Open Questions

1. <Question about approach or requirement> -- Suggested: <Option A> vs <Option B>
2. <Question about scope> -- Suggested: <Option A> vs <Option B>
3. <Question about dependency or risk> -- Suggested: <Option A>

Keep open questions between 1-5. Each should have suggested options so they can be resolved quickly. Remove questions as they get answered -- move the decision to the relevant phase.

## Dependencies

- <External system, API, library, or team dependency>
- <Prerequisite work that must finish first>

## Risks

- <What could go wrong and how likely it is>
- <Mitigation strategy if applicable>

Phase Completion Template

After finishing each phase, create plans/<task-slug>-phase-N-complete.md:

# Phase N Complete: <Phase Title>

Completed: <ISO date>
Plan: <task-slug>-plan.md

## Phase N Summary

<1-2 sentences on what was accomplished.>

## What Changed

| File | Change |
|------|--------|
| `path/to/file.ts` | Added validation logic for user input |
| `path/to/test.ts` | 6 new unit tests for validation edge cases |

## What Was Tested

- <Test suite or manual verification performed>
- <Edge cases covered>
- <What was NOT tested and why>

## Decisions Made

- <Decision>: <Why this option was chosen over alternatives>

## Next Phase Preview

Phase N+1 will focus on <brief description>. Prerequisites met: <yes/no>.

Final Completion Template

When all phases are done, create plans/<task-slug>-complete.md:

# Complete: <Task Title>

Completed: <ISO date>
Plan: <task-slug>-plan.md
Duration: <how long the work took>

## Task Summary

<2-3 sentences on the full scope of work completed.>

## All Phases

| Phase | Title | Status |
|-------|-------|--------|
| 1 | <Title> | COMPLETE |
| 2 | <Title> | COMPLETE |
| N | <Title> | COMPLETE |

## Total Changes

- Files modified: <count>
- Files created: <count>
- Tests added: <count>
- Lines changed: <approximate>

## Lessons Learned

- <Insight that would help someone doing similar work>
- <Unexpected challenge and how it was resolved>
- <Pattern discovered that should be reused>

File Naming Convention

All plan files go in the plans/ directory at the project root.

File	Purpose
<task-slug>-plan.md	Initial plan with phases and acceptance criteria
<task-slug>-phase-N-complete.md	Completion record for phase N
<task-slug>-complete.md	Final completion summary

The <task-slug> should be a short, lowercase, hyphenated description of the task (e.g., auth-refactor, search-api-v2, dashboard-redesign).

Rules

• Write the plan BEFORE starting implementation
• Update phase status in the plan file as work progresses
• Do not skip phase completion docs -- they are the audit trail
• Keep summaries concise -- if it takes more than 3 sentences, it is too long
• Open questions should block work until resolved, not be ignored
• If the plan changes significantly mid-work, update the plan file and note what changed and why