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 (seven mined at index time, plus your session transcripts), plus manual cli capture.

Seven sources, mined in parallel

Beyond manual capture via the CLI, repowise mines decisions automatically from seven sources: ADR files, CHANGELOGs, PR bodies, inline markers, git archaeology, READMEs, and the LLM doc-generation pass itself. All seven 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 four sources

ADR files (Nygard/MADR format), CHANGELOG entries, PR and squash-commit bodies, and README/docs 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.

Mined from your sessions

Beyond the index-time sources, repowise reads your own Claude Code transcripts for the corrections and conventions you actually enforce — "new endpoints go through the auth middleware", "use the shared HTTP client, not raw requests" — and turns the durable, repeated ones into tracked decisions. Deterministic gates decide what's worth keeping before a single batched LLM pass writes them up, so a one-off nudge never becomes a permanent rule. Repo-wide rules with no specific file (a project-wide convention) are kept too, and apply everywhere.

Delivered where it matters

Decisions reach the agent through the proactive hooks, no LLM and no round-trip:

• At session start, the decisions relevant to what this session is about to touch land in a compact block, scored against the working set. Relevance or silence — nothing is injected just for being high-confidence.
• At edit time, when the agent edits a file a decision governs, it gets a one-line "governed by" notice with the rationale.

And it learns: every injected decision is recorded locally, and on the next repowise update the session miner checks whether the guidance was followed or contradicted by your corrections, relaxing or bumping the decision's staleness — so guidance that stops being true stops being injected.

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.