What is an architecture decision record (ADR)?

An ADR is a short, structured record of one architectural choice: its context, the decision made, the alternatives rejected, and the consequences. It answers why is the code structured this way, the one question source code itself never explains and the first thing a team forgets. repowise treats ADRs as a living layer rather than a static folder.

Where does repowise get the why from?

repowise mines decisions from ten sources, not just an ADR folder: ADR files, inline markers in code, commit messages, PR bodies, LLM-mined rationale on high-centrality code, your own agent transcripts (two sources: gated session mining and an opt-in discovery pass), import conventions, and manual or agent-signed entries from the CLI. ADR files, inline markers, conventions and manual entries need no LLM key. CHANGELOGs and READMEs are not mined. The result is one decision layer that captures rationale wherever your team actually recorded it, even when no formal record was ever written.

What if we never wrote any ADRs?

You still get answers. get_why falls back to git archaeology, reconstructing the origin story from significant commits, cross-file references, and live git log history, so a file with zero formal records still returns its most likely rationale instead of an empty result.

How does a decision get marked stale?

Each decision links to the graph nodes it governs. When a governed file's last commit moves forward but the decision's last update does not, repowise flags it stale, a deterministic comparison, so the same repo produces the same staleness flags every time, with no LLM in the path.

get_why is the MCP tool that returns architectural decision rationale in one call: the decision, its verification status, the evidence spans behind it, and its supersession lineage. It supports natural-language search, path-anchored and target-aware lookups, and a no-argument health dashboard, and it is the tool an agent or reviewer calls before a refactor.

How is this different from a folder of ADR markdown?

A folder of ADR markdown only captures the decisions someone remembered to write, and never tells you when one goes stale. repowise reads ten sources, attaches a verification status and evidence spans, links each decision to the graph, tracks staleness as the code changes, connects decisions by lineage, and surfaces governance risk in PR review, a living decision layer instead of a static archive.

Architecture Decision Records & ADRs

By Raghav ChamadiyaUpdated November 2026 · 10 min

repowise architectural decision record with verified-quote evidence

TL;DR

repowise mines architectural decisions from ten sources, not just an ADR folder, so the rationale is captured wherever your team recorded it, including the corrections and conventions your agent enforces during an agent session. Each decision carries a verification status and evidence spans, links to the dependency-graph nodes it governs, records supersession lineage when you name a successor or a commit reverses the change, and is flagged stale automatically when a governed file gets newer commits than the decision. One MCP call, get_why, returns the rationale, lineage, and staleness, and falls back to git archaeology when no ADRs exist, so you never get an empty answer.

Definition

An architecture decision record (ADR) is a short, structured note capturing one architectural choice: the context that forced it, what was decided, the alternatives rejected, and the consequences. repowise mines ADRs from ten sources, backs each with evidence spans, links them to the graph, and ages them as the code changes. ADR files and WHY markers are parsed with no model, commit, PR and comment mining use your configured model, and staleness and governance are computed without one.

repowise decisions view listing candidate records mined from pull requests, each with its quoted source passage and the number of paths it names — Every record carries the passage it came from and the paths it names, and waits for a person to confirm it.

Why do decisions and ADRs matter?

The why behind code is the first thing lost and the most expensive to relearn. Every line tells you what the code does; none of it tells you why it was built that way.

That reasoning lives in the original author's head, in a closed PR thread, in a message nobody can find. When the person who knew it leaves, the knowledge usually leaves with them.

The next refactor relearns the constraint the hard way, usually through an incident.
A folder of markdown ADRs only captures what someone remembered to write, and never tells you when one goes stale.
No wiki or code-quality tool in the category captures the why at all, so this is pure white space.

How do decisions and ADRs work?

repowise turns scattered rationale into a queryable decision layer in four stages: mine → verify → link → track. The result is one decision graph, not a dusty folder.

