Technical Leadership Fundamentals
A single engineer choosing between Vec<T> and a HashMap<K, V> needs nothing more than judgment and a few minutes of thought. A team of eight choosing between Axum and Actix-web, or between a modular monolith and five microservices, needs something more than one person's judgment, even if that person is right.
This page is about that gap. It is the conceptual anchor for the Tech Leadership section: the mental model behind why teams adopt structured decision-making frameworks such as Architecture Decision Records (ADRs) and design reviews, and what those frameworks are actually solving for. Technical Decision-Making and the other pages in this section show the mechanics in practice. This page explains why the mechanics exist at all.
Summary
- As a team grows, the bottleneck shifts from "can someone make a good technical decision" to "can the team reliably reproduce, communicate, and revisit that decision without the original person in the room" - structured frameworks exist to close that gap.
- Insight: Undocumented decisions live in one person's head, get re-litigated every time that person is unavailable, and quietly rot as context changes, which costs a growing team far more time than the framework itself.
- Key Concepts: decision legibility, reversibility, Architecture Decision Record (ADR), design review, disagree and commit, revisit trigger.
- When to Use: Adopting a framework matters most for cross-team or hard-to-reverse choices, new hires needing to understand "why is it built this way," recurring disagreements about the same trade-off, and any decision a postmortem might one day ask about.
- Limitations/Trade-offs: Every framework adds ceremony, and ceremony applied to a decision that did not need it is pure overhead - the skill is calibrating which decisions deserve the weight.
- Related Topics: ranked decision-making, RFC-style design review, disagreement resolution, decision governance for spikes and dependencies.
Foundations
A technical decision, at its smallest scale, is just a choice with a reason behind it. One developer working alone can hold the reason in their head indefinitely, because they are the only person who ever needs to retrieve it.
That stops being true the moment a second person depends on the outcome. Now the reason has to survive being retold, possibly weeks or months later, possibly by someone who was not there when it was made. Decision legibility is the property of a decision being reconstructable by someone who was not in the room: not just what was chosen, but what else was considered and why it lost.
Legibility is not the same thing as documentation for its own sake. A decision can be written down and still be illegible if it records only the outcome ("we use Axum") without the reasoning that made Axum the right call for this team at this moment. The reasoning is what lets a future reader tell the difference between "this is still true" and "this was true in 2024, before we had three more services."
A useful analogy is a company's org chart versus a founder's memory. A two-person startup runs fine on one person remembering every customer promise and architectural shortcut. A fifty-person company running the same way is not lean, it is fragile: knowledge lives in exactly one head, and that head becomes a single point of failure for decisions nobody else can explain. Structured decision frameworks are the org chart for technical judgment: a way of making sure the reasoning survives the person who first had it.
Two frameworks recur across mature engineering organizations, and both appear elsewhere in this section. A design review (often written as an RFC) is the forum where a proposed decision gets stress-tested before it is final. An Architecture Decision Record (ADR) is the artifact that records what was ultimately decided, once a design review or a smaller conversation reaches a conclusion. Neither replaces judgment. Both exist to carry judgment further than the person who exercised it.
Mechanics & Interactions
The two frameworks are not competitors, they are stages of the same pipeline. A design review is where options get generated and challenged; an ADR is where the surviving option gets recorded, along with the ones that lost and why. Skipping the review and jumping straight to an ADR produces a well-formatted record of a decision nobody stress-tested. Running reviews without ever writing an ADR produces the opposite failure: good discussions that evaporate the moment the meeting ends.
The pipeline has a shape worth naming, because each stage catches a specific failure mode:
Frame options -> Review / challenge -> Decide (named owner) -> Record (ADR) -> Revisit (trigger fires)
| | | | |
avoids avoids avoids avoids avoids
single-option groupthink / endless oral-tradition stale decisions
tunnel vision unheard risk consensus-seeking drift treated as permanentTwo mechanics matter more than the diagram shows. First, framing options is deliberately separated from advocating for one - a design review that opens with "I think we should do X" collapses the exploration stage before it starts, because reviewers anchor on the first proposal instead of evaluating alternatives on their own terms. Second, a decision needs a named decision maker, not an unweighted popularity vote. Disagree and commit is the practice of a decision maker choosing after hearing dissent, recording that dissent in the ADR's consequences, and the whole team executing the choice anyway rather than re-litigating it in every subsequent meeting.
enum DecisionStatus {
Proposed,
Accepted,
Superseded { by: u32 }, // ADR number that replaces this one
}That enum is a useful mental model even outside Rust code: a decision framework forces every decision into one of a small number of named, exhaustive states, the same way match forces every enum variant to be handled. A decision is never quietly "sort of still current" - it is Proposed, Accepted, or explicitly Superseded, and the framework's job is to make that state visible instead of ambient.
The most common reasoning pitfall is treating reversibility as binary. Framework weight should scale with how expensive a decision is to undo, not with how technically interesting it is. A dependency swap behind a stable internal interface is cheap to reverse and rarely needs a full design review; a public API shape, a database schema, or a workspace split is expensive to reverse and benefits from exactly the ceremony a smaller decision would not.
Advanced Considerations & Applications
At small scale, a lightweight version of this pipeline - a two-line ticket comment explaining a choice - is often enough. Insisting on a full ADR for every dependency bump trains a team to stop trusting the process. At larger scale, across multiple squads sharing a workspace, the same pipeline needs an index: a discoverable list of what has been decided, or the framework becomes as illegible as the tribal knowledge it replaced.
Revisit triggers are the mechanism that keeps a framework honest over time. A decision accepted for a six-engineer team at 200 requests per second is not wrong at thirty engineers and 20,000 requests per second, but it is no longer guaranteed to be right. A good ADR names the condition that should prompt a second look - traffic multiplier, team-size threshold, a repeated SLO miss - instead of leaving "revisit later" implicit. Without a named trigger, decisions persist by default long after the conditions that justified them have changed.
The security and observability angle shows up in which decisions get escalated. Choices touching unsafe blocks, FFI boundaries, authentication, or a new external dependency are exactly where an informal Slack thread is the wrong artifact - the cost of an unreviewed mistake there outweighs the cost of the review.
| Approach | Strength | Weakness | Best Fit |
|---|---|---|---|
| Tribal knowledge (no framework) | Zero overhead, fastest to decide | Illegible to anyone not present; decays as people leave | Solo projects, throwaway prototypes |
| Lightweight ADR only | Cheap to write; preserves reasoning | No stress-testing before the decision is recorded | Reversible, single-owner, low-blast-radius choices |
| Design review + ADR pipeline | Catches risks before commitment; leaves a legible trail | Meeting overhead; can be slow if scoped too broadly | Cross-team or hard-to-reverse decisions |
| Formal architecture review board | Strong governance for regulated or high-risk domains | Heavy process cost; bottlenecks fast-moving teams | Large orgs, compliance-driven or safety-critical systems |
The pipeline also has to interact with how a team already works, not replace it. Pull-request review, pairing, and everyday code review make small technical decisions constantly; this framework is reserved for the subset expensive enough that forgetting why they were made would genuinely hurt.
Common Misconceptions
- "ADRs are just documentation." An ADR is a decision-making artifact, not a write-up produced after the fact - the discipline of writing "what did we consider and reject" is what makes the eventual choice legible, and skipping straight to documenting only the outcome loses exactly the part future readers need.
- "Design reviews slow everything down." They add real overhead, but that overhead is meant to apply only to decisions expensive to reverse - the misconception comes from applying full review ceremony to every change, which is a calibration failure, not a flaw in the framework itself.
- "The most senior person's opinion is the decision." A framework's value is in separating framing options from committing to one - seniority can break a tie, but a good process still surfaces alternatives a senior engineer's first instinct would have skipped.
- "Once a decision is Accepted, it's permanent." Accepted means "current," not "final" - a revisit trigger is what keeps a decision provisional on purpose without making the team re-debate it every week.
- "Process like this is only for big companies." Small teams benefit from a lighter version of the same shape, not from skipping it entirely - the difference at scale is how much ceremony each stage needs, not whether the stages exist.
FAQs
What's the actual difference between a design review and an ADR?
A design review is a process, usually a meeting or an async comment period, where a proposed decision gets challenged before it is final. An ADR is the artifact produced once a decision - reached through a design review or a smaller conversation - needs to be recorded. Reviews produce decisions; ADRs preserve them.
Why can't a good tech lead just make these calls without the overhead?
A good tech lead can absolutely make the call. The overhead is not about improving the quality of a single decision, it's about making that decision reproducible by people who were not in the room, including the tech lead's own future self months later.
How does a "named decision maker" actually work in practice?
One person (often the tech lead or an EM) is explicitly responsible for closing a decision after options are framed and reviewed, rather than requiring full consensus. That person listens to dissent, records it in the decision's consequences, and the team executes even where not everyone agreed - this is what "disagree and commit" means operationally.
How do revisit triggers keep a decision framework from producing stale, outdated decisions?
A revisit trigger is a specific, named condition written into the decision at the time it's accepted - a traffic multiplier, a team-size threshold, a repeated SLO miss - that flags when the decision should be re-examined. Without one, decisions tend to persist indefinitely simply because no one owns the job of questioning them once conditions change.
When is it overkill to write an ADR or run a design review?
For decisions that are cheap to reverse, affect one owner, and have low blast radius - a local refactor, an internal-only dependency swap behind a stable interface - the overhead usually costs more than the risk it prevents. A one-line ticket comment is often sufficient there.
What makes a decision "legible" versus just documented?
Legibility means a reader who wasn't present can reconstruct not just the outcome, but the reasoning and the rejected alternatives. A record that states only "we chose X" without why X won and what lost is documented but not legible - it can't tell a future reader whether the reasoning still holds.
Does adopting these frameworks slow a team down?
It adds real, visible overhead to the specific decisions it's applied to. The trade-off is time saved later: re-litigating the same undocumented decision repeatedly, or onboarding new engineers with no record of why the system looks the way it does, both cost more time in aggregate than the review would have.
Why separate "framing options" from "advocating for one"?
Opening a discussion with a preferred answer anchors everyone else's thinking before alternatives get a fair hearing. Listing options neutrally first, then debating them, surfaces risks and alternatives that groupthink around an early favorite would otherwise suppress.
What's the smallest version of this framework a two- or three-person team should use?
A short comment in the ticket or PR explaining the choice and the rejected alternative is often enough - the point is preserving reasoning, not adopting heavyweight ceremony. The framework's shape (frame, review, decide, record, revisit) still applies; only the formality of each stage shrinks.
Who should be allowed to override a decision once it's Accepted?
Generally the same category of decision maker who accepted it, or a broader review for cross-team consequences, and always by creating a new record that explicitly supersedes the old one rather than editing it in place. Silent edits erase the history that made the original decision legible.
How is this different from just having good code review culture?
Code review catches small, local technical decisions as they happen, embedded in a specific pull request. This framework is reserved for a smaller set of decisions - cross-team, hard to reverse, or likely to be questioned later - that are too consequential or too broad in scope for a single PR thread to carry the reasoning.
What's the biggest sign a team needs to adopt this kind of framework?
The same architectural debate recurring every few months with no memory of the last time it was settled is the clearest signal - it means the reasoning behind the last decision never survived past the meeting where it was made.
Related
- Technical Decision-Making - the ranked-options mechanics this page's model is built on
- Architecture Decision Records (ADRs) - the recording half of the pipeline, in depth
- Running Design Reviews - the review half of the pipeline, in depth
- Handling Technical Disagreements - what happens when framing and reviewing still leaves conflict
- Spikes, PoCs & Adopting New Crates - de-risking an option before it enters the framework
Stack versions: This page is conceptual and not tied to a specific stack version.