eddowding/write-planning-doc

Planning Document Guide

Guide for writing planning/project management .md files for any type of project or initiative.

[GOAL]

Create structured planning documents that break complex projects into stages with clear actions and validation points.

[CONTEXT]

Planning docs are for thinking through & documenting decisions, breaking down complex projects into multiple stages, and tracking progress.

Store planning docs in Cockpit/memory/topics/planning/ or the relevant project folder.

[PROCESS]

Starting a Planning Doc

• Run date +"%y%m%d" to get the current date for naming
• Ask the user questions about requirements to clarify key decisions
• Use [[sounding-board-mode]] for discovery conversations

File Naming

Format: yyMMdd[letter]_description_in_lowercase.md

• Date prefix: yyMMdd (e.g., 260110 for 10 Jan 2026)
• Letter: auto-increment (a, b, c...) for same-day docs
• Example: 260110a_athena_blue_launch_plan.md

Document Structure

# [Project Name] Planning Doc

## Goal, Context
- Clear problem/goal statement(s) at top
- Enough context to pick up where we left off

## References
- Relevant background docs, files, links
- 1-sentence summary for each
- Most important at top

## Principles, Key Decisions
- Specific approaches agreed with user
- Update as new information arrives

## Stages & Actions

### Stage: [Description]
- [ ] Top-level action
  - [ ] Sub-action
    - Notes with extra context

### ✅ Completed Stage
- ✅ Completed action
  - 📔 Notes on discoveries

## Appendix
- Research findings
- Alternative approaches considered
- Supporting materials

Stage Design Principles

• Start with simple working v1, layer complexity gradually
• End each stage with validated outputs
• Don't number stages (easier to reorder)
• Use [ ] and [x] checkboxes for todo/done
• Surface potential risks early
• Frontload business value

Validation Points

At end of stages, add appropriate checks:

• Stakeholder review / sign-off
• Quality review
• Data validation
• User testing
• Stop & review with user

Final Actions

• Final validation (stakeholder sign-off, QA)
• Cleanup and documentation
• Move to archive when complete

[IMPORTANT]

• Keep concise but capture all decisions
• Update regularly as work progresses
• Stop immediately if surprises/issues - discuss first
• Use subagents for encapsulated research tasks
• Add web search for research, best practices, examples