If someone asks your company "who decided to use Postgres for the billing service?" — six months after the decision — most teams cannot answer. The decision was made in a Slack thread, captured nowhere, and the people involved have moved on. The fix is structural: a thin, durable layer that captures decision, decider, rationale, and authority. Sets up in a week; pays back forever.
Why most decision-tracking fails
Three patterns:
- It's a wiki section nobody opens. Decisions enter; nobody reads them; they have no effect on actual work.
- It's an ADR folder nobody updates. Three initial entries from year one; nothing since.
- It's a meeting note buried in a doc. Meeting summaries with no findable structure.
What works: a thin, structured layer used during work, not just for archival.
Step 1: define what's a decision worth tracking
Not everything. Tracking every preference produces noise. Track decisions that:
- Will likely outlast the sprint.
- Could be reversed accidentally by a future engineer who doesn't know about them.
- Required real authority — not just one engineer's preference.
Roughly 3-6 decisions per team per week qualify. If you're capturing 30, you're capturing too much. If you're capturing zero, you're missing the actual decisions.
Step 2: capture in a structured format
Four fields, mandatory:
- Decision — what was decided.
- Decider — the person or named group with authority.
- Why — the two or three reasons.
- Authority — what scope this decision covers and who would reverse it.
Optional fifth: links to the discussion thread where the decision was made.
Step 3: pick a single canonical place
One place. Searchable. Stable URLs. Whether it's a Notion database, an ADR folder, a governance tool, or a custom system matters less than: it exists, it's used, and people find it.
Tell the team: any tracked decision lives here. Anywhere else is not tracking.
Step 4: assign capture responsibility
Capture as side-of-desk fails. Two patterns that work:
- Rotating capture-of-week — one engineer per week ensures decisions get logged. 30-45 minutes weekly.
- Decider captures. Whoever decides also logs. Faster, sometimes; harder to remember consistently.
The first pattern is more reliable. The second requires culture.
Step 5: back-fill the last quarter
To bootstrap, capture the 10-15 most consequential decisions from the last 90 days. Walk Slack, walk PRs, ask the team. Two hours of effort gives you a working archive that demonstrates the format.
This is the step most teams skip. It's the step that determines whether the practice catches on or feels theoretical.
Decisions With Names Attached
StandIn captures every decision with its decider, rationale, and authority — so 'who decided' is never a question again.
See the Workflow →Step 6: use the archive in PR review
Wire it into the workflow. PRs that touch a surface with prior decisions: reviewers check alignment. PRs that propose reversing a decision: link to the original. This is what keeps the archive useful instead of becoming a museum.
Step 7: audit findability monthly
Once a month, pick a decision from 60 days ago and try to find it in under 3 minutes. If you can, the system works. If you can't, find out why — usually format issues or naming inconsistencies — and fix it.
Common failure modes
Failure: requiring decisions to be tracked formally before they can be acted on. Adds friction; nobody complies. Let decisions be made, then captured.
Failure: tracking only the big decisions. The small ones reverse most often. Capture both.
Failure: making capture too elaborate. Four fields, five minutes. Forms with 12 fields die quickly.
What to do tomorrow
Pick the canonical place this week. Capture three decisions from the last sprint in the four-field format. Pin the doc in the team channel. The friction you feel will tell you what to adjust before rolling out to the team.
Frequently asked questions
What's the difference between this and an ADR?
ADRs are one implementation of this pattern. Whatever format you use, the four fields matter more than the name. Choose ADRs if your culture is doc-heavy; choose a database if it's not.
Should the CEO's decisions be tracked here too?
Tracking the decisions that affect engineering: yes. Org-wide strategy decisions: usually a separate system. Keep the engineering archive focused or it sprawls.
What happens when a decision is reversed?
Mark the original as superseded with a link to the new entry. Don't delete. The reversal is data — six months from now you'll want to see both.
Get async handoff insights in your inbox
One email per week. No spam. Unsubscribe anytime.
Ready to eliminate your daily standup?
Distributed teams use StandIn to start every shift with full context — no standup required. Engineers post a 60-second wrap. The next shift wakes up knowing exactly what to work on.