Remote and async work makes this worse. Decisions happen in meetings half the team misses, or in Slack threads that scroll into oblivion. The pain isn’t about “we need more documentation”. The pain is wasted time, unclear ownership, and a team that can’t move forward because no one’s sure what was already agreed.

Architecture Decision Records (ADRs) fixed this for my projects. Not as documentation overhead, but as a structured approach to conversations we were already having in an unstructured way.

The Real Cost of Undocumented Decisions

Decisions made in Slack threads or meetings leave no artifact. No traceability. Someone asks “how do we plan to fix this?” or “why did we choose X?” and the answer becomes an archaeological dig through chat history, meeting recordings, or the memory of whoever happened to be in the room.

Without a clear decision record, anyone can reopen the debate. And they will. Not out of ill intent. They genuinely don’t know it was already settled, or they weren’t there when it happened. Management can’t track blockers when decisions are stuck in someone’s head. Work stalls quietly.

In startups, the response is often “we’re too small for process”, which is ironic. You’re already paying the cost: repeated debates, context that lives in one person’s brain, in onboarding that requires a verbal history lesson. Not documenting decisions is a shortcut, and like every shortcut, it’s a bet. You’re betting you won’t need to revisit them. I’ve seen it firsthand: in some of my previous teams there was no single source of truth for architectural decisions. Every onboarding became a tribal knowledge transfer. A good number of refactor proposals started with “check the code” commonly followed by “why did we build it this way?”

At scaleups, the coordination overhead multiplies. Fifty engineers means fifty people who might reasonably ask “why?”. Without a record, that could mean fifty separate conversations to answer them.

What ADRs Actually Are (And Aren’t)

An Architecture Decision Record (ADR) is, at its core, a record of why a decision was made, not just what was decided. That distinction matters. The “what” is usually visible in the code. The “why” disappears the moment the meeting ends.

Think of ADRs as requirements engineering disguised as documentation. The artifact, the written record, is a byproduct. The real value is the structured decision-making process that produces it. Writing an ADR forces you to articulate the problem before jumping to solutions. Why before what principle.

ADRs can be a tool for async decision-making in remote teams. They’re the reference that ends “why did we...” conversations in thirty seconds. They are not bureaucratic overhead—a useful ADR can be a ten-line markdown file in your repo. They’re not only for “big” decisions; anything worth debating twice is worth an ADR. And they don’t replace discussion, they structure it.

The Minimum Viable ADR needs just four fields:

1. Context: What’s the situation? What problem are we solving?

2. Decision: What did we decide?

3. Consequences: What are the trade-offs? What did we accept or reject?

4. Status: Draft / Proposed / Accepted / Superseded

A more extended version adds:

• Positions: All approaches considered before the decision was taken. Typically two to four options, each with pros and cons, with the decision stating which approach won (or a combination, if the approaches were complementary).

• Stakeholders: Who needs to be consulted or informed? Who has the final call?

• Related ADRs: Links to previous decisions this one builds on or supersedes.

• Date: When the decision was proposed and when it was accepted.

• Artifacts: Freestyle :) Various proofs or even raw data related to positions and the final decision.

ADRs can live anywhere: a markdown file in your repo, a Confluence page with tags and mentions, a Notion database. The format matters far less than the habit.

As AI-powered search becomes standard, structured records like ADRs become even more valuable. They’re exactly the kind of knowledge that LLMs and search tools can surface instantly.

How ADRs Changed Dynamics Inside My Team

At one of my teams, I introduced a full Architecture Repository. ADRs were one piece alongside Architecture Migrations, Procedures, Post Mortems and a Risk Registry. But ADRs had the most immediate impact.

Before ADRs, the same debates resurfaced every few weeks. Decisions stalled because no one knew who owned them. Remote team members felt excluded from decisions made in meetings they couldn’t attend. Management couldn’t see what was blocked or why.

After we adopted ADRs, these things changed:

• Fewer “why did we do this?” conversations. New project members (e.g. engineers or project owners from different teams) onboarded faster. They read the ADRs instead of hunting down so-called tribal knowledge. We use ADR references instead of re-explaining context in every PR and discussion thread.

