documentation-and-adrs

Create a numbered markdown file in docs/decisions/ with sections for Status, Date, Context, Decision, Alternatives Considered, and Consequences. Document why each alternative was rejected, not just which option won, so future readers understand the constraints.

Write an ADR when choosing frameworks or major dependencies, designing data models, selecting authentication strategies, deciding API architecture, or making any decision expensive to reverse. Skip ADRs for trivial or easily reversible choices.

Comments should explain why code exists, not what it does. Document non-obvious intent, constraints, and known gotchas. Avoid comments that restate the code, TODO markers for work you should do now, and commented-out code that git history already preserves.

No, old ADRs capture historical context and should be kept. When a decision changes, write a new ADR that references and supersedes the old one, updating the old record's status to Superseded.

This Skill provides templates and conventions but does not enforce them automatically. Teams must still adopt the discipline of writing ADRs at decision time, since retroactive documentation often loses the original context and trade-off reasoning.