Writing Plans

Writing Plans

Overview

Write comprehensive implementation plans assuming the engineer has zero context for our codebase and questionable taste. Document everything they need to know: which files to touch for each task, code, testing, docs they might need to check, how to test it. Give them the whole plan as bite-sized tasks. DRY. YAGNI. TDD. Frequent commits.

Assume they are a skilled developer, but know almost nothing about our toolset or problem domain. Assume they don't know good test design very well.

Announce at start: "I'm using the Writing Plans skill to create the implementation plan."

Context: This should be run in a dedicated worktree (created by brainstorming skill).

Save plans to: docs/plans/YYYY-MM-DD-<feature-name>.md

Quick Reference

Plan header template: See Plan Structure & Templates

Task template: See Plan Structure & Templates

Granularity guide: Each step = 2-5 minutes. See Best Practices

Core Principles

• Exact file paths always - Not "in the user module" but "src/models/user.py"
• Complete code in plan - Not "add validation" but show the validation code
• Exact commands with expected output - "pytest tests/file.py -v" with what you'll see
• Reference relevant skills - Use @ syntax: @skills/category/skill-name
• DRY, YAGNI, TDD, frequent commits - Every task follows this pattern

For detailed guidance: Best Practices & Guidelines

Execution Handoff

After saving the plan, offer execution choice:

"Plan complete and saved to `docs/plans/<filename>.md`. Two execution options:

1. Subagent-Driven (this session) - I dispatch fresh subagent per task, review between tasks, fast iteration

2. Parallel Session (separate) - Open new session with executing-plans, batch execution with checkpoints

Which approach?"

If Subagent-Driven chosen:

• Use @skills/collaboration/subagent-driven-development
• Stay in this session
• Fresh subagent per task + code review

If Parallel Session chosen:

• Guide them to open new session in worktree
• New session uses @skills/collaboration/executing-plans

Remember

• Write for zero-context engineers (specify everything)
• Complete code blocks, not instructions
• Exact commands with expected output
• Test first, then implement, then commit
• Reference existing patterns in codebase
• Keep tasks bite-sized (2-5 minutes each)

Need examples? See Plan Structure & Templates for complete task examples.

Need patterns? See Best Practices for error handling, logging, test design, and more.

Plan Writing Best Practices

Core Principles