• Clearer blockers. “We need a decision on ADR-XYZ-042” became a trackable, actionable item. Management got more responsive when decisions were formalized. It’s harder to ignore an official ADR than a chat thread buried under emoji reactions.

• Async work, unlocked. Remote-first teams could propose, debate, and decide without synchronous meetings. Comments on the ADR replaced circular threads that went nowhere.

• Faster decision velocity. Structured options forced focus. Instead of endless open-ended debate, we evaluated concrete trade-offs side by side. Decisions that used to take weeks took days.

• (the unexpected benefit) Mental clarity. Writing an ADR forces you to clarify your own thinking. You take all the feedback, all the competing concerns, and put them into structured form. More than once I heard engineers say some version of: “I thought I knew what I wanted until I tried to write down why.” The act of writing is the act of thinking.

Notice these benefits cut across all four layers of value: faster decisions help the company, async unlocking helps the team, clearer blockers help customers get features sooner, and the mental clarity is deeply personal. ADRs might feel like overhead, but the decision is the deliverable. Shipping the ADR is shipping value, not activity.

The 5-Minute ADR Test

Not every decision needs an ADR. But more decisions deserve one than most teams think. Here’s a quick test: ask these five questions. If you answer “yes” to two or more, write an ADR.

Try this: Think about the last three technical debates your team had. Run them through this test. I’d bet at least one deserved an ADR.

ADR Lifecycle: From Draft to Superseded

ADRs aren’t static documents. They move through stages:

• Draft. You’re still forming the proposal. Not ready for formal review, but visible to the team.

• Proposed. Ready for team input. This is where async discussion happens—comments, counter-proposals, refinements.

• Accepted. Decision made. This is now the canonical record. The team aligns on this.

• Superseded. A newer ADR replaces this one. Link to the new ADR so the decision trail stays clear.

• Deprecated. No longer relevant. The system was removed, the context changed, the decision no longer applies.

The key rule: ADRs are append-only. You don’t edit an accepted ADR. You supersede it with a new one that references the old. This preserves the full decision trail, including why you changed course.

One process tip that makes the whole system work: assign a clear owner to every ADR. Someone needs to shepherd it from Proposed to Accepted, gather input, and make the call or escalate if needed. Ownership applies here just as much as it does in code.

Maintaining Your ADR Repository

ADRs only work if people can find them. The fastest way to kill adoption is a repo of decisions nobody can navigate.

Discoverability is everything. Use consistent naming: ADR-XYZ-001, ADR-XYZ-002 or a tagging system. A simple index file that lists all ADRs with their status and a one-line summary goes a long way.

Link ADRs to code. Reference them in comments, commit messages, and PR descriptions. “See ADR-017 for context” turns a confusing code decision into an understandable one. Consider making ADRs part of your acceptance criteria or definition of done for decisions that affect architecture.

Review quarterly. Are there Proposed ADRs stuck in limbo? Superseded ADRs that need cleanup? A thirty-minute quarterly review keeps the repository healthy and signals that the team takes decisions seriously. Think of it as keeping your decision-making process evolving alongside your codebase.

Keep ADRs close to the work. Markdown files in /docs/adr/ in the code repo get seen. ADRs buried deep in Confluence get forgotten. On the other hand, for broader architectural choices that span teams, a shared Confluence or Notion space with proper tagging works well.

Maybe a hybrid approach: code-level ADRs for implementation decisions, a shared wiki for cross-team choices covers most of your needs.

The format and tooling will depend on your team. Start simple, one ADR for a decision that keeps coming up, and evolve from there.

As for my own projects: We stopped having the same debates. Not because everyone agreed but because we finally wrote down why we disagreed, what we chose, and what we accepted as trade-offs. The next time someone asked, there was a link.

You’re already making decisions. ADRs just make sure you only make them once.

You get asked to help. Interviews. Code reviews. “Quick” syncs. Onboarding. Each request sounds small. Each one feels impossible to refuse.

But say yes to everything without accounting for the real cost, and suddenly you’re behind on your actual commitments. Not because you’re slow. Because nobody, including you, counted the hours.

This isn’t about learning to say no. It’s about learning to say yes sustainably. There’s a difference.

As a senior+ engineer, I’ve often been asked to help with interviews—sometimes for other teams that didn’t have the capacity or were being built from scratch. The kind of request that feels impossible to refuse. Of course you help. Hiring matters. You’re a team player.

