---
name: writing-plans
description: "Write implementation plans: bite-sized tasks, paths, code."
version: 1.2.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]
---

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

## Risk-Adjusted Planning Granularity

Use two levels of detail instead of turning every mechanical action into a separately tracked milestone:

### Canonical / user-visible plan

Track **outcome-sized milestones** that produce something working and verifiable. A milestone should usually combine its internal RED → GREEN → integration work and take roughly 30 minutes to a few hours—not 2–5 minutes.

Examples:

- "Durable execution kernel supports forward claims, compensation, and atomic completion"
- "Fake executor resumes every supported crash state end to end"
- "Disposable tenant completes create/start/status/stop/delete with clean rollback"

The canonical plan should show current goal, milestone state, hard gates, blockers, and acceptance evidence. Do not expose every test invocation, helper, documentation edit, or commit as a first-class milestone.

### Implementer checklist

Inside an active milestone or delegation prompt, mechanical steps may still be 2–5 minutes:

- write the failing test;
- run it to confirm RED;
- implement the minimal coherent behavior;
- run focused GREEN;
- integrate and verify the milestone.

These are execution instructions, not separate program-management phases.

### Choose ceremony by risk

- **Pure/fake/in-memory work:** build an end-to-end outcome batch, then review once.
- **Security or durable-state boundary:** preserve strict tests and adversarial probes, but consolidate review at the working milestone boundary.
- **Real infrastructure/customer data/migration:** retain explicit preflight, rollback, and approval gates.
- **Docs, helper tests, and status updates:** do not trigger independent review cycles unless they change authority or safety semantics.

If the user says the work is taking too long, the plan has "been in progress all day," or asks to move faster, immediately audit planning overhead. Collapse adjacent internal phases, remove duplicate reviews/status updates, keep only hard safety gates, and state the shorter critical path.

## Plan Document Structure

### Header (Required)

Every plan MUST start with:

```markdown
# [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:

````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 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:
- [ ] Canonical milestones are outcome-sized and user-legible
- [ ] Mechanical 2–5 minute steps stay inside the active milestone/delegation prompt
- [ ] Tasks are sequential and logical
- [ ] File paths and commands are exact where implementation detail is needed
- [ ] Acceptance evidence is explicit
- [ ] Review cadence matches risk instead of repeating after every helper/sub-step
- [ ] Status updates occur at meaningful state changes, not after every test or commit
- [ ] DRY, YAGNI, TDD, and the shortest safe critical path are preserved

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

### Coherent Commits

Commit at coherent checkpoints, not after every mechanical action. A good commit is independently testable and reviewable; it may contain several RED/GREEN microsteps that together deliver one behavior.

Use smaller commits when they materially improve rollback or isolate risky authority changes. Avoid documentation/status-only commit churn unless the plan itself is a durable project artifact.

## Common Mistakes

### Turning safety into ceremony

Do not confuse a detailed implementation checklist with the canonical delivery roadmap. Warning signs:

- each helper or storage edge becomes its own milestone;
- specification and security reviews repeat after every tiny slice;
- Viewer/status documentation is updated more often than working behavior advances;
- fake or pure code receives production-cutover ceremony;
- the user cannot tell the short critical path from the supporting detail.

Correction: preserve the hard invariant, combine adjacent implementation slices into one working outcome, run one consolidated review at the boundary, and move immediately to the next externally meaningful proof. Put session-specific examples and rationale in `references/outcome-sized-delivery.md`.

### Rushing to implementation before strategic alignment

When the user asks to "go through this from the start," "revisit the planning," or says a previous plan brushed over the important parts, do not jump straight into scaffolding or tactical tasks. First re-read the conversation context, restate the core product/architecture decision, identify explicit tradeoffs and decision gates, then save a strategy plan before implementation. For product/infrastructure planning, the right deliverable may be a strategy roadmap with phases, risks, economics, and gates rather than only bite-sized coding tasks.

### Replacing AI product behavior with brittle deterministic shortcuts

For AI-native products, especially Alex-facing agent/chat products, do not write plans where core understanding is regex/string parsing or canned "fast answer" templates masquerading as intelligence. Deterministic code is appropriate for infrastructure boundaries — auth, loading cached artifacts, schema validation, redaction, cache existence checks, queues, and tests — but semantic routing and answer composition should remain model/agent-driven unless the user explicitly asks for a rules engine. If speed is the goal, plan an AI-guided cached-context path: load compact cached facts, pass them to an AI/semantic router or normal agent answer path, and fall back safely to deeper tool runs. Call out non-goals such as "no keyword intent router," "no canned reading as primary answer," and "no fake claims from partial cache."

### 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, choose the fastest safe execution cadence:

- Dispatch by **outcome milestone**, not automatically one subagent per mechanical task.
- Keep RED/GREEN microsteps inside the implementer brief.
- Run independent review once the milestone works end to end; use per-substep review only when a substep independently changes a high-risk authority boundary.
- If the user already asked to proceed, execute without asking for another ceremonial go-ahead.

## Remember

```
Outcome-sized canonical milestones
Mechanical detail inside implementer checklists
Exact paths/commands where they prevent guessing
TDD inside the batch
One consolidated review at a meaningful boundary
Only hard gates before real effects or customer data
Coherent commits and sparse, truthful status updates
```

**A good plan makes the shortest safe path obvious.**