blueprint

Writing Implementation Plans

Write comprehensive implementation plans. Document everything needed: which files to touch, code to write, tests to run, commands to verify.

Core Principle

EVERY STEP MUST CONTAIN ACTUAL CONTENT.
No placeholders. No TBD. No "fill in later". Plan failures, not task failures.

Steps

Step 1: Scope Check

If the spec covers multiple independent subsystems, suggest breaking into separate plans — one per subsystem.

Step 2: Map File Structure

Before defining tasks, map out which files will be created or modified and what each is responsible for:

• Design units with clear boundaries and well-defined interfaces
• Prefer smaller, focused files over large ones
• Files that change together should live together
• In existing codebases, follow established patterns

Step 3: Break Into Bite-Sized Tasks

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

Step 4: Write Task Details

### 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**

```python
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**

```python
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: Self-Review

1. Spec coverage: Can you point to a task for each spec requirement?
2. Placeholder scan: Search for TBD, TODO, "implement later", "fill in details"
3. Type consistency: Do types and method signatures match across tasks?