The Math Nobody Does

When someone asks you to “help with an interview,” what they’re picturing is the interview itself. Ninety minutes, maybe two hours. A calendar block. Done.

Here’s what actually happens:

Before the interview you have to:

• Read the candidate’s CV and any prior feedback (20-30 minutes)

• Review the role requirements, refresh on what we’re looking for (15-20 minutes)

• Prepare questions tailored to this candidate’s background (20-30 minutes)

The interview itself:

• The actual conversation (60-90 minutes)

• Buffer time for overruns and transitions (15-30 minutes)

After the interview:

• Document detailed feedback while it’s fresh (30-45 minutes)

• Sync with the hiring manager or director (15-30 minutes)

• Possible follow-up discussions with other interviewers (15-30 minutes)

Add it up: 2 to 4 hours per candidate. Not 60-90 minutes. Half a day.

And if there are multiple interviews in your sprint? If you’re doing panel interviews with another engineer? Double it.

Say Yes, Then Make It Visible

Aligning on expectations, estimates, and prioritization matters most. At startups and scaleups, where sprint capacity is already tight, this alignment prevents the slow bleed of unplanned work.

For example, consider this message:

“Hey team, happy to help with interviews. Quick note for planning: please account for 2-4 hours of capacity per interview. That covers prep, the interview itself, documentation, and syncing results. Just want to make sure we’re all on the same page.”

That’s it. No pushback. No refusal. Just visibility.

This single message did three things:

1. It set expectations. Now everyone knows what the commitment actually is.

2. It protected your sprint. Your manager can see the real capacity impact.

3. It helped others. Other engineers in the channel now have language to use themselves.

Making invisible work visible is being professional.

This is VDE Principle #6 in action: reduce friction, eliminate empty rituals. If nobody’s tracking the real cost of these requests, that’s friction. Make it visible.

The Process Questions Nobody Asked

Let’s take this a step further. Assuming you accepted an emerging task such as an interview. You clarified timeframes and everyone is aligned. Great!

At this point, you might start thinking: “How will this play out? What should this process look like?”

If you are uncertain about how to tackle the interview, you should ask follow-up questions:

• Do we have a formal interview process documented?

• How many people should interview each candidate?

• Are we calibrated? Is one interviewer consistently harsher than another?

• Who owns the interview scorecard (and evaluation guide, maybe), and when was it last updated?

In most cases you should get enough context to keep pushing your task. Feedback doesn’t have to be ideal; it just has to be good enough.

If the answers are vague, that might tell you: there is no process.

And if there’s no process, someone needs to create one. That someone is usually whoever asks the question — which is why most people don’t ask.

But creating a process is also work. It needs to be scoped, scheduled, and owned. You can’t just absorb it into your existing commitments and hope nobody notices.

So in this case you might decide on something like this:

“If we need to formalize the interview process, that’s probably a dedicated task. Should we create a ticket for it and assign an owner?”

Now it’s visible. Now it’s trackable. Now someone has to make a decision about whether it matters enough to prioritize.

The Four Layers of Value

This situation is a perfect example of VDE Principle #3: evaluate decisions through four layers of value. Every engineering decision affects customers, company, team, and yourself. Here’s how it plays out.

• Customer value: If I’m behind schedule because I absorbed unplanned work, my team ships late. That means customers wait for features, or bugs take longer to fix. The impact is indirect but real.

• Company value: Hiring is critical. Bad hires can cost six figures when you factor in recruiting, onboarding, lost productivity, and eventual replacement. Helping with interviews is genuinely valuable to the organization.

• Team value: As software engineers, our primary commitment is to our team’s sprint, iteration, or whatever floats your boat. If we disappear for half a day every time there’s an ad-hoc task, our team’s commitments slip. That’s a real cost — it just happens to be invisible unless someone makes it visible.

• Personal value: If we keep absorbing unplanned work without speaking up, we become engineers who are always behind schedule. Not because we’re slow, but because we said yes to everything without accounting for the true cost. That’s a career problem.

Saying yes to everything feels like being a good team player. But if your yes comes at the cost of your actual commitments, you’re creating problems at all four layers.

