Decision Log (Architecture Decision Records - ADRs)

This skill exists to stop: decisions living in someone's head or a chat thread — three months later the team relitigates the same question with the same arguments (Chesterton's Fence).

📁 Source note: [sage] = upstream Sage repo (github.com/xoai/sage, public) — optional deeper reading; this skill runs fully on the rules inlined here. A step marked MUST READ points at a file in your own project (e.g. an event registry) — if it is missing, stop and ask instead of improvising.

🤖 0. HOW TO USE (agent workflow)

A. Write a new ADR — the moment the decision is made, not at sprint end. Three required parts: what was decided (one sentence) · why (reasoning, not restatement) · losing alternatives WITH the reason they lost. Prepend newest first; rotate to archive at ~200 lines. B. Look up before tearing down a fence: when someone proposes reversing an old decision, read the original entry first and respond with the recorded reasoning instead of relitigating. Reference pattern: a claim-window ADR — decision, reasoning, three rejected alternatives each with its losing reason. 📄 Full original: [sage] skills/sage-decisions/SKILL.md.

1. Why Keep Decision Logs?

• Prevent Relitigation: "We chose Postgres" is a fact in the lockfile. "We chose Postgres over DynamoDB because access patterns are relational and a join layer would eliminate cost savings" is an ADR. It stops someone reopening the debate next quarter without new facts.
• Explicit Alternatives: A decision without considered alternatives is not a decision — it's an accident.