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

markdown

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