Most engineering teams use 5-8 tools for daily work. Decisions get made in all of them. Three months later, when someone asks "why did we choose this?" — nobody can find the thread. The fix is not consolidating tools (that fails). It's establishing one canonical decision layer that points back into the tools where the discussion lives.
Why tool consolidation isn't the answer
Teams try to fix decision sprawl by moving everything into one tool — usually a wiki. It fails for two reasons: discussions don't happen in wikis, and the people who care about the decision are not the people who'd document it after the fact.
The realistic alternative: let discussions happen wherever they happen, but require every decision to land in one canonical place with links back to the source.
Step 1: pick the canonical decision layer
One place. Searchable. Stable URLs. The candidates: an ADR folder in your monorepo, a Notion database, a dedicated decisions tool, or a governance platform. Pick one. Stop debating; the choice matters less than the existence.
Tell the team: any decision that should outlive the sprint goes here. Anywhere else is the discussion, not the record.
Step 2: define the entry format
Each entry has six fields: title, decision, why, considered-and-rejected, authority, links-to-source. That last field is what makes the canonical layer work — every entry points back to where the conversation actually happened.
Six fields, five minutes per decision, one canonical source of truth.
Step 3: tag the discussion in source tools
In each source tool — Slack, Linear, GitHub, Notion — establish a convention for marking that a decision has been captured. Slack: a 📌 emoji or a reply with the canonical link. GitHub: a label or a final comment with the link. Linear: a custom field or status.
The tags let you find the canonical record from the source, not just the source from the canonical record. Bi-directional linkage is the property that makes the system survive.
Step 4: assign rotating capture duty
Decision capture as side-of-desk fails. Designate a rotating capture-of-week — one engineer who, during their week, ensures decisions get promoted. 30-45 minutes a week. Rotate quarterly.
This costs less than the cost of one untracked decision that gets reversed accidentally.
One Queryable Decision Layer
StandIn pulls decisions out of Slack, Linear, GitHub, and Notion into one queryable record — so 'who decided' is never a Slack search.
See the Workflow →Step 5: review unfindable decisions monthly
Once a month, the team picks a decision from 60 days ago and tries to find it from scratch. Time how long it takes. If the answer is "under 3 minutes," the system works. If it's "we can't find it," the system is leaking.
This audit is the only feedback loop that prevents decision-tracking from silently degrading.
Use the canonical layer in PR reviews
Wire decision links into the workflow. When a PR touches a system with prior decisions, reviewers check that the PR aligns with the latest decision — or surfaces a need to update it.
This is what makes the canonical layer actually drive behavior, instead of being a museum.
Common failure modes
Failure: requiring decisions in three places. Triple-bookkeeping fails. One canonical place plus tags in source tools is enough.
Failure: capturing only big architecture decisions. Most reversals happen on small decisions — naming, error handling, retry policy. Capture those too.
Failure: letting the canonical layer rot. If decisions enter but nobody reads them, the system has no feedback. Read them in PR review. Read them in onboarding. Read them at quarterly planning. Use creates the discipline.
What to do tomorrow
Pick the canonical layer this week. Move three recent decisions into it as proof. Send the team channel a 5-line note: "Here's where decisions live now. Here's the format. Here's a 📌 convention in Slack." Three weeks from now, run the find-a-decision audit. If it works, expand the practice.
Frequently asked questions
Should I use a dedicated decisions tool or just a wiki?
Wikis work if the search is reliable and the team will use them. Dedicated tools work if the wiki habit doesn't exist. The constraint is human behavior, not feature set.
What if half the team won't promote decisions?
Use the rotation pattern — one person per week handles promotion. Don't require it of everyone; make it someone's explicit job in turn.
How long should decisions stay in the archive?
Indefinitely. Old decisions are cheap to store and occasionally invaluable to revisit. Don't prune; mark superseded and link to the new entry.
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.