/writing-plans

name: dev-writing-plans
description: "Write implementation plans: bite-sized tasks, paths, code."
version: 1.1.0
author: Hermes Agent (adapted from obra/superpowers)
license: MIT
metadata:
  hermes:
    tags: [planning, design, implementation, workflow, documentation]
    related_skills: [subagent-driven-development, test-driven-development, requesting-code-review]
origin: adapted
source_repo: obra/superpowers
source_url: https://github.com/obra/superpowers
source_license: MIT
language: en

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
• Delegating to subagents via subagent-driven-development

**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:**

### Task 1: Build authentication system
[50 lines of code across 5 files]

**Right size:**

### 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:

# [Feature Name] Implementation Plan

> **For Hermes:** Use subagent-driven-development skill to implement this plan task-by-task.

**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:

### 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**

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**

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 Hermes 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

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

# 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:

git add [fil