writing-plans

# Writing Implementation Plans ## Overview Write comprehensive implementation plans assuming the implementer has zero context for the codebase and questionable taste. Document everything they need: which files to touch, complete code, testing commands, docs to check, how to verify. Give them bite-sized tasks. DRY. YAGNI. TDD. Frequent commits. Assume the implementer is a skilled developer but knows almost nothing about the toolset or problem domain. Assume they don't know good test design very well. **Core principle:** A good plan makes implementation obvious. If someone has to guess, the plan is incomplete. ## When to Use **Always use before:** - Implementing multi-step features - Breaking down complex requirements - Executing a staged plan with verification after each task **Don't skip when:** - Feature seems simple (assumptions cause bugs) - You plan to implement it yourself (future you needs guidance) - Working alone (documentation matters) ## Bite-Sized Task Granularity **Each task = 2-5 minutes of focused work.** Every step is one action: - "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 **Too big:** ```markdown ### Task 1: Build authentication system [50 lines of code across 5 files] ``` **Right size:** ```markdown ### Task 1: Create User model with email field [10 lines, 1 file] ### Task 2: Add password hash field to User [8 lines, 1 file] ### Task 3: Create password hashing utility [15 lines, 1 file] ``` ## Plan Document Structure ### Header (Required) Every plan MUST start with: ```markdown # [Feature Name] Implementation Plan > **For Miki:** Execute this plan task-by-task with verification after each step. **Goal:** [One sentence describing what this builds] **Architecture:** [2-3 sentences about approach] **Tech Stack:** [Key technologies/libraries] --- ``` ### Task Structure Each task follows this format: ````markdown ### Task N: [Descriptive Name] **Objective:** What this task accomplishes (one sentence) **Files:** - Create: `exact/path/to/new_file.py` - Modify: `exact/path/to/existing.py:45-67` (line numbers if known) - Test: `tests/path/to/test_file.py` **Step 1: Write failing test** ```python def test_specific_behavior(): result = function(input) assert result == expected ``` **Step 2: Run test to verify failure** Run: `pytest tests/path/test.py::test_specific_behavior -v` Expected: FAIL — "function not defined" **Step 3: Write minimal implementation** ```python def function(input): return expected ``` **Step 4: Run test to verify pass** Run: `pytest tests/path/test.py::test_specific_behavior -v` Expected: PASS **Step 5: Commit** ```bash git add tests/path/test.py src/path/file.py git commit -m "feat: add specific feature" ``` ```` ## Writing Process ### Step 1: Understand Requirements Read and understand: - Feature requirements - Design documents or user description - Acceptance criteria - Constraints ### Step 2: Explore the Codebase Use Miki tools to understand the project: ```python # Understand project structure search_files("*.py", target="files", path="src/") # Look at similar features search_files("similar_pattern", path="src/", file_glob="*.py") # Check existing tests search_files("*.py", target="files", path="tests/") # Read key files read_file("src/app.py") ``` ### Step 3: Design Approach Decide: - Architecture pattern - File organization - Dependencies needed - Testing strategy ### Step 4: Write Tasks Create tasks in order: 1. Setup/infrastructure 2. Core functionality (TDD for each) 3. Edge cases 4. Integration 5. Cleanup/documentation ### Step 5: Add Complete Details For each task, include: - **Exact file paths** (not "the config file" but `src/config/settings.py`) - **Complete code examples** (not "add validation" but the actual code) - **Exact commands** with expected output - **Verification steps** that prove the task works ### Step 6: Review the Plan Check: - [ ] Tasks are sequential and logical - [ ] Each task is bite-sized (2-5 min) - [ ] File paths are exact - [ ] Code examples are complete (copy-pasteable) - [ ] Commands are exact with expected output - [ ] No missing context - [ ] DRY, YAGNI, TDD principles applied ### Step 7: Save the Plan ```bash mkdir -p docs/plans # Save plan to docs/plans/YYYY-MM-DD-feature-name.md git add docs/plans/ git commit -m "docs: add implementation plan for [feature]" ``` ## Principles ### DRY (Don't Repeat Yourself) **Bad:** Copy-paste validation in 3 places **Good:** Extract validation function, use everywhere ### YAGNI (You Aren't Gonna Need It) **Bad:** Add "flexibility" for future requirements **Good:** Implement only what's needed now ```python # Bad — YAGNI violation class User: def __init__(self, name, email): self.name = name self.email = email self.preferences = {} # Not needed yet! self.metadata = {} # Not needed yet! # Good — YAGNI class User: def __init__(self, name, email): self.name = name self.email = email ``` ### TDD (Test-Driven Development) Every task that produces code should include the full TDD cycle: 1. Write failing test 2. Run to verify failure 3. Write minimal code 4. Run to verify pass See `test-driven-development` skill for details. ### Frequent Commits Commit after every task: ```bash git add [files] git commit -m "type: description" ``` ## Common Mistakes ### Vague Tasks **Bad:** "Add authentication" **Good:** "Create User model with email and password_hash fields" ### Incomplete Code **Bad:** "Step 1: Add validation function" **Good:** "Step 1: Add validation function" followed by the complete function code ### Missing Verification **Bad:** "Step 3: Test it works" **Good:** "Step 3: Run `pytest tests/test_auth.py -v`, expected: 3 passed" ### Missing File Paths **Bad:** "Create the model file" **Good:** "Create: `src/models/user.py`" ## Execution Handoff After saving the plan, offer the execution approach: **"Plan complete and saved. Ready to execute task-by-task with verification after each step. Shall I proceed?"** When executing: - Complete one task at a time with the required context loaded from disk - Review spec compliance after each task - Review code quality after spec passes - Proceed only when both reviews approve ## Remember ``` Bite-sized tasks (2-5 min each) Exact file paths Complete code (copy-pasteable) Exact commands with expected output Verification steps DRY, YAGNI, TDD Frequent commits ``` **A good plan makes implementation obvious.**