Write Plan Document

Create structured implementation plans following project conventions.

Document Structure

Use the template from templates/plan-document.md:

Overview - Brief description
Current State Analysis - What exists now
Desired End State - Specification and verification
What We're NOT Doing - Explicit out-of-scope items
Implementation Approach - High-level strategy
Project References - Links to commands.md and testing.md
Phases - Detailed implementation steps
Changelog - Implementation tracking (created during implementation)
- Not created by plan command
- Implementation command creates and maintains it
- Used for auto-correction loop
Testing Strategy - Unit, integration, manual
References - Links to tickets, research

File Path and Naming

Determine feature slug first using determine-feature-slug skill:

If implementing from existing research: Use same slug (same directory)
If new feature: Auto-detect namespace and next number, suggest description from plan title
Prompts user to accept or customize

Save to: thoughts/{namespace}/NNNN-description/plan.md

Example workflow:

Planning from research doc thoughts/erik/0005-authentication/research.md
Skill suggests: erik/0005-authentication (same directory)
Document saved to: thoughts/erik/0005-authentication/plan.md

Collaboration: Plans start in personal namespace. Use share-docs skill to promote to thoughts/shared/ when ready for team implementation.

Backward compatibility: Old path thoughts/shared/plans/YYYY-MM-DD-NN-description.md still recognized.

Phase Structure

Each phase must include:

Overview - What this phase accomplishes

Changes Required - Specific files and code changes

Success Criteria - Split into two sections:

Automated Verification: Commands that can be run
Manual Verification: Human testing needed

Milestone Structure

Group related phases into testable milestones:

When to create milestones:

Group 2-4 related phases together
Each milestone has user-facing outcome
User can test milestone completion
Natural stopping points for validation

Milestone format:

## Milestone N: {Name}
**Goal**: {What user gets}
**Testable**: {How to verify it works}

### Phase N.1: {Technical step}
### Phase N.2: {Technical step}

Example:

## Milestone 1: Database Ready
**Goal**: Database can store authentication data
**Testable**: Can manually insert and query user records

### Phase 1.1: Create User Table
[Technical implementation details]

### Phase 1.2: Add Authentication Fields
[Technical implementation details]

## Milestone 2: Authentication Working
**Goal**: Users can log in and receive tokens
**Testable**: Can log in via API and get valid JWT

### Phase 2.1: Implement Login Handler
[Technical implementation details]

Benefits:

Clear stopping points for user validation
Incremental delivery of value
User-facing goals, not just technical tasks
Easier to understand project progress

Success Criteria Guidelines

Automated (use make when possible):

- [ ] Tests pass: `make test`
- [ ] Linting passes: `make lint`
- [ ] Build succeeds: `make build`

Manual:

- [ ] Feature appears correctly in UI
- [ ] Performance acceptable with 1000+ items
- [ ] Error messages are user-friendly

Project References

Always reference these documents if they exist:

thoughts/notes/commands.md - Available commands
thoughts/notes/testing.md - Test patterns

These are created by discover-project-commands and discover-test-patterns skills.

Changelog Reference

During implementation, a changelog will be created:

thoughts/NNNN-description/changelog.md - Phase-by-phase tracking
Read before each phase for auto-correction
Updated after each phase with deviations

File References

Include specific file:line references throughout:

When mentioning existing code
When suggesting where to add code
When referencing similar patterns

No Open Questions

Plans must be complete and actionable. If you have open questions:

STOP writing the plan
Research or ask for clarification
Only proceed once all decisions are made

write-plan-doc