Writing Plans

This skill is for turning UNDERSTOOD requirements into EXECUTABLE plans.

The Planning Flow

digraph planning {
    "Gather context" [shape=box];
    "Enough to plan?" [shape=diamond];
    "Define tasks" [shape=box];
    "Each task actionable?" [shape=diamond];
    "Add detail" [shape=box];
    "Write plan" [shape=box];
    "Present plan" [shape=doublecircle];

    "Gather context" -> "Enough to plan?";
    "Enough to plan?" -> "Define tasks" [label="yes"];
    "Enough to plan?" -> "Gather context" [label="no — research first"];
    "Define tasks" -> "Each task actionable?";
    "Each task actionable?" -> "Write plan" [label="yes"];
    "Each task actionable?" -> "Add detail" [label="no — missing files/steps"];
    "Add detail" -> "Each task actionable?";
    "Write plan" -> "Present plan";
}

Step 1: Gather Context

Before writing any plan, build a concrete picture of the codebase:

1. Identify the project's structure — read config files, manifests, directory layout
2. Find the test runner and linter — exact commands the project uses
3. Read existing code at the points where changes will land — not just the entry point, but the files you'll modify
4. Check for patterns — how does existing code handle similar concerns? Follow those patterns.

Use available tools (file search, code search, MCP integrations) to gather this context. Do not plan from assumptions about project structure.

Step 2: Define Tasks

Break the work into tasks where each task:

• Is one coherent change (may touch multiple files)
• Ends at a verification boundary — a point where a specific command proves it worked
• Follows TDD when the project has tests: write test → verify it fails → implement → verify it passes → commit

Target: 3-7 tasks. Fewer than 3 means tasks are too coarse. More than 7 means the scope is too large or tasks are too granular.

Step 3: Write the Plan

Present the plan in conversation. Persist to a file only if requested.

Plan Format

# [Feature Name] Implementation Plan

**Goal:** [One sentence — what is done when the plan is complete]

**Architecture:** [2-3 sentences — approach and key design decisions]

**Test/lint commands:** [Exact commands used to verify throughout]

---

### Task 1: [Descriptive Name]

**Files:**
- Create: `exact/path/to/new_file.py`
- Modify: `exact/path/to/existing.py`
- Test: `tests/exact/path/to/test_file.py`

**Step 1: Write the failing test**

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

**Step 2: Run test — expect FAIL**

Run: `pytest tests/path/test_file.py::test_specific_behavior -v`
Expected: FAIL — `NameError: name 'function' is not defined`

**Step 3: Implement**

```python
def function(input):
    return expected
```

**Step 4: Run test — expect PASS**

Run: `pytest tests/path/test_file.py::test_specific_behavior -v`
Expected: PASS

**Step 5: Commit**

```bash
git add tests/path/test_file.py src/path/new_file.py
git commit -m "feat: add specific behavior"
```

---

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

Non-negotiable elements in every task:

• Exact file paths (not "the config file" — which config file)
• Complete code (not "add validation" — what validation, exactly)
• Exact verification commands with expected output
• Commit step with specific message and file list

Red Flags — Bad Plans

Rationalization Table

Degrees of Freedom

After Planning

Once the plan is written, route to the appropriate next step:

• Plan is ready to execute → If the executing-plans skill is available, invoke it. Otherwise, execute tasks sequentially, verifying each before starting the next.
• Plan reveals unknowns that block task detail → Investigate before proceeding. If the deep-research skill is available, invoke it for the specific unknowns.
• Scope is larger than expected (>7 tasks) → Decompose into phases. If the task-decomposition skill is available, invoke it to break the work into plannable chunks.

Do not hand off a plan with vague tasks. Every task in the plan must pass the Iron Law before execution begins.