agent-skills/software-development/writing-plans/SKILL.md

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

## 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 using subagent-driven-development — I'll dispatch a fresh subagent per task with two-stage review (spec compliance then code quality). Shall I proceed?"**

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

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

## 中文计划模板

### 计划头部

```markdown
# [功能名称] 实现计划

> **Hermes 使用说明：** 使用 subagent-driven-development 技能逐个任务执行此计划。

**目标：** [一句话描述要构建什么]

**架构：** [2-3 句话描述技术方案]

**技术栈：** [关键技术/库]

**预计时间：** [总时间估算]

---
```

### 任务结构

```markdown
### 任务 N: [描述性名称]

**目标：** 此任务要完成什么（一句话）

**文件：**
- 创建：`exact/path/to/new_file.py`
- 修改：`exact/path/to/existing.py:45-67`（如果知道行号）
- 测试：`tests/path/to/test_file.py`

**步骤 1: 编写失败测试**

```python
def test_specific_behavior():
    result = function(input)
    assert result == expected
```

**步骤 2: 运行测试验证失败**

运行：`pytest tests/path/test.py::test_specific_behavior -v`
预期：FAIL — "function not defined"

**步骤 3: 编写最小实现**

```python
def function(input):
    return expected
```

**步骤 4: 运行测试验证通过**

运行：`pytest tests/path/test.py::test_specific_behavior -v`
预期：PASS

**步骤 5: 提交**

```bash
git add tests/path/test.py src/path/file.py
git commit -m "feat: 添加特定功能"
```
```

### 任务粒度示例

**太粗：**
```markdown
### 任务 1: 构建认证系统
[50 行代码，跨越 5 个文件]
```

**合适：**
```markdown
### 任务 1: 创建用户模型，包含邮箱字段
[10 行，1 个文件]

### 任务 2: 为用户添加密码哈希字段
[8 行，1 个文件]

### 任务 3: 创建密码哈希工具函数
[15 行，1 个文件]
```

### 中文计划示例

```markdown
# 用户认证功能实现计划

> **Hermes 使用说明：** 使用 subagent-driven-development 技能逐个任务执行此计划。

**目标：** 实现用户注册、登录、JWT 令牌生成的完整认证系统

**架构：** 使用 Flask + SQLAlchemy + bcrypt，遵循 RESTful 设计

**技术栈：** Python 3.11, Flask 2.3.2, SQLAlchemy 2.0, bcrypt 4.0, PyJWT 2.8

**预计时间：** 4 小时

---

### 任务 1: 创建用户模型

**目标：** 创建 User 模型，包含邮箱和密码哈希字段

**文件：**
- 创建：`src/models/user.py`
- 测试：`tests/models/test_user.py`

**步骤 1: 编写失败测试**

```python
def test_user_creation():
    user = User(email="test@example.com", password_hash="hashed")
    assert user.email == "test@example.com"
    assert user.password_hash == "hashed"
```

**步骤 2: 运行测试验证失败**

运行：`pytest tests/models/test_user.py -v`
预期：FAIL — "cannot import name 'User'"

**步骤 3: 编写最小实现**

```python
class User:
    def __init__(self, email, password_hash):
        self.email = email
        self.password_hash = password_hash
```

**步骤 4: 运行测试验证通过**

运行：`pytest tests/models/test_user.py -v`
预期：PASS

**步骤 5: 提交**

```bash
git add src/models/user.py tests/models/test_user.py
git commit -m "feat: 创建用户模型"
```

---

### 任务 2: 添加密码哈希功能

**目标：** 实现密码哈希和验证功能

**文件：**
- 创建：`src/utils/password.py`
- 测试：`tests/utils/test_password.py`

**步骤 1: 编写失败测试**

```python
def test_hash_password():
    hashed = hash_password("password123")
    assert hashed != "password123"
    assert verify_password("password123", hashed) is True
    assert verify_password("wrong", hashed) is False
```

**步骤 2: 运行测试验证失败**

运行：`pytest tests/utils/test_password.py -v`
预期：FAIL — "cannot import name 'hash_password'"

**步骤 3: 编写最小实现**

```python
import bcrypt

def hash_password(password):
    return bcrypt.hashpw(password.encode(), bcrypt.gensalt()).decode()

def verify_password(password, hashed):
    return bcrypt.checkpw(password.encode(), hashed.encode())
```

**步骤 4: 运行测试验证通过**

运行：`pytest tests/utils/test_password.py -v`
预期：PASS

**步骤 5: 提交**

```bash
git add src/utils/password.py tests/utils/test_password.py
git commit -m "feat: 添加密码哈希功能"
```

---

### 任务 3: 创建注册端点

**目标：** 实现用户注册 API

**文件：**
- 创建：`src/routes/auth.py`
- 测试：`tests/routes/test_auth.py`

**步骤 1: 编写失败测试**

```python
def test_register(client):
    response = client.post('/api/register', json={
        'email': 'test@example.com',
        'password': 'password123'
    })
    assert response.status_code == 201
    assert 'user' in response.json
```

**步骤 2: 运行测试验证失败**

运行：`pytest tests/routes/test_auth.py::test_register -v`
预期：FAIL — "404 Not Found"

**步骤 3: 编写最小实现**

```python
from flask import Blueprint, request, jsonify

auth_bp = Blueprint('auth', __name__)

@auth_bp.route('/api/register', methods=['POST'])
def register():
    data = request.json
    # TODO: 实现注册逻辑
    return jsonify({'user': {'email': data['email']}}), 201
```

**步骤 4: 运行测试验证通过**

运行：`pytest tests/routes/test_auth.py::test_register -v`
预期：PASS

**步骤 5: 提交**

```bash
git add src/routes/auth.py tests/routes/test_auth.py
git commit -m "feat: 创建注册端点"
```

---
```

### 计划审查清单

- [ ] 任务是否按逻辑顺序排列？
- [ ] 每个任务是否足够小（2-5 分钟）？
- [ ] 文件路径是否精确？
- [ ] 代码示例是否完整（可直接复制）？
- [ ] 命令是否精确，包含预期输出？
- [ ] 是否包含验证步骤？
- [ ] 是否应用了 DRY、YAGNI、TDD 原则？
- [ ] 是否包含中文注释和文档？