writing-plans

Purpose

Turn a spec into a detailed, executable multi-step implementation plan. Prevents implementation drift and gives any engineer — or agent — enough detail to build without guessing.

When to Use

• Before implementing any multi-subsystem or non-trivial feature.
• When a spec or requirements document exists and needs to become actionable tasks.
• When the implementation requires coordinating multiple files or components.

If the spec covers multiple independent subsystems, break it into separate plans — one per subsystem. Each plan should produce working, testable software on its own.

Inputs

• Spec or requirements document.
• Access to the codebase (for file paths and existing patterns).

Workflow

1. Scope check — Identify all affected subsystems. If multiple independent subsystems, suggest separate plans.

2. Design file structure — Before defining tasks, map which files will be created or modified and what each is responsible for. Units should have clear boundaries, focused responsibility, and well-defined interfaces.

3. Write the plan header:

   # [Feature Name] Implementation Plan
   
   **Goal:** [One sentence describing what this builds]
   
   **Architecture:** [2-3 sentences about approach]
   
   **Tech Stack:** [Key technologies/libraries]
   
   ---
   

4. Break work into bite-sized tasks — Each step should take 2–5 minutes:

   • "Write the failing test" — step
   • "Run it to verify it fails" — step
   • "Implement the minimal code to pass the test" — step
   • "Run tests and confirm pass" — step
   • "Commit" — step

5. Write each task using this structure:

   ### Task N: [Component Name]
   
   **Files:**
   - Create: `exact/path/to/file.py`
   - Modify: `exact/path/to/existing.py`
   - Test: `tests/exact/path/to/test.py`
   
   - [ ] **Step 1:** [Action]
   ```code
   # Actual code here
   ```
   - [ ] **Step 2:** Run: `<exact command>`
     Expected: `<exact output>`
   

6. No placeholders — These are plan failures; never write them:

   TBD / TODO / implement later / fill in details
   "Add appropriate error handling" / "handle edge cases"
   "Write tests for the above" (without actual test code)
   "Similar to Task N" (repeat the code — engineer may read tasks out of order)
   Steps that describe without showing how (code blocks required for code steps)