What problem does it solve? Code records what exists but never why — the reasoning, rejected alternatives, and constraints behind a choice evaporate unless written down at the moment of deciding. This Skill captures that intent at the cheapest tier that fits, so decisions survive context compaction and remain recoverable later. ## Core Features & Use Cases - Three-tier capture: a one-line Decision: commit trailer (always), an append-only decision note in work/<project>/decisions.md for any choice with a rejected alternative, and a promoted ADR under docs/adr/ only for decisions that are hard to reverse, surprising, and real trade-offs. - Promotion workflow: converts flagged notes into numbered ADRs with provenance, supersedes links, and index updates, then flips the source note to done → ADR-NNNN. - Graph integration: commit Refs: trailers and ADR provenance lines become edges so graphify query can answer "why does X work this way?". - Use Case: While implementing a feature you choose optimistic locking over pessimistic locking; the Skill appends a dated note with the rejected alternative and blast radius, adds a Decision: trailer to the commit, and later promotes it to ADR-0007 at checkpoint. ## Quick Start Ask the agent to log the decision you just made, including the chosen approach, the reason, and the rejected alternatives, as a note in the project's decisions file.
