How engineering managers use decision logs: the 1:1 documentation use case

A senior engineer two months into a new role asks their manager in a 1:1: "Why are we using Temporal for job orchestration instead of a simpler queue? I've been looking at the codebase and the overhead feels significant for what we're actually doing."

The EM who doesn't have a decision log: "That predates me. I think there was a scaling concern at some point — let me check with Priya from the platform team, she might remember." The engineer leaves the 1:1 with nothing useful. Priya is busy. A follow-up never happens. Two weeks later, the engineer makes architectural choices based on the assumption that the complexity is unintentional overhead rather than an explicit decision with a still-valid reason.

The EM who has a decision log: "There's a record for that. The constraint was a specific failure mode we hit eighteen months ago where job fan-out under load caused memory pressure on the Node processes — three incidents in six weeks. The ADR documents two alternatives evaluated: pg-boss and a custom Redis-backed queue. pg-boss lost on operational coupling; the custom queue lost on the maintenance surface with the team we had at the time. Is the original constraint still valid given the refactor you're planning?"

The engineer leaves that 1:1 with something better than an answer: a framework for evaluating whether the original constraint still applies to their current work, plus the specific conditions under which revisiting the decision would make sense.

This is the concrete case for decision logs from an engineering manager's perspective — not as a documentation artifact, but as a tool that changes the quality of the conversations EMs have with their team.

Why EMs sit at a different intersection

Individual contributors who encounter an unfamiliar constraint ask why it exists. If there's no record, they either investigate (expensive), ask someone (interrupting), or assume (risky). The cost of the missing record lands on the IC's time.

When the same question lands on an EM, the failure mode is different. The "why did we build it this way?" question directed at an EM implies "should we still be building it this way?" The EM is being asked to synthesize historical reasoning with current strategic fit. Without the historical reasoning, the EM can only assess current fit — and often gets it wrong because the constraint that drove the original decision isn't visible.

There's a second failure mode: EMs who hedge. When an EM says "I'm not sure, I'd have to check" consistently in response to historical questions, engineers learn not to ask. The 1:1 becomes a space for current work only — not for the engineering judgment conversations that are the highest-value use of EM time. The new-CTO onboarding problem is the extreme version of this: a new leader arrives who can't answer basic historical questions, and engineers infer that the organization doesn't value reasoning. The EM version happens at smaller scale, in every team that hasn't documented its decision history.

A third failure mode affects the EM personally: answering from memory. An EM who confidently explains the reasoning behind a decision but gets it wrong — misremembers the constraint, conflates two decisions, inverts the timeline — is worse than an EM who acknowledges they don't know. The team builds on the confident-but-wrong explanation. Decision logs don't just help the EM answer questions; they protect the EM from the failure that's most expensive to recover from.

Four EM use cases for a decision log

1. The pre-1:1 brief

An EM who knows what each engineer is currently working on can, in five minutes before a 1:1, pull the two or three historical decisions most relevant to that engineer's current work. This converts the decision log from a passive reference library into an active briefing tool.

The preparation looks like: engineer is working on the notification service refactor → pull the original queue choice ADR and the notification delivery SLA decision. Engineer is evaluating a new observability tool → pull the previous observability stack evaluation and the decision about what to instrument. Engineer is proposing changes to the code review process → pull the process adoption decision that explains why the current review format was chosen and the constraint it was solving.

The 1:1 then starts with context. The EM doesn't wait for the engineer to surface a historical question; the EM surfaces the relevant records first. "I was looking at the decision log before this — there's a record for the queue design that's relevant to what you're working on. The constraint that drove it was X, and it's worth knowing before you finalize the refactor scope." This is the difference between an EM who reacts to questions and an EM who prepares context. The preparation takes five minutes. The value compounds over the engineer's tenure.

2. The onboarding fast-path

New engineers on a team with no decision log spend their first month discovering constraints the hard way — attempting an approach, hitting a wall, asking why the wall is there, getting a partial answer, updating their model, trying the next approach. This is the onboarding use case in its everyday form; the EM-specific version is about what the EM does to accelerate it.

