Memory is not a system of record
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.
The five-field decision note
- Context - one paragraph on the problem.
- Options - two to four real alternatives.
- Decision - what we chose.
- Owners - who executes / who can revisit.
- Date + revisit trigger - when this may be reconsidered.
Example fits on half a page. That is a feature.
When to write one
- Cross-team impact
- Hard to reverse
- People not in the room will need it
- You already repeated the debate once
Skip for tiny reversible preferences.
Bad vs good docs
| Bad | Good |
|---|---|
| 12-page RFC for a color | Five fields + link to mock |
| Decision buried in Slack | Link from ticket to note |
| No owner | Named maintainer |
| Eternal finality | Revisit trigger stated |
Meetings and docs
If you need a meeting, end with the decision note draft in the last five minutes - or do not call it decided: fewer better remote meetings. Chat threads that mattered should graduate: turn chat into a durable document.
Failure modes
Template cosplay. Fields for theater.
Doc as delay. Endless writing instead of choosing.
Secret decisions. Notes that never get linked where work happens.
Bureaucracy is process without payoff. A five-field note pays for itself the first time someone almost reopens a settled choice. ## Reversible vs irreversible threshold
Reversible choices within a sprint - feature flag off, config tweak with rollback - need lighter records: PR description suffices.
Irreversible or expensive-to-undo choices - data deletion, public API shape, pricing logic - need the five-field record even if writing feels slow in the moment.
Train the team on threshold, not on "always write a novel."
Example: two teams, same decision, two stories
Example: Platform picks gRPC internally. Product team hears "we use gRPC" in standup but never sees the rejection reasons for REST.
Mobile team builds against wrong assumptions for a week.
Fix: decision comment on shared epic linking both teams; chat message is link only.
PR descriptions as decision carriers
For engineering-heavy choices, the merged PR description is the record: what changed, what was rejected, follow-ups.
Reviewers enforce: no merge without context for the next reader.
Avoid decision by exhaustion
When documentation is heavy, teams decide in meetings and skip writing because everyone is tired. That is when a two-minute record matters most.
Assign a rotating "closer" role in meetings: last five minutes capture decision or explicit defer.
Security and compliance without a binder
Some decisions require audit trails. That is not permission to wrap every choice in process. Separate compliance decisions (logged formally) from day-to-day product choices (lightweight record).
Decision debt sprints
If folklore grows, run a half-day "decision harvest": search recurring arguments, write missing records retroactively where memory allows, mark unknowns for rediscovery.
Debt paid once beats weekly re-debate.
Async proposal pattern
Author posts: context, options, recommendation, ask-by date. Commenters vote or object with reason. Owner marks accepted and links from ticket.
Meeting optional if objections are substantive, not social.
Leaders reverse decisions in writing
When strategy shifts, add supersedes line. Deleting old records teaches team that history is fake.
Visible correction builds trust faster than silent pivot.
Connect to handoffs
Leave work someone else can continue fails when decisions live in heads. Handoff checklist includes "decisions since last update" with links.
Quality bar: can a stranger continue?
Test: could someone in another zone pick up the epic tomorrow with only the ticket thread and linked doc?
If not, documentation is not bureaucracy - it is missing. ## Decision records in client work
Freelancers should log client-visible decisions on the shared brief or ticket: scope cuts, timeline moves, tech choices the client approved. Prevents "I never agreed" later without a meeting replay tour.
Example: scope cut mid-project
Example: Client drops reporting module to hit date. Verbal on call only. Later they ask where reports went.
Fix: comment on SOW ticket: "Decision: reporting deferred to phase two per call DATE; link recording."
Avoid duplicate decision homes
One canonical comment per decision. If debate continues, edit the record with Updated line rather than spawning a second wiki page.
Small teams skip process, not records
Two-person teams still forget. Thirty seconds in the shared task beats arguing in two weeks.
Decision latency vs documentation latency
Sometimes decide fast and write rough immediately beats polish later never.
Link blockers
When decision unblocks work, tag blocked tickets in the same comment so notification does the routing.
Read time respect
Executives skim. First sentence is the decision; rest is context for implementers.
Audit without fear
Some regulated environments need more fields. Add fields only where audit demands - do not export whole template to product team.
Decisions that ship without sentences attached become meetings. Sentences are cheaper than calendars. ## Operational summary
Name the finish line before the block ends. Write one crumb for the next session. Match task shape to energy when the day goes sideways. These boring steps compound more than any single app feature. ## PR review asks for decision context
Reviewers comment "needs decision record" when merge changes behavior without comment link - same as asking for tests.
Example: config flag flip
Example: Feature flag default changes in prod. PR must say who approved and link to ticket comment.
Decisions in retros
Retro action "document X" beats retro action "communicate better." One sentence owner and link.
Clients approve in writing
When client chooses option B, paste their approval line into decision record - email quote or ticket.
Avoid meeting notes nobody reads
Meeting notes should be decision record plus action table only. Attendance narrative is waste.
Architecture decision records at scale
Larger orgs use ADR numbering. Small teams use ticket comments. Match weight to team size.
Every undocumented decision is a meeting scheduled in the future. Write the sentence now.
Decision quality over decision volume
Teams sometimes confuse documenting everything with documenting what matters. 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.
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.
Product managers and engineering alignment
PMs often decide in calls with leadership while engineering hears a summary days later. Promote decisions to the epic the same day, even rough, and tag engineering owners. Async alignment fails when decision latency is shorter in one room than in the ticket.
Example: "we'll revisit later"
Example: Team punts a choice with "we'll revisit Q2." Without a ticket and date, Q2 becomes folklore. Write: "Deferred until Q2 planning week; owner Maya; trigger metric is support tickets above N per week."
Legal and client-facing decisions
When clients choose among options, paste the chosen option into the record with who approved. Verbal yes on a call is fragile when staff changes on either side.
Tooling does not replace the sentence
Confluence trees, Notion databases, and AI summaries help only if someone maintains the canonical link on the work item. Otherwise you have two archives and zero truth.
Teaching new hires to decide in writing
Onboarding exercise: find one decision in a ticket from last month and explain it without asking a veteran. If they cannot, your documentation habit is still weak - fix that before adding templates. ## Operational summary for the week
Pick one finish line per day that matches the energy you actually have, not the energy you post about. Write one crumb for the next session before you close the laptop. When the day fragments, name the type of work you are doing so guilt does not invent a story about failure. These steps look boring in a blog post; they are what make next Tuesday start without a twenty-minute reopening tax.
Remote work removes the commute edge and the office cue that someone else saw you stop. That means the habits in this article are not productivity decoration - they are how you keep evenings and mornings from blending into one long partial-attention shift. If you only adopt one change, adopt the smallest honest version on your worst day, not the heroic version on your best day.