---
name: writing-plans
description: "Write implementation plans: bite-sized tasks, paths, code."
version: 1.1.0
author: Hermes Agent (adapted from obra/superpowers)
license: MIT
platforms: [linux, macos, windows]
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)

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

## Enhanced Approach with Research Integration

When creating implementation plans, consider the following research insights and design principles:

### User-Centric Design
- Always consider the user's needs and pain points
- Focus on creating an intuitive, elegant experience
- Apply the principle that "simplicity is the ultimate sophistication"

### Steve Jobs Design Philosophy
- Remove everything that doesn't contribute to the essential experience
- Make every interaction feel effortless and magical
- Pay attention to every detail, from visual design to user flow
- Focus on the core experience without feature bloat

### Market Differentiation
- Identify unique value propositions that set your product apart
- Consider how to solve problems that existing solutions don't address
- Think about how to create a product that users will love and recommend

### Implementation Best Practices
- Apply the "trailer-first" approach when relevant (focus on the primary content experience)
- Implement intelligent curation features when appropriate
- Ensure social integration feels natural and seamless
- Prioritize high-quality playback and performance

### App Project Planning Addendum

When planning a **new app or product** (not a feature within an existing codebase):

1. **Research competitors first** — Load `market-research` skill, run competitive analysis. Document what exists, what's missing, and the market gap.
2. **Define architecture before tasks** — Write a high-level architecture doc (tech stack, core modules, data flow) before breaking into bite-sized tasks.
3. **Phase the roadmap** — MVP (core functionality) → Core Features (differentiators) → Advanced (nice-to-haves) → Polish (platform expansion).
4. **Specify UI early** — Include color palette, typography, and wireframe layouts in the plan. Don't leave UI decisions to the implementer.
5. **Include non-functional requirements** — Performance targets, security, scalability, monitoring.
6. **Plan for infrastructure** — Database schema, API endpoints, external service integrations, deployment.
7. Reference `references/streaming-app-competitive-analysis.md` in `market-research` for streaming/media app patterns.
8. For competitive audits where the user provides a list of reference repos to study, use `references/reference-repo-competitive-audit.md` — a 4-phase methodology (clone → inspect → rate → adapt) that produces the standard 5-document audit deliverable set.

## 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"
```

## Enhanced Principles with Research Integration

### Research-Informed Development
When creating implementation plans, consider the following research insights:

**User-Centric Design**: Always consider user needs and pain points identified through market research
**Steve Jobs Philosophy**: Apply principles of simplicity, elegance, and user-focused design
**Market Differentiation**: Identify unique value propositions that set your product apart

### Implementation Best Practices
- Apply the "trailer-first" approach when relevant
- Implement intelligent curation features based on user behavior research
- Ensure social integration feels natural and seamless
- Prioritize high-quality playback and performance based on user expectations

### Specify Exact API Signatures in Task Descriptions

When a task uses third-party APIs (especially Jetpack Compose, tv-material3, or other rapidly-evolving AndroidX libraries), include the **exact constructor syntax** in the task description. Subagents will guess differently.

**Don't write:**
```
Use Border from tv-material3 for the focus border.
```

**Write:**
```kotlin
// CORRECT: 
//   import androidx.tv.material3.Border
//   import androidx.compose.foundation.BorderStroke
//   Border(BorderStroke(2.dp, color))
//
//   import androidx.tv.material3.ClickableSurfaceDefaults
//   ClickableSurfaceDefaults.border(
//       focusedBorder = Border(BorderStroke(2.dp, color)),
//   )
//
// DO NOT use:
//   ImmutableBorder(width=, color=, shape=)  -- does not exist in 1.0.0-rc01
//   .border(focused = ...)  -- parameter is focusedBorder, not focused
```

This is especially important when dispatching parallel subagents from `subagent-driven-development`. Each subagent gets a fresh context and will independently decide what API shape to use — unless you pin it in the plan.

## Common Mistakes

### Missing Exact API Signatures (for subagent execution)

**Bad:** Plan says "Implement Retrofit interface" without exact import paths or constructor signatures. Subagents guess at third-party API surfaces and get them wrong systematically.

**Good:** For every third-party library, include a `// KNOWN API` block showing the exact class names, constructor signatures, and import paths the subagent must use:

```markdown
// KNOWN API — tv-material 1.0.0-rc01 (key for subagents)
// Border accepts: Border(BorderStroke(width, color)) — NOT Border(width, color, shape)
// ClickableSurfaceDefaults.border(focused = Border(...))
// ImmutableBorder does NOT exist in this version

// KNOWN API — Coil 3.0.4
// ImageLoader.Builder(context) — builder takes Context, not unit
// OkHttpFetcherFactory(okHttpClient) — NOT OkHttpNetworkFetcherFactory
```

Without these, every subagent will guess differently, and you'll spend 3-4 regex fix passes reconciling API mismatches across 20+ files.

