Architectural decisions

Most documentation rots because the why lives in the original author's head. Repowise treats architectural decisions as first-class data — captured, linked to the files they govern, tracked for staleness, and surfaced to your AI agent via get_why.

What's a decision

A decision is a structured record with:

• Title — short summary.
• Context — what was the situation.
• Decision — what was chosen.
• Rationale — why.
• Alternatives — what was rejected.
• Consequences — what it implies going forward.
• Affected files — the graph nodes the decision governs.
• Tags — for cross-cutting concerns (security, performance, etc.).
• Status — proposed, active, deprecated, superseded.
• Verification — verified, fuzzy, or unverified, from an anti-hallucination gate that checks each claim against a literal source span rather than trusting the extraction.
• Source — one of the eight capture channels below, plus manual cli capture.

Eight sources, mined in parallel

Beyond manual capture via the CLI, repowise mines decisions automatically from eight sources: ADR files, CHANGELOGs, PR bodies, inline markers, git archaeology, READMEs, code comments, and the LLM doc-generation pass itself. All eight run concurrently at index time; a failure in one source never blocks the others.

The CLI

Capture a decision interactively in ~90 seconds:

repowise decision add

See decision CLI commands for the full subcommand list.

Inline markers in source

Drop a marker comment in the file it governs:

# WHY: JWT chosen over sessions — API must be stateless for k8s scaling
# DECISION: All external API calls wrapped in CircuitBreaker after Q3 outages
# TRADEOFF: Accepted eventual consistency in preferences for write throughput

These get extracted at index time, linked to the file they live in, and treated as active decisions.

Git archaeology

Repowise mines significant commit messages and proposes decisions automatically. Run repowise decision list --proposed to review and either confirm them (repowise decision confirm <id>) or dismiss them (repowise decision dismiss <id>).

The other five sources

ADR files (Nygard/MADR format), CHANGELOG entries, PR and squash-commit bodies, README/docs, and centrality-bounded code comments are all mined the same way: each candidate is checked against a literal source passage before it's kept, so a decision is only ever verified when the evidence actually says so.

Verify, don't invent

Every mined decision carries a verification status: verified (the claim traces to a literal quote in the source), fuzzy (related evidence exists but doesn't match exactly), or unverified (kept, but flagged rather than silently dropped or overwritten). Repowise never fabricates a rejection it can't justify.

Linked to the graph, connected to each other

Every decision is linked to the graph nodes it governs. When your agent edits a file, get_why automatically surfaces the decisions that touch it — without you having to remember to ask.

Decisions also connect to each other by typed edges: supersedes (one decision replaces another), refines (narrows or extends without reversing it), relates_to (same topic, no ordering implied), and conflicts_with (two active decisions that contradict, with neither clearly winning — a governance smell surfaced in code health). This is how get_why answers a lineage question like "why is auth structured this way?" with a chain, not just the latest record.

Staleness and health

Decisions decay. If a file's last_commit_at moves forward but the decision's last_update_at doesn't, repowise flags it stale. Run:

repowise decision health

Or, agent-facing:

get_why()  # no arguments → health dashboard

You'll see stale decisions, proposed-awaiting-review, and ungoverned hotspots (high-churn files with no decisions on file).

Workspace decisions

In a workspace, decisions are per-repo by default. Pass repo="all" to get_why to search across the workspace.