Five fields beat a wiki religion
Remote teams re-argue choices because the choice lived in a call or a chat thread. Documentation fear swings to the other extreme: templates nobody fills. Aim for the smallest durable record that prevents re-litigation - half a page, linked from the work item, with a named owner: Context, Options, Decision, Owners, Revisit trigger.
Bureaucracy is process without payoff. A five-field note pays for itself the first time someone almost reopens a settled choice. Chat starts the conversation; the decision note finishes institutional memory. Promote a thread when the choice is hard to reverse, affects people not in the room, or you already repeated the debate once. Skip for tiny reversible preferences.
When chat should become a decision record
Promote a thread (or meeting) into a durable note when any of these is true:
- Decision with cross-person or cross-team impact
- Hard to reverse or expensive to undo (API shape, data deletion, pricing logic)
- People not in the room will need the reasoning
- You already repeated the debate once
- How-to or incident timeline you will need twice
- Spec changing while people argue in-thread
Skip for tiny reversible preferences. Feature-flag flips with easy rollback can live in a PR description. Irreversible choices need the five-field record even when writing feels slow.
How to graduate in five minutes: create a short ticket comment or page; paste the conclusion, not the whole argument; link the chat thread for archaeology; replace future answers with the link; name an owner for freshness. Keep notes lean (useful work notes).
Decision log template (copy into the ticket)
## Decision: [one-line title]
Date: YYYY-MM-DD
Status: Accepted | Deferred | Superseded by [link]
Context:
[One paragraph: problem and constraint]
Options considered:
1. ...
2. ...
3. ...
Decision:
[What we chose - first sentence is the choice]
Why / tie-breaker:
[Cost, risk, time, or user impact - say it explicitly]
Owners:
Execute: [name]
Revisit authority: [name]
Revisit trigger:
[Date, metric, or event - e.g. "Q2 planning" or "support tickets > N/week"]
Links:
Work item: ...
Chat/meeting: ...
Related decisions: ...Executives skim. First sentence under Decision is the choice; the rest is for implementers. When strategy shifts, add a Supersedes line - do not delete history.
Example filled in
## Decision: Checkout tax via TaxService, not inline cart math
Date: 2026-09-12
Status: Accepted
Context:
Cart calculates tax inline; finance spreadsheet disagrees on two EU rates; support tickets rising.
Options considered:
1. Keep inline math and patch rates monthly
2. Call TaxService for all carts (chosen)
3. Hybrid: TaxService for EU only
Decision:
All carts call TaxService; inline math removed behind flag tax_service_v1.
Why / tie-breaker:
One source of truth beats faster inline path; EU ticket volume is the pain.
Owners:
Execute: Sam
Revisit authority: Priya (platform)
Revisit trigger:
Error rate on tax_service_v1 > 0.5% for 7 days, or finance rejects sample orders.
Links:
Epic CHECK-220; thread #checkout 2026-09-11; ADR not required at team size.Without that record, product hears "we use TaxService" in standup while mobile still builds against inline assumptions for a week.
Async proposal pattern and meeting close
Author posts: context, options, recommendation, ask-by date. Commenters object with reason. Owner marks accepted and links from the ticket. Meeting optional if objections are substantive (fewer better remote meetings).
If you need a meeting, end with the decision note draft in the last five minutes - or do not call it decided. Assign a rotating "closer" role: last five minutes capture decision or explicit defer with date. Avoid deciding by exhaustion and skipping the write because everyone is tired - that is exactly when the two-minute record matters most.
Leaders reverse decisions in writing. Visible correction builds trust faster than silent pivot.
Bad vs good decision docs
| Bad | Good |
|---|---|
| 12-page RFC for a button color | Five fields + link to mock |
| Decision buried in Slack | Link from ticket to note |
| No owner | Named maintainer |
| Eternal finality | Revisit trigger stated |
| Meeting notes as attendance narrative | Decision + action table only |
| Two wiki homes for one choice | One canonical comment; Updated lines |
Quality bar: could someone in another zone pick up the epic tomorrow with only the ticket thread and linked doc? If not, documentation is missing - not bureaucracy.
Client work and PR descriptions
Freelancers should log client-visible decisions on the shared brief or ticket: scope cuts, timeline moves, tech choices the client approved. Paste their approval line. Example: "Decision: reporting deferred to phase two per call DATE; link recording." Prevents "I never agreed" without a meeting replay tour.
For engineering-heavy choices, the merged PR description can carry the record: what changed, what was rejected, follow-ups. Reviewers enforce: no merge that changes behavior without context for the next reader. Config flag default flips need who approved and a ticket link.
Failure modes to avoid
Template cosplay. Fields for theater. Use the five fields; add compliance fields only where audit demands.
Doc as delay. Endless writing instead of choosing. Decide, write rough immediately, polish later never is worse than rough now.
Secret decisions. Notes that never get linked where work happens.
Wiki landfill. Graduating everything. Use the promotion triggers.
Duplicate homes. Edit the record with an Updated line rather than spawning a second page.
Decision harvest half-day (when folklore is already thick)
If the team re-argues the same three choices monthly, run a harvest:
- List the recurring arguments from the last quarter (chat search + retro notes).
- For each, write a five-field record from memory as best you can; mark unknowns honestly.
- Link each record from the live epic or README so the next debate starts at the link.
- Assign owners and revisit triggers so "we'll revisit later" has a date.
- Stop when the top five arguments have records - do not boil the ocean into a wiki religion.
PM and engineering alignment tip: when leadership decides in a call, promote a rough decision comment to the epic the same day and tag owners. Async fails when decision latency is shorter in one room than in the ticket.
When two options are close, write the tie-breaker explicitly - cost, risk, time, or user impact. Future debates often reopen because the tie-breaker lived in tone of voice, not in text. A decision record should answer a stranger's question: "What did you pick and what did you reject?" If it only narrates that a meeting happened, it will not prevent the next meeting.
Tooling does not replace the sentence. Confluence trees and Notion databases help only if someone maintains the canonical link on the work item. Otherwise you have two archives and zero truth.
Onboarding exercise: ask a new hire to find one decision from last month in a ticket and explain it without asking a veteran. If they cannot, fix the habit before adding templates. Retro action "document X with owner and link" beats "communicate better."
Two-person teams still forget. Thirty seconds in the shared task beats arguing in two weeks. When decision unblocks work, tag blocked tickets in the same comment so notification does the routing. Every undocumented decision is a meeting scheduled in the future. Write the sentence now.