decision-loglisted

# Decision Log — Ruled Out, Made Permanent A handoff's `Ruled out` section dies with the handoff. A decision log does not. Without one, a rejected approach comes back every few weeks, gets re-argued from scratch, and sometimes wins the second time purely because nobody remembers why it lost. The cost is not the discussion — it is silently reversing a decision that had a good reason. **Two operations, and the read is the one that matters.** ## Search before proposing Before proposing an approach, or when a question smells settled: ```bash grep -il "<term>" docs/decisions/*.md 2>/dev/null | tail -5 ``` Anything that hits, read whole. Then: - **The decision stands** → say so, cite it, move on. Do not re-derive the reasoning. - **You want to reverse it** → say that explicitly. *"This reverses D-014, which chose X because Y; that reason no longer holds because Z."* A silent reversal is the failure this file exists to prevent. - **It is genuinely new** → proceed, and log it when it lands. ## Log when it lands One file per decision, `docs/decisions/D-NNN-slug.md`, append-only: ```markdown --- id: D-014 date: 2026-07-26 status: accepted # accepted | superseded supersedes: # D-009, if this reverses one superseded_by: # filled in later, never deleted tags: [storage, api] --- # D-014 — <the decision in one line> ## Context What forced a choice. The constraint, not the whole history. ## Decision What was chosen, stated so someone can act on i