Feature Decision Records (FDRs)

Manage features as structured markdown documents in docs/fdr/. Each FDR captures what a feature does from a user perspective and the design decisions that shaped it, with rationale.

What an FDR Is

An FDR is a single source of truth for one feature. It answers:

• What does the feature do, behaviorally? (no implementation details)
• Why is it built this way? (the design decisions, with rationale)
• Where does it fit? (related ADRs, related FDRs, permissions that gate it)

Alongside superpowers

Feature decisions land mid-flow: superpowers:brainstorming gets one accepted; a subagent that departs from the plan has made one. Create or update the FDR the moment it lands, then continue. Before designing in an area — and when briefing a subagent into it — read docs/fdr/INDEX.md and the records it names: current FDRs constrain the redesign and carry the why that code can't.

FDRs sit alongside ADRs (docs/adr/). The split: