# Architectural Decisions

Explains why code is built a certain way and records design decisions.

- Repository: https://github.com/repowise-dev/repowise (8087 stars)
- Category: Engineering
- License: AGPL-3.0
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add repowise-dev/repowise --skill architectural-decisions -g -a claude-code -y`
Codex: `npx skills add repowise-dev/repowise --skill architectural-decisions -g -a codex -y`
Cursor: `npx skills add repowise-dev/repowise --skill architectural-decisions -g -a cursor -y`
Gemini CLI: `npx skills add repowise-dev/repowise --skill architectural-decisions -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add repowise-dev/repowise`

## Description

Use when encountering questions about WHY code is built a certain way, when about to make architectural changes (new patterns, restructuring, choosing between approaches), or when the user asks about design rationale in a Repowise-indexed codebase (.repowise/ directory exists). Also activates when commit messages or code comments contain decision signals like "WHY:", "DECISION:", "TRADEOFF:", "ADR:".

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 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)

The rest: https://github.com/repowise-dev/repowise/blob/HEAD/plugins/claude-code/skills/architectural-decisions/SKILL.md