### 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`"

### Research Integration Mistakes

**Bad:** Ignore user research and market analysis
**Good:** Incorporate research insights into design decisions and feature implementation

### Design Philosophy Mistakes

**Bad:** Don't apply Steve Jobs principles of simplicity and elegance
**Good:** Follow design principles that create intuitive, magical user experiences

## Session Reset / Continuity Handoff

When the user says they are about to reset, start a new session, avoid losing context to compression, or asks to "document everything" / "keep everything intact", treat it as a project-continuity deliverable, not just a summary.

For software projects, actively create or update the durable handoff set (see `references/project-continuity-handoff.md` for a compact checklist):

1. `SESSION_HANDOFF.md` at the project root — current phase, verified state, architecture rules, exact commands, git commit, what changed, and where to continue.
2. `docs/PROJECT_CONTEXT.md` — stable product purpose, architecture standards, data model, security rules, verification commands, and what to avoid.
3. `docs/NEXT_SESSION_START.md` — the exact first commands/files to read after reset, expected outputs, and clean-state checks.
4. `docs/plans/<NEXT_PHASE>_PLAN.md` — a bite-sized continuation plan following this skill's plan structure.
5. `README.md` — make sure it points to the handoff docs and is not stale.

Then verify and checkpoint:

```bash
ruff check app tests alembic  # adapt paths/tools to the project
mypy app                      # if configured
pytest -q                     # if configured
git diff --check              # catches trailing whitespace in handoff docs too
git status --short
git add -A && git commit -m "docs: add reset handoff and next-phase plan"
```

Before committing, actively hunt for stale continuity details across **all** handoff surfaces, not just the one file you edited: old phase names, old commit SHAs, old test counts, old source-file counts, old "next task" pointers, and README links to obsolete plans. A reset handoff is only useful if `README.md`, `SESSION_HANDOFF.md`, `docs/PROJECT_CONTEXT.md`, `docs/NEXT_SESSION_START.md`, and the next-phase plan agree with each other.

If the project is not already a git repo and the user wants nothing lost, initialize git before committing unless there is a clear reason not to. Use `main` as the branch name and keep generated/cache/secret files excluded via `.gitignore`.

Pitfalls:
- Do not rely on chat history or memory alone for project continuity. Memory should hold only a compact pointer; the project docs must hold the detailed handoff.
- Do not save session progress only to persistent memory. Put detailed state, decisions, known issues, and pending tasks in project docs; memory gets a short path + current-docs pointer.
- Do not make the next-phase plan vague. Include an explicit first objective, exact files to read, verification commands, and tasks ordered by production risk.

Reference: `references/reset-handoff-pattern.md` contains a concise example pattern from a streaming-app Phase 4 → Phase 5 reset handoff.

## Execution Handoff

After saving the plan, offer the execution approach:

**"Plan complete and saved. Ready to execute using subagent-driven-development — I'll dispatch a fresh subagent per task with two-stage review (spec compliance then code quality). Shall I proceed?"**

**Exception — "Complete all phases":** When the user says "Complete all phases" or "execute all phases" or "don't stop between phases," do NOT ask for confirmation between phases. Execute the entire plan autonomously. Still build + test after each phase, but proceed immediately to the next phase without asking. This is an escalation of trust — do not pause for approval.

When executing, use the `subagent-driven-development` skill:
- Fresh `delegate_task` per task with full context
- Spec compliance review after each task
- Code quality review after spec passes
- Proceed only when both reviews approve

## Enhanced Execution Handoff

After saving the plan, offer the execution approach:

**"Plan complete and saved. Ready to execute using subagent-driven-development — I'll dispatch a fresh subagent per task with two-stage review (spec compliance then code quality). Shall I proceed?"**

**Exception — "Complete all phases":** When the user says "Complete all phases," execute the entire plan autonomously without per-phase confirmation. Build + test after each phase, then proceed to the next immediately.

When executing, use the `subagent-driven-development` skill:
- Fresh `delegate_task` per task with full context
- Spec compliance review after each task
- Code quality review after spec passes
- Proceed only when both reviews approve

## Research-Informed Execution

When executing the plan, ensure that:
1. Research insights are applied to each task
2. Design principles are followed throughout implementation
3. User needs are prioritized in every decision
4. Differentiation strategies are implemented

## 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
Research integration
Design philosophy application
```

**A good plan makes implementation obvious.**

## Enhanced Remember Section

When creating implementation plans, remember to:

1. **Apply Research Insights**: Always incorporate user research and market analysis
2. **Follow Design Principles**: Implement Steve Jobs' philosophy of simplicity and elegance
3. **Focus on User Experience**: Make every interaction feel effortless and magical
4. **Differentiate from Competitors**: Identify unique value propositions
5. **Plan for Future Growth**: Design with scalability in mind