At a startup, unplanned work can sink a sprint because you’re already running lean. At a scaleup, it creates coordination chaos across teams and suddenly you’re blocking others. Either way, the cost is real.

The Principle: Sustainable Yes

The skill here isn’t saying no. Saying no is easy, but it burns bridges and makes you look unhelpful.

The skill is saying yes sustainably. Which means:

Say yes, because the work usually does matter. But make the cost visible before you’re underwater, not after. Ask the process questions, because if there’s no process, you’re not the only one struggling. Then let others make the tradeoff with full information, not assumptions.

When you name the cost publicly, you’re being the kind of senior engineer who thinks about systems, not just tasks.

Next time someone asks you for “a quick favor” that isn’t quick, try this:

“Happy to help with [X]. For planning purposes, this typically takes [realistic time estimate] when you include [list the hidden work]. Can we make sure that’s accounted for in this sprint?”

You’re not refusing. You’re being honest about what help actually costs.

That’s how senior engineers protect their capacity without burning bridges.

The Cheat Sheet: What “Quick” Requests Actually Cost

“Help with an interview”

You assume it takes 90 minutes.

It actually takes 2-4 hours:

• CV review and prior feedback (20-30 min)

• Role requirements and prep (15-20 min)

• Tailored question preparation (20-30 min)

• The interview itself (60-90 min)

• Buffer for overruns and transitions (15-30 min)

• Detailed feedback documentation (30-45 min)

• Sync with hiring manager (15-30 min)

• Follow-up discussions with other interviewers (15-30 min)

“Onboard the new person”

You assume it takes a few pairing sessions.

It actually takes 8-15 hours over 2 weeks:

• Environment setup troubleshooting (1-2 hours)

• Codebase walkthrough (2-3 hours)

• Pairing on first tasks (3-5 hours)

• Code review with teaching (2-3 hours)

• Answering questions throughout (1-2 hours)

“Quick code review”

You assume it takes 30 minutes.

It actually takes 1-2 hours:

• Pull branch and run locally (10-15 min)

• Understand context and requirements (15-20 min)

• Actual review (20-30 min)

• Write constructive feedback (15-20 min)

• Follow-up discussion (10-20 min)

• Re-review after changes (15-30 min)

“Join this sync meeting”

You assume it takes 30 minutes.

It actually takes 1-1.5 hours:

• Pre-read materials (15-20 min)

• Actual meeting (30 min)

• Context switching overhead (10-15 min)

• Action items and follow-up (15-20 min)

“Can you document this?”

You assume it takes an hour.

It actually takes 3-5 hours:

• Understand what needs documenting (30-45 min)

• Write first draft (1-2 hours)

• Add diagrams or examples (30-60 min)

• Review and revise for clarity (45-60 min)

• Get feedback and update (30-45 min)

“Debug this production issue”

You assume it takes a few minutes.

It actually takes 2-6 hours:

• Get access to logs and metrics (15-30 min)

• Reproduce the issue (30-60 min)

• Trace through the code (45-90 min)

• Identify root cause (30-90 min)

• Test the fix (30-60 min)

• Document for postmortem (30-45 min)

“Spike out this approach”

You assume it takes a couple hours.

It actually takes 1-3 days:

• Research existing solutions (1-2 hours)

• Prototype implementation (5-10 hours)

• Test edge cases (1-2 hours)

• Document findings and trade-offs (1 hour)

“Present at the team meeting”

You assume it takes the meeting length.

It actually takes 2-3 hours:

• Prepare slides or talking points (45-60 min)

• Rehearse if needed (15-30 min)

• Actual presentation (30 min)

• Q&A and discussion (20-30 min)

• Follow-up questions after (15-30 min)

Every “quick” request has hidden work attached. The senior move is knowing what that work is and saying it out loud before you’re buried.

Have you ever counted the real hours on a “quick” request and been surprised? What’s the biggest gap you’ve found between perceived vs. actual time? I’m curious what’s missing from this list.

If this resonated, share it with a fellow engineer who’s drowning in “quick” requests. They’ll thank you. And if you’re not subscribed yet, subscribe now so you don’t miss the next one.

Why did this happen in the first place?

More importantly, how do you stop it from happening again?

The hotfix is only temporary. It needs to be replaced with a proper solution. Priorities have to shift.

The incident must be clearly communicated across development, sales, customer support, compliance, security, and product teams.

How do you manage all of this?

A well-crafted postmortem will become your best friend.

Why Postmortems Matter

Software systems are complex, interconnected, and constantly evolving. Especially in SaaS products, no matter how experienced your team is, incidents will happen. Downtime, data corruption, misconfigurations, regressions, customer complaints, and even full-scale outages are all part of a software team’s experience.

During an incident, the top priority is to contain it and resolve the issue as quickly as possible. Patching, hotfixing, and restoring service come first. How to manage incidents effectively is a topic for another day…

But once the dust settles, we have a responsibility to look back, blamelessly, and understand what actually happened. That is where the postmortem comes in. A good one summarizes the incident, traces the sequence of events, and identifies the root cause. It shows us where we can improve: in our code, our processes, our testing, or our monitoring. It also helps us reflect on the incident response itself, revealing ways to strengthen our resilience and readiness.

A postmortem gives us a chance to move beyond “what broke?” and ask “why?”. A well-analyzed and clearly communicated postmortem helps ensure we do not make the same mistake twice.

Common Pitfalls

In my experience, most postmortems I have seen were thoughtful and well written. But occasionally, I have come across several that just felt off. In one case, the author directly pointed to an individual as the cause of the incident. This set off a long, uncomfortable discussion where the conversation quickly turned into finger-pointing. It escalated unnecessarily, with middle management stepping in and starting to dig into who did what, instead of helping the team move forward.

To be fair, the person did make an honest mistake. But it was the kind of issue that a properly set up CI/CD pipeline could have caught. At first, the discussion focused too much on personal accountability, rather than looking at how the process could be improved or what safety nets were missing. Fortunately, as more people joined the conversation, the tone shifted and the focus turned back to how to prevent similar issues in the future.

Blame is one of the most common and damaging pitfalls in postmortems. When people feel they are being singled out, they stop sharing openly, which undermines the whole point of reflection and improvement. Another common mistake is writing vague or non-actionable takeaways. Phrases like “engineers should be more careful” or “we’ll try harder next time” do not lead to real change. Some teams also treat postmortems as a checkbox activity—something to complete quickly and file away, without follow-up or accountability. Others write overly technical postmortems that are hard to understand or so high-level they fail to capture the complexity of what actually happened. In all these cases, the result is the same: the team misses a chance to learn.

Best Practices

A good postmortem is clear, written in a calm tone, and focused on learning. It’s not a blame report but a tool for continuous improvement.

Here are some practices that I use when writing or reviewing postmortems:

Capture everything as it happens

I cannot highlight this enough. Turn it into a habit to screenshot anything that might seem relevant during the incident and keep it in a personal notes file. Copy and paste links from Slack threads, stack traces, reports from your monitoring platform or links to your customer tickets. Include names of people involved or consulted. This will save time and help you reconstruct the timeline later.

Write the postmortem soon after the incident

Details fade quickly. The sooner you write it, the more accurate and useful it will be.

Start with the timeline. Walk through the sequence of events as they unfolded. Include timestamps, actions taken, and observations.

Hint: Be mindful and specific about timezones, distributed systems and worldwide users do not “run on the same time”.

For example, a clear timeline might look like this:

Incident Timeline — 12 March 2025 (all times in UTC)

09:15 — Alert triggered: Payment service response time exceeds 5s threshold

09:18 — Engineering team notified via team channel

09:25 — Initial investigation begins. Logs indicate database queries timing out

09:35 — Customer support reports increase in payment failure complaints

09:40 — DevOps/Backend checks database server metrics: CPU and I/O utilization spiked at 95%

09:45 — Hotfix deployed: temporarily increase database instance size to relieve load (in reality DB instance size change could involve additional downtime)

09:50 — Response time improves; service partially restored

10:05 — Team continues root cause analysis; identifies recent schema migration as possible cause

10:20 — Communication sent to all stakeholders (sales, support, product) explaining the incident and temporary fix

10:30 — Database migration rollback plan drafted in case issues persist

11:00 — Monitoring confirms system stable; customer complaints drop

11:15 — Postmortem assigned and kickoff scheduled for next day

Be blameless, but transparent