DRY (Don't Repeat Yourself)

• Extract common patterns into utilities
• Reuse existing functions and classes
• Create shared helpers for repeated logic
• Never copy-paste code in the plan

YAGNI (You Aren't Gonna Need It)

• Build only what's required by the design
• No speculative features
• No "future-proofing" unless explicitly required
• Start simple, extend when needed

TDD (Test-Driven Development)

• Write test first, always
• Watch it fail before implementing
• Implement minimal code to pass
• Refactor after green

Frequent Commits

• Commit after each passing test
• One feature per commit
• Clear, descriptive commit messages
• Never commit broken code

Writing for Zero-Context Engineers

Assume They Know

• Core programming concepts
• The programming language syntax
• Basic development tools (git, pytest, npm)
• General software patterns

Assume They DON'T Know

• Your specific codebase structure
• Domain-specific terminology
• Project conventions and patterns
• Where files should go
• Which existing utilities to use
• Your testing strategy

Therefore, Always Specify

• Exact file paths - not "in the user module" but "src/models/user.py"
• Complete code - not "add validation" but show the validation code
• Exact commands - not "run tests" but "pytest tests/models/test_user.py -v"
• Expected output - what should happen when they run the command
• Line numbers for modifications - "src/config.py:45-52"

Complete Code, Not Instructions

❌ Bad (vague instructions):

**Step 3: Add validation**

Add email validation to the User model.
Make sure to check for valid format.

✅ Good (complete code):

**Step 3: Add validation to User model**

In `src/models/user.py`, add this method after line 12:

def __post_init__(self): if not validate_email(self.email): raise ValueError(f"Invalid email: {self.email}") if self.created_at is None: self.created_at = datetime.utcnow()

Exact Commands with Expected Output

❌ Bad (vague):

**Step 2: Run the test**

Run the test and make sure it fails.

✅ Good (specific):

**Step 2: Run test to verify it fails**

Run: `pytest tests/models/test_user.py::test_user_creation -v`
Expected output:

FAILED tests/models/test_user.py::test_user_creation - ModuleNotFoundError: No module named 'models.user'

This is expected! We haven't created the module yet.

File Path Precision

For New Files

**Files:**
- Create: `src/api/handlers/users.py`
- Create: `tests/api/test_users.py`

For Modifications

**Files:**
- Modify: `src/api/routes.py:15` (add import)
- Modify: `src/api/routes.py:45` (add route registration)
- Modify: `src/config.py:12-18` (update database config)

For Referenced Files

**Documentation to check:**
- See: `docs/api-design.md` (endpoint specification)
- Reference: `src/api/handlers/auth.py:25-40` (similar pattern)

Test Design for Zero-Context Engineers

Many engineers struggle with test design. Help them by:

Show What to Test

**Test coverage needed:**
1. Happy path (valid input → expected output)
2. Invalid input (error handling)
3. Edge cases (empty, null, boundary values)
4. Integration (does it work with real dependencies?)

Provide Complete Test Examples

# Happy path
def test_create_user_success():
    user = create_user("alice", "alice@example.com")
    assert user.username == "alice"
    assert user.email == "alice@example.com"

# Invalid input
def test_create_user_invalid_email():
    with pytest.raises(ValueError, match="Invalid email"):
        create_user("alice", "not-an-email")

# Edge case
def test_create_user_empty_username():
    with pytest.raises(ValueError, match="Username cannot be empty"):
        create_user("", "alice@example.com")

Explain Test Strategy

**Why these tests:**
- `test_create_user_success`: Verifies basic functionality works
- `test_create_user_invalid_email`: Ensures we reject bad data
- `test_create_user_empty_username`: Prevents edge case bugs

Referencing Existing Code

Use @ Syntax for Skills

For authentication patterns, see @skills/security/implementing-auth
For API design, reference @skills/api/rest-endpoints

Reference Codebase Files

**Similar implementations:**
- `src/api/handlers/auth.py:25-40` - shows JWT validation pattern
- `src/utils/validators.py:10-15` - email validation we can reuse

Point to Documentation

**Required reading:**
- `docs/architecture/database-schema.md` - understand our user model
- `docs/api/authentication.md` - see auth requirements

Handling Dependencies and Setup

External Dependencies

**Dependencies needed:**

Add to `requirements.txt`:

bcrypt==4.0.1 PyJWT==2.8.0

Install:

pip install -r requirements.txt

Configuration Changes

**Configuration update:**

In `src/config.py`, add:

JWT_SECRET = os.environ.get("JWT_SECRET", "dev-secret-key") JWT_EXPIRATION_HOURS = 24

In `.env.example`:

JWT_SECRET=your-secret-key-here

Common Patterns to Include

Error Handling Pattern

try:
    result = risky_operation()
    return result
except SpecificError as e:
    logger.error(f"Operation failed: {e}")
    raise ValueError(f"Cannot complete operation: {e}")
except Exception as e:
    logger.exception("Unexpected error")
    raise

Resource Cleanup Pattern

def process_file(filepath):
    file_handle = None
    try:
        file_handle = open(filepath, 'r')
        data = file_handle.read()
        return process_data(data)
    finally:
        if file_handle:
            file_handle.close()

Logging Pattern

import logging

logger = logging.getLogger(__name__)

def important_operation():
    logger.info("Starting operation")
    try:
        result = do_work()
        logger.info(f"Operation completed: {result}")
        return result
    except Exception as e:
        logger.error(f"Operation failed: {e}", exc_info=True)
        raise

Documentation in Plans

When to Include Inline Docs

**Step 3: Implement user creation with docstring**

def create_user(username: str, email: str) -> User: """ Create a new user with validation.

Args: username: User's chosen username (must be unique) email: User's email address (must be valid format)

Returns: User: The created user object

Raises: ValueError: If username/email invalid or user exists """ if not username: raise ValueError("Username cannot be empty") if not validate_email(email): raise ValueError(f"Invalid email: {email}")

return User(username=username, email=email)

When to Update Separate Docs

**Step 10: Update API documentation**

In `docs/api/endpoints.md`, add:

POST /users

Create a new user account.

Request:

{
  "username": "alice",
  "email": "alice@example.com"
}

Response: 201 Created

{
  "id": 1,
  "username": "alice",
  "email": "alice@example.com",
  "created_at": "2025-01-15T10:30:00Z"
}

Commit Message Guidelines

Format

type: brief description

- Detail 1
- Detail 2

Types

• feat: - New feature
• fix: - Bug fix
• test: - Add/update tests
• refactor: - Code restructuring
• docs: - Documentation only
• chore: - Tooling, dependencies

Examples

git commit -m "feat: add user email validation"
git commit -m "test: add edge cases for user creation"
git commit -m "fix: handle empty username in user model"
git commit -m "refactor: extract validation to utils module"

Quality Checklist for Plans

Before saving the plan, verify:

• [ ] All file paths are exact and absolute
• [ ] All code blocks are complete (not pseudocode)
• [ ] All commands include expected output
• [ ] Tests are written before implementation
• [ ] Each step is 2-5 minutes of work
• [ ] Dependencies and setup are documented
• [ ] Error handling is included
• [ ] Commit messages are descriptive
• [ ] Referenced skills use @ syntax
• [ ] Header follows standard template

Plan Structure Templates

Standard Plan Document Header

Every plan MUST start with this header:

# [Feature Name] Implementation Plan

> **For Claude:** Use `${SUPERPOWERS_SKILLS_ROOT}/skills/collaboration/executing-plans/SKILL.md` 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 Template Structure

### Task N: [Component Name]

**Files:**
- Create: `exact/path/to/file.py`
- Modify: `exact/path/to/existing.py:123-145`
- Test: `tests/exact/path/to/test.py`

**Step 1: Write the failing test**

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

**Step 2: Run test to verify it fails**

Run: `pytest tests/path/test.py::test_name -v`
Expected: FAIL with "function not defined"

**Step 3: Write minimal implementation**

def function(input): return expected

**Step 4: Run test to verify it passes**

Run: `pytest tests/path/test.py::test_name -v`
Expected: PASS

**Step 5: Commit**

git add tests/path/test.py src/path/file.py git commit -m "feat: add specific feature"

Bite-Sized Task Examples

Example 1: Database Model

### Task 1: User Model and Schema

**Files:**
- Create: `src/models/user.py`
- Create: `tests/models/test_user.py`
- Create: `migrations/001_create_users_table.sql`

**Step 1: Write the failing test**

def test_user_model_creation(): user = User(username="alice", email="alice@example.com") assert user.username == "alice" assert user.email == "alice@example.com" assert user.created_at is not None

**Step 2: Run test to verify it fails**

Run: `pytest tests/models/test_user.py::test_user_model_creation -v`
Expected: FAIL with "ModuleNotFoundError: No module named 'models.user'"

**Step 3: Write minimal implementation**

In `src/models/user.py`:

from datetime import datetime from dataclasses import dataclass

@dataclass class User: username: str email: str created_at: datetime = None

def __post_init__(self): if self.created_at is None: self.created_at = datetime.utcnow()

**Step 4: Run test to verify it passes**

Run: `pytest tests/models/test_user.py::test_user_model_creation -v`
Expected: PASS

**Step 5: Commit**

git add src/models/user.py tests/models/test_user.py git commit -m "feat: add User model with basic fields"

Example 2: API Endpoint

### Task 3: GET /users/:id Endpoint

**Files:**
- Modify: `src/api/routes.py:15` (add route)
- Create: `src/api/handlers/users.py`
- Create: `tests/api/test_users_endpoint.py`

**Step 1: Write the failing test**

def test_get_user_by_id(client, db_with_users): response = client.get("/users/1") assert response.status_code == 200 assert response.json["username"] == "alice" assert response.json["email"] == "alice@example.com"

**Step 2: Run test to verify it fails**

Run: `pytest tests/api/test_users_endpoint.py::test_get_user_by_id -v`
Expected: FAIL with "404 Not Found"

**Step 3: Write minimal implementation**

In `src/api/handlers/users.py`:

from flask import jsonify from src.models.user import User from src.db import get_db

def get_user(user_id): db = get_db() user = db.query(User).filter(User.id == user_id).first() if not user: return jsonify({"error": "User not found"}), 404 return jsonify({ "id": user.id, "username": user.username, "email": user.email })

In `src/api/routes.py` at line 15:

from src.api.handlers.users import get_user

Add this route

app.route("/users/<int:user_id>", methods=["GET"])(get_user)

**Step 4: Run test to verify it passes**

Run: `pytest tests/api/test_users_endpoint.py::test_get_user_by_id -v`
Expected: PASS

**Step 5: Commit**

git add src/api/handlers/users.py src/api/routes.py tests/api/test_users_endpoint.py git commit -m "feat: add GET /users/:id endpoint"

Granularity Guidelines

Each step should take 2-5 minutes:

✅ Good granularity:

• "Write the failing test" - single test function
• "Run it to make sure it fails" - one command
• "Implement the minimal code to make the test pass" - focused function
• "Run the tests and make sure they pass" - verify
• "Commit" - checkpoint

❌ Too large (split these up):

• "Implement the user authentication system" - needs 10+ tasks
• "Add validation and error handling" - multiple tests/steps
• "Create all the models" - one task per model

❌ Too small (combine these):

• "Import the datetime module" - part of implementation step
• "Type the function signature" - part of implementation step
• "Add one line of code" - too granular

Multi-File Task Structure

When a task involves multiple related files:

### Task 4: Email Validation with Helper

**Files:**
- Create: `src/utils/validators.py`
- Create: `tests/utils/test_validators.py`
- Modify: `src/models/user.py:12` (use validator)
- Modify: `tests/models/test_user.py` (add validation tests)

**Step 1: Write failing test for validator**

In `tests/utils/test_validators.py`:

def test_validate_email_valid(): assert validate_email("alice@example.com") == True

def test_validate_email_invalid(): assert validate_email("not-an-email") == False

**Step 2: Run validator test to verify it fails**

Run: `pytest tests/utils/test_validators.py -v`
Expected: FAIL with "NameError: name 'validate_email' is not defined"

**Step 3: Implement email validator**

In `src/utils/validators.py`:

import re

def validate_email(email: str) -> bool: pattern = r'^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$' return bool(re.match(pattern, email))

**Step 4: Run validator test to verify it passes**

Run: `pytest tests/utils/test_validators.py -v`
Expected: PASS (both tests)

**Step 5: Write failing test for User model validation**

In `tests/models/test_user.py`:

def test_user_model_rejects_invalid_email(): with pytest.raises(ValueError, match="Invalid email"): User(username="alice", email="not-an-email")

**Step 6: Run User model test to verify it fails**

Run: `pytest tests/models/test_user.py::test_user_model_rejects_invalid_email -v`
Expected: FAIL (no validation yet)

**Step 7: Add validation to User model**

In `src/models/user.py` at line 12:

from src.utils.validators import validate_email

@dataclass class User: username: str email: str created_at: datetime = None

def __post_init__(self): if not validate_email(self.email): raise ValueError(f"Invalid email: {self.email}") if self.created_at is None: self.created_at = datetime.utcnow()

**Step 8: Run User model test to verify it passes**

Run: `pytest tests/models/test_user.py::test_user_model_rejects_invalid_email -v`
Expected: PASS

**Step 9: Run all tests to ensure nothing broke**

Run: `pytest tests/ -v`
Expected: All tests PASS

**Step 10: Commit**

git add src/utils/validators.py tests/utils/test_validators.py src/models/user.py tests/models/test_user.py git commit -m "feat: add email validation to User model"

Plan File Naming Convention

Save plans to: docs/plans/YYYY-MM-DD-<feature-name>.md

Examples:

• docs/plans/2025-01-15-user-authentication.md
• docs/plans/2025-01-16-api-rate-limiting.md
• docs/plans/2025-01-17-database-migration-users.md