Plan Template Skill

This skill provides everything needed to write implementation plans: templates, format specifications, and examples.

Quick Reference

| Command | Description | |---------|-------------| | /plan-template | Show available templates and help | | /plan-template feature | Template for new features (any complexity) | | /plan-template bugfix | Template for bug fixes (TDD approach) | | /plan-template refactor | Template for architectural changes | | /plan-template format | Show complete plan document format |

Available Templates

| Template | Use For | Pattern | |----------|---------|---------| | feature | New features of any complexity (from utility functions to multi-module systems) | Setup → Component 1 (write→test→validate) → Component 2 → ... → Integration → Final QA | | bugfix | Bug fixes following TDD pattern | Identify → Reproduce with test → Fix → Edge cases → Validate | | refactor | Architectural changes, code restructuring, multi-module work | Module 1 → Module 2 → Module 3 → Integration → Final QA |

Template Selection Guide

Choose feature when:

Adding new functionality (greenfield development)
Implementing anything from simple utility functions to complex multi-module features
Building new APIs, services, or components
Requirements involve creating new code rather than fixing or restructuring existing code

Choose bugfix when:

Fixing a bug of any size
Issue requires root cause analysis
Dealing with regressions or unexpected behavior
Need to follow TDD (test-first) approach

Choose refactor when:

Making architectural changes to existing code
Restructuring code across multiple files
Reorganizing modules without changing behavior
Implementing breaking changes with migration needs
Maintaining backward compatibility is important

Plan Document Format

Every plan MUST follow this structure. This is the canonical format for all implementation plans.

Required Frontmatter

---
scope: <scope-name>                # lowercase with hyphens
created: <YYYY-MM-DDTHHmmssZ>      # creation timestamp (UTC)
updated: <YYYY-MM-DDTHHmmssZ>      # last update timestamp (UTC)
version: <int>                     # increment on updates
---

Required Sections

# Implementation Plan: [Feature Name]