An EM with a decision log can build a curated reading list before the engineer's first day: the 8–12 most consequential decisions in the engineer's domain, ordered by how often they create friction for new engineers who don't know them. Share it in the first-day welcome message. Walk through one record in the first 1:1 — not as a briefing, but as a live demonstration of how the log works and how the EM expects it to be used. "Here's a decision we made about the caching model. The constraint was X. That constraint has changed since then — do you think the decision should be revisited?"

This does two things: it gives the new engineer genuine context faster than any onboarding wiki, and it signals that the EM expects decisions to be revisited when constraints change. That second signal shapes how the engineer uses the log for the rest of their tenure — as a living tool for calibrating current decisions, not as a static archive.

EMs who do this report that first-month "why is it this way?" interruptions decrease significantly. New engineers arrive already knowing the answers to the most common questions. The first-month 1:1s spend more time on current work and less on history. The new engineer becomes useful to the team faster.

3. The performance conversation

Specific feedback requires specific evidence. "Alice showed good architectural judgment this quarter" is a claim every calibration reviewer has to take on faith. "Alice identified that the original observability stack ADR's constraint — limited observability expertise in the team at the time — was no longer valid after two new hires with strong Datadog experience, proposed the migration, documented the decision with concrete alternatives and explicit review triggers, and managed the rollout without service impact" is a claim backed by an artifact that reviewers from other teams can evaluate.

Decision records make invisible judgment visible. This matters disproportionately for engineers doing infrastructure, architecture, and platform work — domains where the output isn't a user-facing feature but a set of decisions that enable other engineers. Their most valuable work is hard to see in commit histories and feature trackers. Decision records are how that work becomes legible to the organization.

The EM's role is to ensure the records exist. Not to write them — the engineer who made the decision should write the record — but to make the ADR in the PR diff a normal expectation. "Before this merges, add a short decision record for the queue choice." Over time, engineers learn that consequential decisions are documented as part of the work, not as an afterthought. The EM who establishes this norm creates a team that generates its own evidence for performance conversations.

The mechanism runs in the other direction too: when an engineer makes a decision that conflicts with an existing documented constraint, the EM can give specific feedback grounded in the record. "The approach in this PR conflicts with the constraint documented in ADR-0031 — the distributed tracing budget set when we were at 40% margin. We're at 62% now, which means the constraint may have changed, but that's a decision that should be made explicitly with an ADR update, not implicitly in a refactor PR." This is more useful to the engineer than "consider the broader context."

4. The promotion case

Promotion briefs at most companies are written once, under time pressure, from memory. The EM writes three paragraphs explaining why the engineer deserves promotion, drawing on recollection of the past six months. The calibration panel reads three paragraphs of claims and has to decide whether to trust them without evidence.

An EM with a decision log can write a different kind of promotion brief. Each claim maps to a decision record. "Demonstrated senior-level architectural judgment" maps to "identified constraint staleness in ADR-0042, proposed the migration with proper documentation, navigated cross-team dependencies correctly." "Showed strong technical leadership" maps to "drafted the first hiring decision records for the team, establishing the candidate-anonymous format we now use across all role prioritization decisions." The promotion brief becomes a structured argument with citations.

This matters more as seniority increases. Staff and principal promotions require demonstrating organizational impact — influence on decisions beyond the engineer's immediate scope. Decision records that show the engineer initiating cross-team constraint conversations, maintaining the team's institutional memory, and creating records that downstream teams reference are concrete evidence for organizational impact claims. Without records, the EM is making assertions. With them, the EM is making an argument.

The practical implication: EMs who want to build promotion cases for their best engineers should start building the evidence trail now, not during promotion cycle. Decision records created during the normal course of engineering work are the evidence. The EM's job is to ensure the records are created.

The EM as decision log curator

Beyond using the decision log in 1:1s and performance conversations, EMs occupy a unique position for maintaining a team's decision history. They have the organizational visibility to identify which undocumented decisions are creating recurring confusion, and the authority to require documentation without creating process overhead.

Three curator responsibilities:

The decision backlog. An EM who notices the same historical question recurring across multiple engineers — "why do we not use TypeScript?" "why is the test suite structured this way?" "why do we not have a staging database that mirrors production?" — has identified an undocumented decision that needs a record. A running list of these recurring questions is the decision backlog: the set of records that need to be written. Prioritize by how often the question comes up and how expensive the wrong assumption is. The EM doesn't write all of these — they assign them to the engineer with the most context, or in the absence of anyone with context, lead a small investigation and write the record based on what can be recovered.

The PR approval loop. PRs that create new architectural constraints should include an ADR in the diff. Not as ceremony — as team protection. An EM who establishes this as a lightweight norm (not a blocking requirement, but an expectation) creates a team that documents decisions at the moment they're made rather than reconstructing them from memory months later. The threshold — what constitutes a "consequential" decision that needs a record — is worth defining explicitly once. A rule like "any decision that would require another engineer to ask why if they encountered it six months from now" is simple enough to apply consistently and doesn't require judgment recalibration on every PR.

The quarterly triage. Once a quarter, run the quarterly decision review pass for the team's decision history. The EM's version serves a different function than an IC's: the EM is looking for decisions that have become stale, constraints that have changed, and records whose review triggers have been reached. The ADR for the queue choice was written when the team had two engineers doing infrastructure work; now there are five. The constraint about operational capacity has changed. Does the decision need to be revisited? The EM is the person with the visibility to make this call — ICs are closer to the work but the EM has the organizational context.

The EM who operates as curator produces a team that doesn't re-litigate the same decisions quarterly. Engineers can focus on current work because the historical reasoning is accessible. New team members onboard faster. ADRs don't go stale because someone is checking review triggers. The documentation habit compounds across quarters.

What the pattern looks like in practice

The change is easiest to see in the structure of 1:1 questions and answers. Two versions of the same conversation:

Without a decision log:

Engineer: "Why do we use Redis for caching instead of a CDN?"
EM: "I think it was a latency thing, or maybe something about cache invalidation. It predates me. I can check with Dan."
Engineer: "No worries, I'll figure it out." (Goes and builds a mental model from code and context, possibly incorrectly.)

With a decision log:

Engineer: "Why do we use Redis for caching instead of a CDN?"
EM: "There's a record for that — the constraint was the cache invalidation model for user-specific data. CDN caches work for static assets, but we had a class of data where invalidation events were unpredictable and fine-grained. The specific failure mode was serving stale user permission data after a role change. Is the data you're working with the same category?"
Engineer: "No, this is static reference data that changes monthly."
EM: "Then the constraint doesn't apply. That's worth a short ADR documenting that this data category doesn't have the same invalidation requirements, so whoever comes after you understands the exception."

The second conversation did several things: gave the engineer the actual reasoning, helped them assess whether it applies to their work, and turned the conversation into a prompt to create a new record. This is the compounding effect of the decision log — every conversation that uses it creates a small amount of additional documentation, because the EM is modeling what good engineering judgment looks like: check the existing record, assess whether it applies, document the exception if it doesn't.

This modeling effect is underrated. Engineers absorb norms from what they see their EM do in 1:1s. An EM who consistently refers to decision records in response to historical questions signals that explicit deliberation is normal, not exceptional. Over time, team members start doing the same — checking the log before asking, creating records before anyone has to ask why a decision was made. The EM doesn't have to mandate this. It propagates from the 1:1 pattern.

AI chat extraction for EM decision logs

EMs are often the least-visible contributor to a team's decision history — and the most valuable extraction target. Engineering decisions by ICs surface in code reviews, PR descriptions, and technical documents. EM decisions surface in AI chat sessions, 1:1 notes, and email threads that disappear.

An EM who exports their AI chat history and runs the WhyChose extractor on three months of sessions typically finds a different category of decisions than IC exports produce. Where IC exports contain architectural, framework, and tooling decisions, EM exports contain: technical debt triage decisions ("we're deferring the auth service rewrite until Q3 because the compliance audit is the binding constraint"), process adoption decisions ("we're moving to weekly retros because the two-week cycle is too slow for the iteration rate right now"), tooling adoption reasoning ("we're adding Datadog APM even though we already have basic metrics because the on-call incident last month showed we have no visibility into slow endpoints"), and resource allocation reasoning behind decisions that look arbitrary from the outside.