Avoid finger-pointing, but don’t hide oversights either.

Don’t criticize, suggest better ways

Focus on proposing improvements, not pointing out flaws. If something was missed or could have been handled better, call it out constructively. That’s the only way to prevent it from repeating. For example, anytime I call out a mistake, oversight or a bad process I try to come up with a proposal on how to improve it.

Involve everyone who made an important contribution

Customer support member who recognized the outage; sales team member who hinted you that something is broken for a large integration customer. Someone saw a strange CPU spike and contributed to your investigation.

Ask “why?” until you get clarity

I love “5 whys” technique. The idea is simple, you start by writing why something happened. Whatever you write as an answer you ask a follow-up why. You repeat this process up to 5 times until you hit the core issue.

Let’s imagine a situation here.

The team had a production outage... Why?

Because team deployed new feature relying on a non-existing environment variable... Why?

Because it was not recognized during the code review or within our automated deployment pipelines... Why?

Because in our code reviews it is unclear who has the ownership of quality assurance when it comes to the infrastructure and integrations. Also, we never planned and don’t have a task to improve our automated pipelines...

See, as we ask why the ambiguity is turning into clarity. Clarity will hopefully turn into actionable items.

Here is a “5 Whys Root Cause Analysis” example.

Problem: Payments were failing during peak hours.

Why 1: Why were payments failing? Because our payment gateway kept timing out.

Why 2: Why was the gateway timing out? Because the database was slammed and slow to respond.

Why 3: Why was the database overloaded? Because a slow query was running without proper indexing.

Why 4: Why was the query unindexed? Because it was added as part of a new report without a performance review.

Why 5: Why wasn’t there a performance review? This is where it gets interesting. The same question can lead to different root causes depending on which thread you pull:

Branch A: Because our code review checklist didn’t include database impact checks. → Root cause: Missing a formal process for database performance reviews before deployment.

Branch B: Because the team was under tight deadlines and skipped parts of the review process to ship faster. → Root cause: Pressure to deliver quickly led to skipping critical quality checks.

Branch C: Because the team lacked clear ownership and accountability for reviewing database changes. → Root cause: Undefined roles and responsibilities caused gaps in the review process.

All three branches are valid. In practice, you might find that more than one root cause contributed to the incident. The point is to keep asking until you reach something structural that you can actually fix.

Always end with follow-up tasks

Lessons that you learned should show you where your team or processes are lacking. Use this to your advantage. For example, your software had partial outage because DB CPU was overloaded, you hot-fixed it by increasing instance size. Create follow-up task to investigate indexes if you haven’t done this already. Write a follow-up task to investigate if it makes sense to introduce additional caching layer.

Use the opportunity to revisit your processes

Let’s say your response time was 1 hour during “work time”. With 20 developers available you expected someone to react in 5 minutes. What happened? Are you lacking visibility, alerts? You might be lacking clear described processes or monitoring alerts ownership. If needed, reflect on this, also on your team’s “definition of done,” quality and security practices, or release criteria. Postmortems can uncover deep gaps worth fixing.

Your Postmortem Cheat Sheet (Free PDF)

Incidents suck. But postmortems? They don’t have to.

They’re your chance to pause, rewind, and learn something that actually makes your system and your team better. A good postmortem turns “what just happened?” into “we will do better, here’s how we avoid this next time”.

I’ve put together a Postmortem Guidebook. A simple, practical PDF you can keep on hand for the next time something breaks in production.

Inside, you’ll find:

• A clean, blameless postmortem template

• A checklist of what to capture during and after the incident

• A step-by-step “5 Whys” worksheet for uncovering root causes

• Sample of what follow-up tasks might look like (with clear acceptance criteria)

• Tips for getting buy-in from leadership and cross-functional teams

Vde Postmortem Cheat Sheet v.1.0

156KB ∙ PDF file

Download

Download the cheat sheet to run better postmortems: why they matter, pitfalls to avoid, what to do during the incident, best practices, a sample timeline, 5 Whys, root-cause branches, and a reusable postmortem template outline.

Download

This is the kind of thing I wish I had earlier in my career, a concrete resource built from real-world experience.

If you liked this post, hit subscribe. I write about engineering practices, postmortems, SaaS delivery, and lessons learned from the messy parts of building software.