Writing Plans

Writing Plans

Core Principle

Write plans clear enough for an enthusiastic junior engineer with poor taste, no judgement, no project context, and an aversion to testing to follow.

Plan Structure

Save plans to: docs/plans/YYYY-MM-DD-<feature-name>.md

# [Feature Name] Implementation Plan

> **For Claude:** Use executing-plans skill to implement this plan task-by-task.

## Overview
Brief description of what we're building and why.

## Prerequisites
- [ ] Dependency 1 installed
- [ ] Service 2 running
- [ ] Access to X configured

## Tasks

### Task 1: [Descriptive Name]
**File:** `path/to/file.ts`
**Test:** `path/to/file.test.ts`

#### Test First (RED)

// Exact test code to write describe('FeatureName', () => { it('should do specific thing', () => { // Arrange // Act // Assert }); });

#### Implementation (GREEN)

// Exact implementation code export function featureName() { // Implementation }

#### Verification

npm test -- --grep "FeatureName"

Expected: 1 passing

### Task 2: [Next Task]
...

## Integration Tests
After all tasks complete:

Commands to run

npm run test:integration

## Manual Verification
Steps to manually verify the feature works:
1. Step 1
2. Step 2
3. Expected result

## Rollback Plan
If something goes wrong:
1. `git revert HEAD`
2. ...

Plan Quality Checklist

Every Task Must Have:

• [ ] Exact file paths
• [ ] Complete code (not "add validation")
• [ ] Test written BEFORE implementation
• [ ] Verification command with expected output
• [ ] Clear success criteria

Plan Must Include:

• [ ] Prerequisites listed
• [ ] Tasks in dependency order
• [ ] Integration test at end
• [ ] Rollback instructions

Writing Guidelines

Be Explicit

❌ "Add error handling" ✅ "Wrap the API call in try/catch, log errors with context, return null on failure"

Be Complete

❌ "Update the config" ✅ ```json { "setting": "value", "newSetting": "newValue" }

### Be Ordered
Tasks should be executable in sequence:
1. No forward dependencies
2. Each task builds on previous
3. Tests pass after each task

## Execution Handoff

After saving the plan, offer execution choice:

**"Plan complete and saved. Two execution options:**

**1. Subagent-Driven (this session)**
- Fresh subagent per task
- Review between tasks
- Fast iteration

**2. Parallel Session (separate)**
- Open new session with executing-plans skill
- Batch execution with checkpoints

**Which approach?"**

## DRY, YAGNI, TDD Reminders

Include at top of every plan:

Remember

• Exact file paths always
• Complete code in plan (not "add validation")
• Exact commands with expected output
• DRY, YAGNI, TDD, frequent commits

## Anti-Patterns

### Don't Do This
- Vague task descriptions
- Missing file paths
- Incomplete code snippets
- Implementation before tests
- No verification steps
- Assuming context