These decisions are the context engineers need most. They explain not just how the system is built but how the team is being run. They're almost never documented because EMs aren't typically writing ADRs, and because the deliberation happens in 1:1s and AI chat rather than in documents that get committed to a repository.

The quarterly extraction pass for an EM should produce two outputs: a set of team-visible decision records (architectural, process, tooling decisions where the reasoning is team property) and a set of private records (headcount reasoning, performance calibration context, political context from stakeholder conversations). Hiring decision records are the clearest category of this boundary — candidate comparisons stay in private HR documentation, but role prioritization and design reasoning belong in the team's shared log, candidate-anonymous.

For distributed teams where the EM is in a different timezone from most of their reports, AI chat is often the primary deliberation surface — the EM doesn't have a whiteboard or a rubber-duck colleague available at their local 10am. The extraction pass for a distributed EM's exports is often richer than for co-located EMs precisely because more of the deliberation happened explicitly in writing rather than in hallway conversations that were never captured at all.

The private log and the shared log

Not everything an EM deliberates belongs in the team's shared decision log. The distinction matters enough to state explicitly.

The shared team log — in git, readable by all engineers — contains: architectural decisions explaining current constraints, process adoption decisions (why this retro format, why this on-call rotation design), tooling decisions (why this dependency was added, why this service was extracted), and the "not building this yet" records that explain deliberate deferrals. Any record where the reasoning is team property and a new engineer would behave differently knowing it.

The personal log — private to the EM, in a locked Notion page or similar — contains: headcount reasoning that includes budget or organizational politics, performance calibration decisions about specific individuals, the reasoning behind who gets what opportunity, and any context from stakeholder conversations shared in confidence. The rule of thumb: does this record contain information about specific people's performance, compensation, or organizational standing? If yes, it goes private by default.

The extraction triage step has to apply both filters. When reviewing extraction output, ask two questions: "would a new engineer behave differently knowing this?" (team log candidate) and "does this contain information about specific individuals?" (private by default). Most decisions that meet the first criterion don't meet the second. The ones that do — hiring deliberation where candidates are named, performance management reasoning, political context about individual stakeholders — stay private even if the team-visible version of the same decision gets a shared record.

This distinction is what makes non-technical decision documentation tractable for EMs. The concern that "documenting EM decisions means documenting things about people" is valid — but the answer is not to avoid documentation. The answer is to separate what belongs in the shared log from what belongs in the private log, and apply the candidate-anonymous format to any shared record that touches team structure or hiring.

Where to start

The most tractable first step is the decision backlog: before the next 1:1 cycle, write down the three historical questions that come up most often — the questions engineers ask that require checking with someone or reconstructing from memory. These are the records the team most needs. Write one this week. Not as a project; as a single 15-minute document with the constraint, the alternatives that were evaluated, and the reasoning.

The second step is adding "relevant decision records" as a standing item in 1:1 templates for engineers starting new projects or entering new domains. Pull the relevant records before the meeting. Make the log a routine part of how you prepare for conversations with your team, not a reference document you remember to mention occasionally.

The third step is the extraction pass. Run the WhyChose extractor on the last three months of your AI chat exports. The output will include decisions you made that no one on your team knows the reasoning behind. Triage for team-log candidates — decisions whose reasoning is team property. Write ADRs for the highest-priority ones. The extraction gives you the alternatives and constraint; writing the ADR from that output is a 15-minute synthesis.

For EMs managing engineers who are building the team's ADR practice, the end-to-end documentation guide is the resource to share. For teams starting from scratch, the Markdown ADR template is the fastest starting point — add it to the repo, write the first record, let the practice grow from there. The goal is not a complete historical log by next quarter; it's a practice that ensures every consequential decision made from this point forward gets documented as part of the work, so the next EM who inherits the team inherits the reasoning too.