Decision Ledger

Keep a record of why your team decided things — not just what you decided.

Six months from now, when someone asks "why did we do it this way?", the answer is one command away. Every decision is a small text file. Every change is saved in git, so you always know who decided what, when, and why.

Runs in your terminal

There's nothing to sign up for and nothing to install. It runs right in your terminal, and the only things it needs are git and bash — both already on every Mac and Linux machine. Your decisions are just text files in a folder you own; git keeps the history.

Install

./decision-ledger/install.sh

That's it. (If you also use an AI assistant like Claude Code, run /search-reindex afterward so it can find your decisions — optional.)

The three things you'll do

Write down a decision:

./scripts/ledger.sh new "Use Postgres instead of DynamoDB" --why "we already know it; don't need huge scale yet"

Ask why later:

./scripts/ledger.sh why 0002

This shows the decision, the reason behind it, and how your thinking changed over time.

Change your mind:

./scripts/ledger.sh supersede 0002 "Switch to DynamoDB" --why "we now need much faster reads"

The old decision isn't deleted — it's marked as replaced and linked to the new one, so the history stays honest.

The time machine

Want to know what you believed on a past date?

./scripts/ledger.sh as-of 2026-03-03

Other handy commands

./scripts/ledger.sh list        # see every decision
./scripts/ledger.sh timeline    # see the order things were decided
./scripts/ledger.sh help        # full list of commands

Prefer to just chat?

Inside Claude Code you can skip the commands and type:

• /decision "..." — write down a decision (it'll ask you for the reasoning)
• /why 0002 — ask why
• /supersede 0002 "..." — change your mind

Both ways do the same thing.

The one rule

You can't quietly rewrite an old decision. If you try to change what an accepted decision said, git stops you and tells you to use supersede instead. That's what keeps the record trustworthy — it shows how your thinking actually changed, not a tidied-up version after the fact.

Check it works

make test

This runs a quick self-check (it builds a throwaway ledger and tries everything). You should see ALL GREEN.

What's in here

install.sh                 One-command setup
scripts/ledger.sh          The command-line tool
scripts/test.sh            The self-check
hooks/pre-commit           The rule that stops decisions being rewritten
workers/decision-keeper/   The Claude Code worker (for the chat-style commands)
commands/                  /decision, /why, /supersede
knowledge/decisions/       Your decisions live here (one file each)
Makefile                   Shortcuts: make new / why / list / audit / test

Sharing across teams

Run the installer with --public and the ledger can be shared between setups, so several teams pull from and add to one shared record. See INSTALL.md.

Tech stack: plain bash scripts + git for storage and history, markdown records, and a git pre-commit hook for the append-only rule. Ships as an Indigo HQ package (worker + slash commands) and also runs standalone.