## Overview
[2-3 sentence summary of what this feature does and why it's needed]

## Phases

- [ ] [Phase 1: Phase Name](#phase-1-phase-name)
- [ ] [Phase 2: Phase Name](#phase-2-phase-name)
- [ ] [Phase N: End-to-End Validation](#phase-n-end-to-end-validation)

## Requirements

### Functional Requirements
- [FR1: Specific functional requirement]
- [FR2: Specific functional requirement]

### Non-Functional Requirements
- [NFR1: Performance, scalability, security requirements]
- [NFR2: Code quality, testing, documentation requirements]

### Assumptions & Constraints
- [Assumption 1]
- [Constraint 1]

## Architecture Analysis

### Current State
- [Description of relevant existing architecture]
- [Key files/modules that will be affected]

### Proposed Changes
- [Change 1: file path and high-level description]
- [Change 2: file path and high-level description]

### Design Decisions
1. **[Decision 1]**: [Rationale]
2. **[Decision 2]**: [Rationale]

## File Inventory

### Files to Create
- `path/to/new_file.py` - [Purpose]
- `path/to/test_new_file.py` - [Test coverage]

### Files to Modify
- `path/to/existing_file.py` - [What changes]

### Files to Delete (if any)
- `path/to/deprecated_file.py` - [Reason for removal]

## Implementation Steps
[See Phase Structure below]

## Testing Requirements
[See Testing Format below]

## Code Quality Requirements
[See Quality Checklist below]

## Dependencies

### External Dependencies
- [New package: version and purpose]

### Internal Dependencies
- [Other features or modules this depends on]

### Blocking Items
- [Items that must be completed first]

## Acceptance Criteria
[See Acceptance Criteria Format below]

## Future Enhancements
[Optional features to consider for future iterations]

Phase Structure

One Phase = One Complete Feature/Function/Component

Each phase produces working, tested, validated code before moving to the next.

Phase Organization Principles

Organize by feature, not by activity: Each feature is its own phase containing implementation, testing, and validation steps
Enable incremental progress: Complete Phase 1 fully before starting Phase 2
Prioritize by dependencies: If Function B depends on Function A, make Function A Phase 1
Include integration checks: Each phase verifies compatibility with existing code
Always end with E2E validation: Final phase verifies all work meets acceptance criteria

Phase Template

### Phase N: [Phase Name - e.g., Implement process_dataframe Function]
**Goal**: [What this phase accomplishes - be specific about the single feature/function]

**Dependencies**: None / Requires Phase X completion

#### Implementation Steps

##### Step N.1: [Specific Implementation Step]
- **File**: `path/to/file.py`
- **Action**: [Detailed, specific action - what code to write]
- **Details**:
  - Create class/function `ClassName` with methods `method1()`, `method2()`
  - Key signatures: `def method1(param: Type) -> ReturnType:`
  - Important implementation notes
- **Why**: [Business/technical reason]
- **Dependencies**: None / Requires Step X.Y
- **Validation**:
  - **Command**: `uv run pytest tests/test_<module>.py::test_<function> -v`
  - **Expected**: Test passes, verifying functionality works correctly
  - **Manual Check**: Function has type hints and docstring

#### Test Steps

##### Step N.T1: Write Unit Tests
- **File**: `tests/test_<module>.py`
- **Action**: Create comprehensive unit tests
- **Details**:
  - Test success cases
  - Test edge cases
  - Test error handling
- **Validation**:
  - **Command**: `uv run pytest tests/test_<module>.py -v`
  - **Expected**: All tests pass with >90% coverage

#### Validation Steps

##### Step N.V1: Validate Implementation
- **Action**: Run all quality checks
- **Validation**:
  - **Command**: `uv run pytest tests/test_<module>.py && uv run ty check . && uv run ruff check`
  - **Expected**: All checks pass
  - **Manual Check**: Code follows project conventions

Final Phase: End-to-End Validation

Every plan MUST end with an E2E validation phase:

### Phase N: End-to-End Validation
**Goal**: Verify all phases work together and meet acceptance criteria

#### Step N.1: Run Full Test Suite
- **Validation**:
  - **Command**: `uv run pytest -v`
  - **Expected**: All tests pass
  - **Manual Check**: Code coverage >= 90%

#### Step N.2: Verify Acceptance Criteria
- **Action**: Check all acceptance criteria from plan overview
- **Validation**:
  - **Command**: `uv run ruff check && uv run ty check . && uv tool run pydoclint`
  - **Expected**: All quality checks pass
  - **Manual Check**: All acceptance criteria checkboxes complete

Step Granularity Rules

One step = One atomic, testable change

Each step must be:

Atomic: Can be completed independently without partial states
Time-bounded: Should take 5-15 minutes to implement
Verifiable: Has clear validation criteria
Focused: Does one thing well

When to break down steps:

If a step seems >15 minutes, split it into substeps
If a step has multiple unrelated actions, separate them
If a step crosses multiple files/modules, consider breaking it up
If validation requires multiple checks, each check might be its own step

Validation Criteria Format

CRITICAL: Every step MUST have specific, actionable validation criteria.

Generic validation like "make sure it works" or "verify correctness" is NOT acceptable.

Required Components

Every validation must include:

Command - Exact command to run for automated verification
- Must be copy-pasteable
- Should be deterministic (same input = same output)
- PREFER tests that exercise the code over simple import checks
Expected - Precise expected outcome
- Specific output, return code, or behavior
- Measurable and verifiable
- Examples: "Test passes", "All 3 tests pass", "Returns exit code 0"
Manual Check (when automated verification isn't sufficient)
- Code quality checks (docstrings, type hints present)
- Visual/structural verification

Validation Philosophy

DO: Write tests that exercise the code

Run pytest tests that call the function with real inputs
Verify the function produces expected outputs
Test edge cases and error handling

DON'T: Use simple import checks as primary validation

Importing only verifies the function exists, not that it works
Import checks are acceptable as "smoke tests" but should be supplemented with real tests

Testing Requirements Format

Use Given/When/Then format for test scenarios:

## Testing Requirements

### Unit Tests

#### Test File: `tests/test_<module>.py`
- **Test 1**: `test_<function_name>_success_case`
  - Given: [Initial state]
  - When: [Action]
  - Then: [Expected outcome]

- **Test 2**: `test_<function_name>_edge_case`
  - Given: [Edge case setup]
  - When: [Action]
  - Then: [Expected handling]

- **Test 3**: `test_<function_name>_error_handling`
  - Given: [Error condition]
  - When: [Action]
  - Then: [Expected error/exception]

### Integration Tests
- **Scenario 1**: [End-to-end flow description]
- **Scenario 2**: [Integration between components]

Code Quality Checklist

Include this checklist in every plan:

## Code Quality Requirements

- [ ] All functions have type hints
- [ ] All public APIs have Google-style docstrings
- [ ] Code follows project conventions
- [ ] No code duplication (DRY principle)
- [ ] Error handling with clear messages
- [ ] Passes `uv run ruff check`
- [ ] Passes `uv run ty check .`
- [ ] Passes docstring linting

Acceptance Criteria Format

## Acceptance Criteria

### Functional Acceptance
- [ ] [Specific, testable criterion 1]
- [ ] [Specific, testable criterion 2]
- [ ] [Specific, testable criterion 3]

### Quality Acceptance
- [ ] All unit tests pass (`uv run pytest`)
- [ ] All public functions have a test
- [ ] Code coverage >= 90%
- [ ] Type checking passes (`uv run ty check .`)
- [ ] Linting passes (`uv run ruff check`)
- [ ] Docstring validation passes
- [ ] No security vulnerabilities

### Documentation Acceptance
- [ ] Code is documented with Google-style docstrings
- [ ] README updated (if applicable)
- [ ] Examples provided in docstrings

Bug Fix Pattern (TDD)

Bug fixes follow Test-Driven Development:

Pattern: Identify → Reproduce → Fix → Validate

Identify: Locate buggy code and understand root cause
Reproduce: Write test FIRST that reproduces the bug (verify test FAILS)
Fix: Make minimal change to fix bug (verify test now PASSES)
Edge Cases: Add tests for related scenarios (prevent similar bugs)
Validate: Run full test suite (ensure no regressions)

Key Principles

Test-Driven: Write reproduction test before fixing code
Verify Failure: Confirm test fails with current code (proves bug exists)
Minimal Fix: Smallest change necessary to fix the bug
No Regressions: All existing tests must continue to pass
Document Root Cause: Explain why bug occurred and how fix prevents it

Refactoring Guidelines

When planning refactors:

Identify code smells and technical debt
List specific improvements needed
Preserve existing functionality (all existing tests must pass)
Create backwards-compatible changes when possible
Plan for gradual migration if needed

Action Instructions

Based on the argument provided, perform one of these actions:

`/plan-template` (no args) or `/plan-template help`

Show this overview with available templates and commands.

`/plan-template feature`

Read and display: .claude/skills/plan-template/example-feature.md

`/plan-template bugfix`

Read and display: .claude/skills/plan-template/example-bugfix.md

`/plan-template refactor`

Read and display: .claude/skills/plan-template/example-refactor.md

`/plan-template format`

Display the "Plan Document Format" section from this skill.

Template File Locations

All example templates are in this skill directory:

example-feature.md - Complete example for new features (any complexity)
example-bugfix.md - Complete example for bug fixes
example-refactor.md - Complete example for refactoring