1. Mine the why from ten sources. Teams record decisions in many places, and most of them are not an ADR folder, including the corrections and conventions an agent learns mid-session. repowise reads all of them and unifies them into one layer.

#	Source	What it captures	Needs an LLM key
1	ADR files	Formal records someone already wrote (Nygard and MADR headings, YAML frontmatter)	No
2	Inline markers	`# WHY:` / `# DECISION:` / `# TRADEOFF:` comments, extracted at index time	No
3	Git archaeology	Commit messages with a decision verb (migrate, replace, adopt, deprecate)	Yes
4	PR bodies	The argument made when the change landed	Yes
5	Comment archaeology	Rationale prose on high-centrality code, verified against the literal comment	Yes
6	Agent sessions	Corrections and conventions you enforce in an agent session, after a deterministic gate filters one-off nudges (off by default)	No for the gate
7	Session discovery	One broad model pass over new transcript prose per update (off by default)	Yes
8	Conventions	A wrapper most files reach a library through, read from import edges (off by default)	No
9	Manual entry	`repowise decision add` and the dashboard form	No
10	Agent entry	`repowise decision add --agent <slug>`, signed by the coding agent	No

2. Verify with evidence. Every decision carries a status, verified / fuzzy / unverified, plus evidence spans: the exact passages in ADRs, commits, PR bodies, or comments that back it. Fuzzy and unverified records are surfaced honestly, never invented.

3. Link to the graph. Each decision ties to the graph nodes it governs (the files and modules) and records lineage only from an explicit repowise decision deprecate ID --superseded-by ID2 or from a commit that reverses a change. repowise does not infer supersedes, refines or conflicts_with edges between decisions.

4. Track staleness. A decision is only as current as the code it governs. If a governed file's last commit moves forward but the decision's last update does not, repowise marks it stale.

Stage	Mechanism	Output
Verify	Status + literal evidence spans from the source	`verified` / `fuzzy` / `unverified`
Link	Decision tied to governed graph nodes and other decisions	Explicit lineage: `--superseded-by` or a commit reversal
Track	Governed-file last commit vs decision last update	`stale` flag, deterministic

Mining ADR files and WHY markers needs no model. Mining commits, PR bodies and code comments uses your configured model and is skipped with a stated reason when none is set. Verification, staleness and governance are deterministic: the same repo produces the same staleness flags and the same PR governance signal every run, with no model in that path.

How do decisions and ADRs help you?

Four outcomes, each tied to a moment where the why usually goes missing.

Onboarding

Call get_why() with no arguments for a guided tour of the codebase's recorded reasoning, the dashboard a new hire wishes existed. They read why before they touch what, instead of reverse-engineering intent from the diff.

Safe refactors

Before an architectural change, get_why("src/auth/service.py") returns every decision governing that path and its origin story, so you find out a constraint exists before you violate it, not in code review.

Agent grounding

Decisions are linked to graph nodes, so when your AI agent edits a file, get_why surfaces the governing decisions automatically. The agent reasons before it refactors instead of confidently undoing a deliberate trade-off.

repowise chat answering how a file code health score is calculated, step by step, from the indexed repository — The same index answers questions in chat, here how a file's health score is calculated.

Governance

The decision-health dashboard surfaces stale decisions, proposed-awaiting-review records, and ungoverned hotspots, high-churn files with no decision on file. On a PR, the Repowise PR bot flags ungoverned hotspots and contradictory decisions deterministically, with no LLM in the scoring path.

Guardrail: this is a deterministic governance layer, not an LLM judge. The same diff scores the same every time, with zero model in the scoring path.

Walkthrough: browse decisions and catch a stale one

Step 1: Browse the decision layer. Open the decisions view to see every mined record, formal ADRs alongside decisions reconstructed from commits, PRs, and inline markers. Each row shows its verification status and the files it governs.

Step 2: Open a decision and read its proof. A verified record shows the evidence span, the literal commit or PR line that supports it, plus, when one was recorded, the decision that superseded it. You read the source passage, not a paraphrase.

