repowise mines architectural decisions from eight sources, not just an ADR folder, so the rationale is captured wherever your team recorded it. Each decision carries a verification status and evidence spans, links to the dependency-graph nodes it governs, connects to other decisions by supersession lineage, 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.
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 eight sources, backs each with evidence spans, links them to the graph, and ages them as the code changes, all deterministically with no LLM in the scoring path.
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 deterministic stages: mine → verify → link → track. The result is one decision graph, not a dusty folder.
1. Mine the why from eight sources. Teams record decisions in many places, and most of them are not an ADR folder. repowise reads all of them and unifies them into one layer.
| # | Source | What it captures |
|---|---|---|
| 1 | ADR files | Formal records someone already wrote |
| 2 | CHANGELOGs | Release-note rationale and behavior changes |
| 3 | PR bodies | The argument made when the change landed |
| 4 | Inline markers | # WHY: / # DECISION: / # TRADEOFF: comments, extracted at index time |
| 5 | Git archaeology | Significant commit messages mined into proposed decisions |
| 6 | READMEs | Project-level rationale and constraints |
| 7 | Code comments | In-context reasoning next to the code |
| 8 | LLM over the indexed wiki | Inferred decisions, surfaced as proposed, never as fact |
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 connects to other decisions by supersedes / refines / conflicts_with edges, forming a lineage chain.
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 | supersedes / refines / conflicts_with lineage |
| Track | Governed-file last commit vs decision last update | stale flag, deterministic |
The scoring is deterministic end to end: the same repo produces the same decisions and the same staleness flags every run, with no LLM in the governance 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.
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 its lineage: what it superseded and what refined it. You read the source passage, not a paraphrase.
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 |
|---|---|
| Eight sources mined | ADR files, CHANGELOGs, PR bodies, inline markers, git archaeology, READMEs, code comments, LLM over the indexed wiki |
| 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 |
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 decisionsThen call get_why() for the decision-health dashboard, or get_why("why is auth using JWT?") to ask the codebase directly.
How each role uses this feature
Get deterministic, inspectable governance under AGPL-3.0, self-hosted, with no model in the scoring path, so audits reproduce byte-for-byte. The rationale that usually leaves when people do is retained on-prem and queryable for successor teams.
Recover the architecture context behind any subsystem before an investment call, with git-archaeology fallback when no ADR exists. Every PR carries a deterministic governance signal flagging ungoverned hotspots and contradictory decisions.