Where we pretend to plan things before diving into code. Sometimes it even works.
- Issues first - Problems get discussed before solutions get coded
- Epics for big stuff - When something needs multiple PRs, make an epic
- Milestones for deadlines - When we actually have deadlines (rare)
- ADRs for decisions - When we make choices that'll confuse future us
Architecture Decision Records. For when we make non-obvious technical choices that future developers will wonder about.
High-level direction. What we're building and roughly when. Emphasis on "roughly".
Issue and PR templates specific to the PM repo. For tracking epics and milestones.
Use the epic template. An epic should:
- Solve a real problem
- Be too big for one PR
- Have clear success criteria
- Link to related issues
- Use GitHub Projects for visual tracking (if you're into that)
- Use issue labels consistently (see
.githubrepo for label definitions) - Update epic descriptions as scope changes (it always does)
- Quarterly planning in
/roadmap/YYYY-QX.md - Focus on outcomes, not features
- Be realistic about velocity
- Leave room for fixing things that break
- Ship working code - Better to ship something that works than plan something perfect
- Fix it in post - Launch, learn, iterate
- Communicate changes - If scope/timeline changes, say so early
- No process theater - If a process doesn't help ship better code, kill it
We use pragmatic labels across all repos:
- Priority:
p0-fire,p1-broken,p2-annoying,p3-maybe - Status:
blocked,investigating,pr-welcome - Type:
bug,feature,dx,perf,debt,docs - Effort:
effort/minutes,effort/hours,effort/days,effort/weeks
See CONTRIBUTING.md for how to contribute without wasting everyone's time.
Remember: Plans are worthless, but planning is everything. Write code, ship features, fix bugs. Everything else is negotiable.