repowise decision record with its status, a verified source quote, context, decision and rationale, and the module and file it governs — A verified decision quotes the exact source passage, so you read the proof, not a summary.

Step 3: Catch the stale decision. The health dashboard flags decisions whose governed files have newer commits than the decision's last update, the moment the why starts drifting from the what. Live counts shift per index, so read the dashboard's active / stale / proposed / ungoverned-hotspot rollups rather than a fixed number.

Proof: a living decision layer, not a static archive

Each claim below stands alone and is reproducible on your own repo: every heuristic is open source under AGPL-3.0.

Claim	Detail
Ten sources	ADR files, inline markers, git archaeology, PR bodies, comment archaeology, agent sessions, session discovery, conventions, manual and agent entries
Zero LLM in the governance path	The PR governance signal is deterministic; the same diff scores the same every time
Evidence-backed	Every decision carries a verification status (verified / fuzzy / unverified) and evidence spans pointing at the source passage
Linked and aged	Each decision ties to the graph nodes it governs and is flagged stale when those files get newer commits
Never empty	When no ADRs exist, `get_why` falls back to git archaeology: significant commits, cross-file references, and live `git log --follow` / `--grep`
Open source, reproducible	Released under AGPL-3.0 and self-hostable; every step of mine, verify, link, and track is inspectable
White space	No competitor in the wiki or code-quality categories tracks architectural decisions at all

ADR tools: write records with any of them

ADR tools help a team write, publish and browse records. repowise reads what they produce, so you keep the tool you already use.

Tool	What it does
adr-tools	Command-line tool by Nat Pryce. `adr init` starts a log in `doc/adr`, `adr new` adds a numbered record, and `adr new -s 9` supersedes record 9
MADR	Markdown Architectural Decision Records: a template (4.0.0) with context, considered options and decision outcome, plus optional front matter for status and decision makers
Log4brains	CLI that creates ADRs from the terminal (MADR by default) and builds them into a static site for GitHub Pages, GitLab Pages or S3
ADR Manager	Web app that connects to GitHub and edits the MADR files in a repo's `docs/adr` folder
Structurizr	The `!adrs` DSL keyword attaches decision records to a workspace, system or container, with importers for adr-tools, MADR and Log4brains files
Backstage ADR plugin	Shows a component's ADRs on an entity page tab, found through the `backstage.io/adr-location` annotation, and indexes them into Backstage search. Parses MADR by default
ADR template collection	Joel Parker Henderson's repository of ADR templates (Nygard, MADR, Tyree and Akerman) and worked examples

These tools manage the records someone wrote. repowise starts from those records and adds the decisions nobody filed as an ADR:

ADR files. Read from docs/adr/, doc/adr/, docs/decisions/, adr/ and similar folders. Nygard and MADR headings and YAML front matter are parsed directly, with no LLM key. A committed ADR whose status is accepted and that names what it governs becomes an accepted decision; a draft lands as a candidate.
WHY comments. WHY:, DECISION:, TRADEOFF:, RATIONALE: and REJECTED: markers in any comment syntax, also with no LLM key.
Commits. Messages that carry a decision verb such as migrate, switch to, replace, adopt or deprecate.
Pull requests. Squash-merge and PR commit bodies that read like a PR description.

Commit and PR mining use your configured model. Every candidate is checked against its verbatim source quote, and the same decision found in an ADR and a PR becomes one record with both as evidence. When your agent edits a governed file, get_why hands it the decision.

Try it on your repo

Keep the why with your codebase: every step of how decisions are mined, verified, linked, and aged is inspectable and runs locally.

pip install repowise
repowise init                          # mine, verify, link, and age decisions

Then call get_why() for the decision-health dashboard, or get_why("why is auth using JWT?") to ask the codebase directly.

For your role

How each role uses this feature