Writing Plans

Writing Plans

触发条件

通用领域触发矩阵

实现计划撰写覆盖7大领域，21个子场景。

手动触发

• "写一个plan"
• "implementation plan"
• "write a plan"
• "实施计划"

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

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

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

Critical Workflow: Plan → Confirm → Execute (Never Skip)

This user requires explicit plan confirmation before touching any code (non-negotiable):

1. Plan first — Full implementation plan (complete tasks, approach, open questions)
2. User reviews — They correct scope, priority, or approach (typically 2-3 rounds)
3. Revise if needed — Align before writing code
4. Only then execute — After user says "confirmed"

Do NOT skip to implementation because the plan looks obvious. The user's corrections at the plan stage prevent hours of wasted work.

What a Complete Plan Looks Like (for this user)

• 4-item framework if user gave specific scope (e.g., "only items 1,2,3,4")
• Real calendar dates not abstract days ("May 21 - June 30" not "D1-D40")
• Key milestone anchoring — explicitly call out fixed dates user mentioned
• Feature specs for every new capability (not just bug fixes)
• Verification method for every feature — "CDP screenshot", "API call returns X"

Open Questions Required

At the end of every plan, ALWAYS list:

## Open Questions (Pending Your Confirmation)
1. [Specific question about scope]
2. [Specific question about a missing field/behavior]

CRITICAL: When adding new modules to an existing system, every plan MUST include an explicit "Integration Wiring" phase AFTER implementation and BEFORE shipping.

WRONG plan order:  implement → test → ship
RIGHT plan order:  implement → unit test → wire into existing → integration test → ship

For each new module, the plan MUST answer:

1. Who calls this? — Which existing file/function will import and invoke it?
2. When does it fire? — On heartbeat? On event? On API call? On startup?
3. What if it fails? — Does the host system break? (Must be try/except guarded)
4. How do we prove it? — Integration test that verifies end-to-end data flow

Create tests/test_integration_<module>.py for every new module that proves it's actually wired into the system, not just importable.

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

Further reading (load when relevant)

• references/cross-project-adaptation.md — Workflow for analyzing an external project and adapting its patterns/modules into your own codebase. Load when the task involves "borrow from X", "adapt Y's architecture", "port Z to our stack".

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.