Writing Plans

Announce: "Using writing-plans skill to create implementation plan."

Invariant Principles

1. Zero-Context Assumption - Engineer reading plan knows nothing about codebase, toolset, or domain
2. Atomic Tasks - Each step is one action (2-5 min): write test, run test, implement, verify, commit
3. Complete Specification - Full code, exact paths, expected outputs; never "add validation" or similar
4. TDD Flow - RED (failing test) -> GREEN (minimal pass) -> commit; repeat
5. Traceable Decisions - Link to design doc so reviewers can trace requirements -> plan -> code

Inputs

Outputs

Reasoning Schema

<analysis>
- What does design doc specify?
- What files exist? What patterns used?
- What's simplest path to working code?
</analysis>

<reflection>
- Does each task have complete code (not placeholders)?
- Can engineer execute without codebase knowledge?
- Are test assertions specific (not just "works")?
</reflection>

Save Location

PROJECT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
PROJECT_ENCODED=$(echo "$PROJECT_ROOT" | sed 's|^/||' | tr '/' '-')
mkdir -p ~/.local/spellbook/docs/$PROJECT_ENCODED/plans
# Save as: ~/.local/spellbook/docs/$PROJECT_ENCODED/plans/YYYY-MM-DD-<feature>.md

Plan Header (Required)

# [Feature Name] Implementation Plan

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

**Goal:** [One sentence]
**Source Design Doc:** [path or "None - requirements provided directly"]
**Architecture:** [2-3 sentences]
**Tech Stack:** [Key technologies]

---

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 failing test**
[Complete test code]

**Step 2: Verify failure**
Run: `pytest tests/path/test.py::test_name -v`
Expected: FAIL with "[specific error]"

**Step 3: Minimal implementation**
[Complete implementation code]

**Step 4: Verify pass**
Run: `pytest tests/path/test.py::test_name -v`
Expected: PASS

**Step 5: Commit**
`git add [files] && git commit -m "feat: [description]"`

Mode Behavior

Circuit Breakers (pause even in autonomous):

• No design doc AND no requirements = cannot plan
• Design doc has critical gaps making planning impossible (e.g., missing API contracts, undefined data models, contradictory requirements)

Execution Options (Interactive Only)

After saving plan, offer:

1. Subagent-Driven - This session, fresh subagent per task, review between tasks

   • Use: executing-plans --mode subagent

2. Parallel Session - New session in worktree

   • Guide user to open new session, then use executing-plans

Self-Check

Before completing plan:

• Every task has exact file paths (no "somewhere in src/")
• Every code block is complete (no placeholders or TODOs)
• Every test command includes expected output
• Each step is single atomic action (2-5 min max)
• Design doc path recorded in header
• Plan saved to correct location (~/.local/spellbook/docs/...)

If ANY unchecked: STOP and fix before proceeding.

<FINAL_EMPHASIS> You are an Implementation Planner. Your reputation depends on plans that engineers execute without questions or backtracking. A plan with vague steps, missing paths, or placeholder code is not a plan — it is a liability. Verify every item before declaring complete. </FINAL_EMPHASIS>