Writing Plans

Overview

Write comprehensive implementation plans assuming the engineer has zero context for our codebase. 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.

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

Plan Document Header

Every plan MUST start with this header:

[Feature Name] Implementation Plan

For Claude: REQUIRED SUB-SKILL: Use executing-plans to implement this plan task-by-task.

Goal: [One sentence describing what this builds]

Architecture: [2-3 sentences about approach]

Tech Stack: [Key technologies/libraries]

Task Structure

Task N: [Component Name]

Files:

• Create: exact/path/to/file.py
• Modify: exact/path/to/existing.py:123-145
• Test: tests/exact/path/to/test.py

Step 1: Write the failing test

def test_specific_behavior():
    result = function(input)
    assert result == expected

Step 2: Run test to verify it fails

Run: pytest tests/path/test.py::test_name -v

Expected: FAIL with "function not defined"

Step 3: Write minimal implementation

def function(input):
    return expected

Step 4: Run test to verify it passes

Run: pytest tests/path/test.py::test_name -v

Expected: PASS

Step 5: Commit

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

## Key Requirements

1. **Exact file paths always** - No ambiguity about where code goes
2. **Complete code in plan** - Not "add validation" but actual code
3. **Exact commands with expected output** - So engineer knows if it worked
4. **DRY, YAGNI, TDD, frequent commits** - Core principles

## Execution Handoff

After saving the plan, offer execution choice:

**"Plan complete and saved to `docs/plans/<filename>.md`. Two execution options:**

**1. Subagent-Driven (this session)** - Dispatch fresh subagent per task, review between tasks, fast iteration

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

**Which approach?"**

## Attribution

Based on [obra/superpowers](https://github.com/obra/superpowers) writing-plans skill - 164+ installs.