Deck: The decision was made in the PR. Nobody wrote it down. Six months later, the same question is back in #eng-help.
What this article solves: Architecture decisions get made inside pull requests and never leave them. This post explains how to capture ADRs directly from GitHub PR reviews, what makes them traceable rather than tribal, and how to build a review workflow that doesn't depend on someone remembering to write things up afterward.
Who this is for: Engineering managers and tech leads who are tired of re-explaining the same architectural choices every quarter.
The question that came back
It was 11:14 on a Tuesday morning when Priya, an engineering manager at a mid-size SaaS company, saw the Slack message. A backend engineer on the team had posted in #eng-help: "Why are we using event sourcing for the orders service? Feels heavy for what we're doing."
Priya recognized the question immediately. She had answered it herself, nine months earlier, in the review thread for PR #412. The team had debated three approaches, weighed the audit trail requirements from a compliance conversation in Linear ticket ENG-204, and landed on event sourcing with a clear rationale. The decision was documented in the thread. Forty-seven comments. Buried.
She typed out the answer again. The same answer. The third time in less than a year.
Why PRs hold the real architectural record
The actual architecture decision record for most teams already exists. It lives in the PR description, the inline review comments, and the back-and-forth where someone pushed back and someone else explained the tradeoff. That is where the reasoning happens. That is where the dissent gets aired and resolved.
The problem is that none of it survives in a findable form. A merged PR is effectively an archive. Engineers can search commit history, but they rarely do. New hires don't know what to search for. And the senior engineer who made the call has moved on to the next problem.
ADRs are supposed to solve this. The format is simple: context, decision, consequences. But the manual version requires someone to stop mid-sprint, open a separate document, reconstruct the reasoning they just had in a review thread, and publish it somewhere the team will actually check. That step almost never happens. According to a 2023 survey by the State of DevOps Report, documentation is consistently ranked among the lowest-priority engineering activities, even when teams acknowledge its value.
The gap is not motivation. It is friction.
What a traceable ADR actually needs
An ADR that people trust has three properties that a Confluence page written from memory usually lacks.
It links back to the source. When an engineer reads "we chose Postgres over DynamoDB for the billing schema," they should be able to click through to the PR where that was debated. The thread, the objections, the specific commit that implemented it. Not a summary someone wrote two weeks later.
It captures the context that existed at the time. Decisions look obvious in retrospect. The ADR needs to record what was true when the decision was made: the scale assumptions, the team constraints, the compliance requirement from ENG-204. That context is almost always in the ticket or the PR description, not in anyone's head.
It stays connected to what changed. If the billing service gets refactored six months later, the ADR should reflect that. A static document in a wiki that nobody updates is worse than no document at all. Engineers stop trusting runbooks and decision logs when they find outdated information once. After that, they stop reading them.
This is where the capture problem becomes a maintenance problem. The two are the same problem.
Building a review workflow that produces ADRs automatically
The review workflow is the right place to generate ADRs because that is where the decision actually happens. The goal is to make the artifact a byproduct of the work, not an additional task after it.
A few practices that work in practice:
1. Use PR templates with an ADR prompt. Add a section to your pull request template: "If this PR changes an architectural pattern, describe the decision and alternatives considered." Most engineers will fill this in if the prompt is already there. The blank field does the work.
2. Tag architectural PRs at review time. A label like arch-decision on a PR costs nothing. It creates a filterable record of every PR where an architectural choice was made. That label becomes the index for your ADR log.
3. Link the Linear or Jira ticket. The ticket holds the product context: why the feature existed, what the deadline pressure was, what the compliance requirement triggered the change. A good ADR without that context is half an ADR.
4. Generate the ADR from the PR, not after it. ScopeDocs connects GitHub and Linear to generate source-linked ADRs directly from PR reviews and ticket context, so the decision record exists before anyone has to remember to write one.
5. Review ADRs in architecture discussions. Once a quarter, pull the arch-decision label and walk through what was decided. The review surfaces gaps and keeps the log alive.
In practice
A tech lead merges PR #847, which switches the authentication service from session tokens to JWTs. The PR description explains the decision: stateless auth was needed for the new mobile client, and the team considered but rejected opaque tokens because of the introspection overhead. Linear ticket ENG-519 has the original product requirement.
Three months later, a new engineer joins and asks in #backend why the auth service doesn't use sessions. Instead of a Slack thread or a DM to the tech lead, there is ADR-014: "JWT adoption for stateless auth," linked to PR #847, linked to ENG-519, with a note that the decision was revisited and confirmed when the Android client shipped. The new engineer reads it in four minutes and moves on.
That is the difference between tribal knowledge and traceable knowledge.
Checklist: capturing ADRs from GitHub PRs
- Add an ADR prompt section to your pull request template
- Create an
arch-decisionlabel and apply it at review time - Link every architectural PR to its originating Linear or Jira ticket
- Include alternatives considered in the PR description, not just the chosen approach
- Set a recurring calendar item to review tagged PRs and confirm ADRs are current
- Store ADRs in a location that links back to the source PR, not just the decision text
- When a decision is reversed or updated, update the ADR and link the new PR
The answer should not live in Priya's head
Every time an engineering manager re-answers a question that was already resolved in a PR, the team pays twice: once for the original work, once for the retrieval tax. The reasoning existed. The context existed. It just wasn't captured in a form that outlasts the thread.
ScopeDocs generates source-linked ADRs from PR reviews and ticket context automatically, so the decision record exists before anyone has to ask. Traceable, not tribal. See how it works.