Architectural Decisions with Repowise

Repowise captures architectural decisions, the why behind how code is built.

get_why has four modes, pick by what you pass:

1. get_why(query="why is auth using JWT?"), keyword + semantic decision search.
2. get_why(query="src/auth/service.py"), decisions governing that file, plus its origin story and an alignment score (does the file still follow its own ADRs?).
3. get_why(query="why was caching added?", targets=["src/auth/cache.py"]), target-anchored search; decisions touching the targets get boosted.
4. get_why(), the decision-health dashboard.

Decisions are mined from five sources (ADR files, PR and squash-commit bodies, inline markers, git archaeology, and centrality-bounded code comments). Each rationale traces to a verbatim source span, stamped exact / fuzzy / unverified. When no decision exists for a path, get_why falls back to git archaeology so the call is never empty.

When the user asks "why is X built this way?"

Call get_why(query="X").

When about to make an architectural change

1. Call get_why(query="the specific area you're changing") to find existing decisions that govern that area.
2. If decisions are found, present them to the user before proceeding, they may not want to contradict an existing architectural choice.
3. If no decisions are found, proceed but note that no recorded decision governs this area.

When called with no specific query

Call get_why() with no arguments to get the decision-health dashboard:

• Stale decisions that may no longer apply
• Proposed decisions awaiting confirmation
• Ungoverned hotspots (high-churn files with no recorded decisions)