Skip to main content

Lightweight Peer Review of Architecture Proposals

What This Concept Is​

A lightweight peer review is the default review mode for most architectural changes: not ATAM, not a full risk-driven workshop, just a small group of peers giving a proposal honest scrutiny. It runs in one of two modes:

  • Async. A written proposal (typically a draft ADR or RFC), open comments for 2-5 business days, author responds in writing, final ADR committed with the outcome.
  • Sync. A 30-60 minute meeting with 2-5 participants, a prepared proposal, structured discussion, decision captured in the ADR before the meeting ends.

Most teams run both in succession: an async pass, then a short sync to close what is still open.

Why It Matters Here​

Lightweight peer review is where the volume happens. A team may do one ATAM per year and a full risk-driven review per quarter, but they do a peer review per week. The sustainability of architectural practice depends almost entirely on whether these reviews are useful, or whether they become performative.

Common failure modes:

  • Rubber stamping ("LGTM") because reviewing carefully is costly and invisible.
  • Bikeshedding on formatting and wording while the structural decision goes unchallenged.
  • Review fatigue when the same three people are on every review.

The design of the process determines which failure mode you get.

Concrete Example​

A healthy lightweight review cycle:

Day 0. Author pushes a draft ADR to library/raw/adr/pending/ and opens a PR. Slack notification to #architecture. Reviewers include: one peer from the author's team, one from an affected team, one "architecture guild" rotating reviewer.

Day 0-3. Async comments:

  • "Context is clear. I don't see a consequence for the downstream analytics job - is it affected?"
  • "Considered options lists 2. Were message queues considered and rejected?"
  • "Tradeoff point between availability and cost is not labeled."

Day 3. Author updates the ADR, replies inline to open threads.

Day 4. A single 30-minute sync to resolve the one remaining disagreement: whether the decision is one-way or two-way. Outcome: "Two-way, because we can migrate off by running a secondary consumer for 30 days."

Day 4. PR merged. ADR status: Accepted. Reviewers named in the ADR footer.

The ADR is the artifact. The meeting was a closer, not the review itself.

Common Confusion / Misconception​

"Review = meeting." The meeting is the closing step. The review is mostly async.

"All reviews should be the same size." No. Lightweight is the default. Escalate only when the risk list says so (see Concept 8).

"Approval by count." "Two LGTMs" is not a quality signal if neither reviewer engaged with the tradeoffs. Require that at least one reviewer write something substantive in Consequences or Alternatives.

"Reviewers must be senior." Peer review means peers. A "senior" reviewer can actually reduce quality by letting the author defer instead of defending the reasoning.

How To Use It​

Protocol for the author:

  1. Draft the ADR to the point where Context, Decision, and Consequences are load-bearing.
  2. Open the review with 2-5 named reviewers, at least one from an affected team.
  3. Respond to every comment in writing, even if only to acknowledge.
  4. Before merging, update the ADR to reflect what was learned.

Protocol for the reviewer:

  1. Read Context first. Is the problem real? Are constraints correctly named?
  2. Read Decision. Does it address the Context?
  3. Read Consequences. Is there at least one negative? Is the tradeoff labeled?
  4. Leave at least one substantive comment. If you have none, say "I reviewed and have no concerns" so your presence is recorded, not just your silence.

Check Yourself​

  1. Give one sign that a "lightweight review" has quietly turned into rubber-stamping. What would you change?
  2. What is the smallest acceptable reviewer set for an architectural change in your organization, and why?
  3. Why can "two LGTMs" be a worse signal than "one thoughtful objection"?

Mini Drill or Application​

For a peer's recent ADR:

  • write at least 2 substantive comments on Context or Consequences
  • one comment that proposes an alternative not yet considered
  • one comment that challenges a claim with a specific question

Then reverse roles on one of your own ADRs. Track how the quality of the final document changes.

Read This Only If Stuck​