writing-plans

name	writing-plans
description	Use when you have a spec or requirements for a multi-step task, before touching code

Writing Plans

Overview

Write comprehensive implementation plans assuming the engineer has zero context for the codebase. Document everything they need to know: which files to touch for each task, testing they might need to check, and how to verify it.

Announce at start: "I'm using the writing-plans skill to create the implementation plan."

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

Plans must preserve both:

• disciplined execution
• alignment with the original user intent

Bite-Sized Task Granularity

Each step is one action (2-5 minutes):

• "Capture the Intent Contract" - step
• "Write the failing test" - step when TDD is the right approach
• "Run it to make sure it fails" - step when TDD is used
• "Implement the minimal code to make the test pass" - step when TDD is used
• "Run the relevant verification" - step
• "Review evidence and remaining risks" - step

Plan Document Header

Every plan MUST start with this header:

# [Feature Name] Implementation Plan

**Goal:** [One sentence describing what this builds]

**Architecture:** [2-3 sentences about approach]

**Tech Stack:** [Key technologies/libraries]

## Intent Contract

- **Requested behavior:** [What the user wants to happen]
- **Must remain unchanged:** [What should not change]
- **Non-goals:** [What is explicitly out of scope]
- **Primary success scenario:** [Concrete example of correct outcome]
- **Important edge/failure scenario:** [If relevant]

---

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: Capture or confirm the Intent Contract**

- Restate requested behavior
- Restate non-goals
- Add one concrete success scenario

**Step 2: Choose verification strategy**

- Prefer the highest-signal proof for the risk
- If TDD is appropriate, say so explicitly
- If TDD is not the best fit, specify the alternative verification path

**Step 3: Write the failing test** *(only when TDD is appropriate)*

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

Step 4: Run test to verify it fails (only when TDD is used)

Run: pytest tests/path/test.py::test_name -v Expected: FAIL with "function not defined"

Step 5: Write minimal implementation

def function(input):
    return expected

Step 6: Run relevant verification

• Run the new high-signal test(s), or
• Run the relevant existing tests, or
• Run the direct verification steps defined for this change

Expected: evidence that the requested behavior works and unchanged behavior still holds where relevant

Step 7: Review remaining risks and follow-ups

• Note uncovered risks
• Note whether more tests are warranted later

## Remember
- Exact file paths always
- Complete code in plan (not "add validation")
- Exact commands with expected output
- Reference relevant skills with @ syntax
- DRY, YAGNI, strong verification, risk-based TDD when appropriate

## Verification Guidance

- Prefer one high-signal acceptance or integration test over many low-signal unit tests when it proves behavior better
- Keep strong unit tests for isolated risky logic
- If no new automated test is proposed, explain why existing coverage plus direct verification is enough
- Do not include commit steps unless the user explicitly requested commit workflow

## Execution Handoff

After saving the plan, proceed with the execution approach that best fits task size and risk:

- Use subagent-driven execution when the task is large, risky, or benefits from isolation
- Use lighter execution when the task is small and the main risk is over-orchestration
- Dispatch independent tasks in parallel where useful
- Preserve the Intent Contract through all execution steps