Decision Tracking¶

Philosophy: Document decisions so future you understands why

Overview¶

Tracking decisions prevents re-litigating past choices, provides context for new team members, and creates institutional knowledge. Use lightweight tools for small decisions, structured ADRs for significant ones.

Files in This Directory¶

adr_000_template.md - Architecture Decision Record template
adr_001_example.md - Example ADR (lock-free ring buffer)
decision_log_template.md - Quick decision logging
rfc_process.md - Request for Comments process
retrospective_format.md - Sprint retrospective format

When to Use What¶

Decision Type	Tool	Example
Architecture decision	ADR	"Use lock-free data structures for audio thread"
Major feature design	RFC → ADR	"New state management system"
Minor tech decision	Decision Log	"Use Catch2 for unit tests"
Process improvement	Retrospective	"Add dedicated review time blocks"
Team decision	Meeting Notes	"Sprint planning outcomes"

Quick Reference¶

ADR (Architecture Decision Record)¶

Use for: Significant architectural or technical decisions Format: Structured document with context, decision, consequences, alternatives Storage: Git repository (docs/adr/ or alongside code) Template: adr_000_template.md

RFC (Request for Comments)¶

Use for: Proposing major changes, gathering feedback before implementation Format: Design document shared with team for review Process: Draft → Share → Discuss → Decide → (Create ADR if significant) Guide: rfc_process.md

Decision Log¶

Use for: Smaller decisions worth documenting but don't need full ADR Format: Date, decision, rationale in simple log Storage: Wiki or shared doc Template: decision_log_template.md

Retrospective¶

Use for: Team process improvements after sprint/release/incident Format: Facilitated meeting → action items Frequency: Every 2 weeks (end of sprint) Guide: retrospective_format.md

Best Practices¶

Writing Decisions¶

✅ Do: - Explain the "why" not just the "what" - Document alternatives considered - Note tradeoffs explicitly - Link to discussions and references - Update if decision changes

❌ Don't: - Write novel (be concise) - Skip alternatives (show you thought it through) - Be vague (future you won't understand) - Let them get stale (review and update)

Storing Decisions¶

ADRs: Version control (Git) - Part of codebase - Can reference from code - History preserved

Decision Log: Wiki or docs repo - Easier to browse - Lower barrier to entry

Meeting Notes: Wiki, linked from calendar - Easy to find - Connected to meeting

Retrospective Notes: Project management tool or wiki - Track action items - Review in next retro

Communication Setup - Where to communicate decisions
Knowledge Sharing - Organizing team knowledge
Project Management - Tracking work

Resources¶

Remember: The best decision is the one that's documented. Future you will thank you!