Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Architectural Decisions
Repowise finds the reasoning your team already wrote down (ADR files, # WHY:
comments, commit messages, pull request bodies) and, if you opt in, the choices
you make in coding-agent sessions. Each record is tied to the files it governs,
backed by a verbatim quote, checked for staleness against the code, and handed
to your agent when it is about to edit those files.
It does not decide anything for you. Extraction only proposes candidates; a person, a signed agent, or a committed ADR makes one a decision that governs.
Cost: capture runs inside repowise init and repowise update. ADR files,
inline markers, manual entry and conventions need no LLM key. Commit, pull
request and comment mining need a model and are skipped with a stated reason
when no provider is configured. Delivery to agents is a local SQLite lookup
with no network.
Quick start
repowise init # capture runs as part of indexing
repowise decision candidates # what is awaiting review
repowise decision confirm a1b2c3d4 # accept one; this is what makes it govern
repowise decision list # everything, decisions and candidates
repowise decision health # stale, unscoped, ungoverned hotspots
repowise decision export # write accepted ones to .repowise/decisions.yaml
To record one yourself, see How to add one; agents ask with
get_why. The dashboard's Decisions page of a repository lists records by
review lane and lets you accept or dismiss candidates.
What a decision record is
Repowise keeps three things apart:
| What it is | Can a machine create it? | Does it govern? | |
|---|---|---|---|
| Episode | An evidenced event: a transcript span, a commit, a structural change | Yes | No |
| Candidate | A durable choice inferred from that evidence. Stored with status proposed |
Yes | No |
| Decision | A constraint someone accepted. Stored with status active |
No, except a committed ADR | Yes |
Only decisions reach your agent as rules, count toward path alignment, or land
in the generated CLAUDE.md. Recurrence, confidence and a model's verdict make
a candidate worth reading. None of them accepts it.
A record carries a title, the decision, context, rationale, rejected alternatives, consequences, tags, the files or modules it governs (its scope), its source, a confidence, a staleness score, and one or more evidence rows (file and line, or commit, plus the quote).
Acceptance is a recorded event, not a status flag. It carries a reason, a
scope, an evidence reference and who signed it, and Repowise refuses to store
an acceptance that is missing any of those. A record with no decision text, mined
or typed, is refused too; confirm --decision supplies it:
$ repowise decision confirm 4b6ddc58
Cannot accept 4b6ddc58: no scope: name the files or modules it governs
Supply the missing parts with --decision, --reason, --scope or --evidence.
$ repowise decision confirm 4b6ddc58 --scope src/ingestion
Decision 4b6ddc58 accepted (governing)
The acceptance log is append-only. Accepting, reaffirming, merging,
withdrawing, superseding, deprecating and dismissing each add a row, so the
history of who granted and withdrew authority survives. Only accepted
decisions have rows: dismissing or deprecating a candidate records its signer
(dismissed_by, dismissed_by_kind, dismissed_session) on the candidate's
review row instead. A deprecated row withdraws authority like dismissed
and is counted as deprecated by decision health.
Where decisions come from
| Source | Key | Reads | Needs an LLM key | On by default |
|---|---|---|---|---|
| ADR files | adr |
adr/, adrs/, docs/adr/, docs/adrs/, docs/decisions/, decisions/, architecture/, doc/adr/ (up to 60 files); Nygard and MADR headings, YAML frontmatter |
No (parsed directly; a model stage is optional) | Yes |
| Inline markers | inline_marker |
WHY:, DECISION:, TRADEOFF:, ADR:, RATIONALE:, REJECTED: in any comment syntax. Uppercase only, like TODO: |
No (a model stage is optional) | Yes |
| Commits | git_archaeology |
Commit messages that carry a decision verb (migrate, switch to, replace, adopt, deprecate, drop, ...) | Yes | Yes |
| Pull request bodies | pr |
Squash-merge and PR commit bodies that read like a PR description | Yes | Yes |
| Code comments | comment |
Rationale prose in comments on the most central files | Yes | Yes |
| Agent sessions | session |
Your local coding-agent transcripts | No for the gates; the structuring step uses a model when one is configured | No |
| Session discovery | session_discovery |
One broad model pass over new transcript prose per update | Yes | No |
| Conventions | conventions |
Import edges: a wrapper most files reach a library through | No | No |
| Manual entry | cli |
repowise decision add, the dashboard form |
No | Always |
A committed ADR whose status says accepted or approved and that names what
it governs accepts its own decision, with the file recorded as the accepter. It
is the only non-human acceptance, and it only applies to a file git tracks. A
draft, an uncommitted file, or one with no status lands as a candidate.
The same decision found by two sources becomes one record with two evidence rows. Headline fields come from the more authoritative source; the other is kept as corroboration and raises confidence.
Lifecycle
Stored status is one of proposed (a candidate), active (accepted),
deprecated, superseded or dismissed. An accepted decision also has a
currency, which says whether it still describes the code:
| Currency | Meaning | Still governs? |
|---|---|---|
active |
Accepted, and still describes the code | Yes |
needs_review |
Accepted, but at least half of the files it names have changed since it was recorded or last accepted | Yes |
uncheckable |
Accepted, but names no file or module, so it cannot be checked against the code | Agents editing a file are not given it |
stale |
Accepted, but every file it names is gone at HEAD (renames followed) | No |
superseded |
Replaced by a later decision the person named | No |
dismissed |
Authority withdrawn; kept for history | No |
active, needs_review, uncheckable and stale are derived from the code
on every read. superseded and dismissed are set by a person.
- Staleness score: each record carries
staleness_scorebetween 0 and 1, the fraction of its governed files committed to since the decision was recorded. A record written before its evidence commits landed counts from the commit (or squash) that landed them. A later accept, reaffirm or merge by a person or agent moves the start to that moment, so reviewing a decision clearsneeds_reviewat once. A file the repository does not track counts as changed. At 0.5 or above an accepted decision isneeds_review, and that is whatdecision list --stale-onlyand the health summary count as stale. A record that names no file scores 0.0 and is counted separately as unscoped.repowise decision showandget_whyon a path also ask git directly for one record and print what changed. - Sticky review: a dismissed candidate is kept as a tombstone, so re-indexing
never proposes it again. Retired candidates (dismissed, deprecated,
superseded) stay out of the candidate queue and the lane totals. A later extraction never walks an accepted decision
back to
proposed. - Supersession:
repowise decision deprecate ID --superseded-by ID2records the successor, andrepowise updatemarks a decision that a new commit reversed. These are the only sources of lineage; Repowise does not infersupersedesorconflicts_withedges from text similarity (why).
Reviewing candidates
decision confirm accepts, dismiss tombstones, deprecate retires, and
merge, dedupe and split tidy candidates (Reference). In a
batch, each id goes through the same acceptance check and is applied on its
own, so one refusal does not stop the rest.
The Decisions page splits records into five lanes that do not overlap. Its
Accept goes through the same check as decision confirm, so a candidate
missing a reason, scope or evidence has Accept disabled with the gap named.
| Lane | What is in it |
|---|---|
| Active | Accepted and still describes the code. These are the rules. |
| Candidates | Never accepted. Governs nothing. Ordered so the ones that can be accepted as-is come first. |
| Needs review | Accepted, but the files it names have moved. Still binds. |
| Uncheckable | Accepted, but names no file or module. |
| History | Accepted, then withdrawn, superseded or dismissed. |
How to add one
repowise decision add # guided prompts
repowise decision add --title T --decision D [--affects PATH ...] # no prompts
| Flag | Meaning |
|---|---|
--title, --decision |
Both together switch to non-interactive mode and print the new id |
--context, --rationale |
Why it was needed, why this choice |
--alternative, --consequence |
A rejected alternative; a tradeoff accepted. Repeatable |
--affects, --tag |
A file or module it governs; a tag. Repeatable |
--evidence-commit |
A commit the decision was made in. Repeatable |
--kind |
architectural (default) or agreement |
--agent, --session |
Record it as this agent's (source agent), with its session id. Needs the flags |
--format json |
Machine-readable output with the full id |
What gets stored depends on how you add it:
- Guided prompts record an acceptance, signed by you. An architectural decision that names no files is kept as a candidate, because it cannot be checked against the code.
- Flags (
--titleand--decision) store a candidate (proposed). A person answering the prompts has reviewed the decision; a script or agent inferring one has not. Promote it withrepowise decision confirm ID. - After a commit whose message states a choice, a hook asks the agent once a
session to record it with
decision add. On by default;repowise decision config capture-prompt --offturns it off. --agent SLUGmarks a candidate an agent reasoned out itself. Unlike a person's manual entry, accepting it needs an evidence reference (--evidence-commiton add, or--evidenceon confirm).--kind agreementrecords a rule about how the work is done ("never push without review"). It governs the whole repository, needs no files, and reaches an agent at session start.
Governance
Who may accept
Each acceptance records who signed it and what kind of signer: person,
agent, or import (the committed manifest or an ADR). The person defaults to
git config user.name; --as records a different identity. An agent reviews
and accepts by signing as itself, for example
decision confirm ID --agent claude_code --session "$SESSION_ID"; merge,
dismiss and deprecate take --agent too. The acceptance contract is the
same for every signer, and an agent's own record also needs evidence. The
dashboard badges any authority record a person did not sign, the generated
CLAUDE.md marks it [accepted by SLUG, not a person], and
decision show --format json returns the signature.
repowise decision config agent-acceptance --off keeps granting to people:
agents still propose and withdraw.
The tracked manifest
Accepted decisions belong to the repository, so they live in a file you
commit. repowise decision export writes the store to
.repowise/decisions.yaml and repowise decision import reads it back. Each
entry holds the id, title, decision, reason, scope, currency, source, and when
and by whom it was accepted. On import the file wins, and candidates and
episodes stay out of it. Format, merge and ordering rules:
architecture/decisions.md.
Capture policy
Every source can be switched, and so can the model: decision config preset
picks a preset, decision source set SRC --off (or --no-llm to keep a
source's parse and skip its model stage) switches one source, and
decision llm --off stops every decision extraction model call.
decision config show prints the resolved policy, with reasons.
| Preset | What it runs |
|---|---|
default |
What a config with no decisions: block gets: ADR, markers, commits, PR bodies, comments, with the model on. Sessions, discovery and conventions off |
off |
No capture. Manual entry still works |
local_only |
ADR, markers and sessions, deterministic only. No model calls |
balanced |
default minus comments, plus sessions and session discovery |
full |
Every source, model on |
Switching a source off stops new capture; it deletes nothing, and accepted
decisions keep governing. With the model off or no provider configured, model
stages report skipped, never failed. Full block reference:
CONFIG.md.
repowise decision status reports what capture did: the policy, each source
and why it did or did not run, review lanes, backlog age, staging queues and
model spend on decision extraction.
How agents get them
Through hooks, without asking (details in HOOKS.md):
- Session start: Repowise injects the decisions most relevant to the session's likely working set under a hard ~400-token cap. Candidates come in a separate, labelled section with its own small budget. If nothing is relevant enough, nothing is injected. How the working set is scored: architecture/decisions.md.
- Edit time: when the agent edits a file an accepted decision governs, it gets a one-line notice with the rationale, once per session per decision.
Through MCP, get_why picks its mode from the call shape:
| Call | Returns |
|---|---|
get_why() |
Governance health: counts, stale decisions, candidates awaiting review, ungoverned hotspots |
get_why(query="src/auth/jwt.py") |
Three lanes that never mix: decisions (accepted, governing; with lineage when there is one), candidates (nobody accepted them), history (superseded or withdrawn). Plus an origin story from git and an alignment read on the first lane |
get_why(query="why is caching split?", targets=[...]) |
Ranked decision search, optionally anchored to paths |
get_why(query=..., repo="all") |
The same search across every workspace repo |
Only the decisions lane is a rule. When no decision covers a path, get_why
falls back to git history for that file, then to a rationale comment in the
source. Full parameters: MCP_TOOLS.md.
Accepted decisions also appear in the generated CLAUDE.md, get_overview,
get_context, and as the governance_risk flag in get_risk. A candidate
never raises governance_risk, and reaches get_answer labelled candidate.
Code health reports ungoverned_hotspot, stale_governance and
contradictory_decision findings (CODE_HEALTH.md).
Accuracy and limits
- Every stored field is checked against the verbatim source span. A field that is not grounded is cleared; a candidate with no grounded field is rejected.
- Confidence is capped at 0.99 and rises with source authority and independent corroboration. It is a ranking aid, not a probability.
- The
sessionsource ships off: of 139 records here, none has a context and 115 have no rationale either (measurement). - Lineage comes only from explicit
--superseded-byand commit reversals. - Staleness measures whether governed files changed, not whether the decision is still true.
- Commit, PR and comment mining need a model; without one, only ADRs, markers, conventions, sessions (gates only) and manual entry produce records.
Reference
Every subcommand takes an optional trailing PATH, --format json, and
accepts an 8-character id prefix. Lifecycle commands exit non-zero on an
unknown id.
| Command | What it does |
|---|---|
decision add |
Record a decision (see How to add one) |
decision list |
Table of records. --status, --source, --proposed, --stale-only |
decision show ID |
Full record with evidence and signature |
decision candidates |
What awaits review, and why each was raised |
decision confirm ID... |
Accept. --reason, --scope, --evidence fill gaps; --preview writes nothing |
decision dismiss ID... |
Tombstone. On an accepted decision this also withdraws its authority |
decision deprecate ID --superseded-by ID2 |
Retire with an explicit successor |
decision merge ID INTO_ID |
Fold a candidate into an accepted decision. The old id keeps resolving |
decision dedupe |
Fold duplicate candidates in one sweep. Dry run until --apply |
decision split ID |
Flag a candidate as bundling two choices. Never splits it for you |
decision export / import |
Round-trip .repowise/decisions.yaml |
decision migrate |
Classify records from older stores. Dry run unless --apply |
decision health |
Counts, stale records, ungoverned hotspots |
decision status |
What capture did, per source |
decision config show / preset / discovery / agent-acceptance / capture-prompt |
Capture policy |
decision source list / set SRC --on/--off [--llm/--no-llm] |
Per-source switches |
decision llm --on/--off |
Master switch for model calls |
Full flags: CLI_REFERENCE.md.
See also
- architecture/decisions.md: source internals, evidence check, confidence, session mining, manifest rules, hook scoring.
- INTELLIGENCE_LAYERS.md: where decisions sit among the layers.
- CODE_HEALTH.md, HOOKS.md, CONFIG.md: governance findings, injection hooks, the
decisions:block.