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.
• Source — cli, git_archaeology, inline_marker, readme_mining.

Three sources

1. The CLI

Capture a decision interactively in ~90 seconds:

repowise decision add

See decision CLI commands for the full subcommand list.

2. 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.

3. 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>).

Linked to the graph

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.

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.