# How it works

How repowise builds its index in five passes (dependency graph, git history, wiki, decision records and code health) and how the MCP tools query the result.

Repowise's index is a single artifact built from five passes over your repo.
Each pass produces something the next one consumes; the final shape is what
the MCP tools query.

```mermaid
flowchart LR
  Repo[Git repo] --> Parse[Tree-sitter parse]
  Parse --> Graph[Dependency graph<br/>files + symbols]
  Repo --> Git[Git history walk]
  Git --> Sigs[Hotspots, ownership,<br/>co-changes]
  Graph --> LLM[Wiki pass<br/>model or structure]
  Sigs --> LLM
  LLM --> Wiki[Wiki pages<br/>+ citations]
  Repo --> Marks[Decision markers<br/>+ commits]
  Marks --> Decisions[Decision records]
  Graph --> Health[Code health<br/>defect · maint · perf]
  Sigs --> Health
  Graph --> Index[(Index artifact)]
  Sigs --> Index
  Wiki --> Index
  Decisions --> Index
  Health --> Index
  Index --> MCP[MCP tools]
  MCP --> Agent[Your AI agent]
```

## 1. Dependency graph

Language-aware resolvers under `packages/core/src/repowise/core/ingestion/resolvers/`
parse each file, extract symbols, and emit import edges. Symbols are nodes,
imports are edges, and PageRank + community detection run once at the end to
surface the architectural skeleton.

→ [Dependency graph](https://docs.repowise.dev/intelligence/dependency-graph)

## 2. Git history

A second pass walks the newest 5,000 commits of the git log and records, per
file: commit count, last-touched date, primary owner, co-change pairs (files
that move together), and churn percentile. This is what powers hotspots, bus-factor, and the "who can review
this PR" queries.

→ [Git history & co-changes](https://docs.repowise.dev/intelligence/git-history)

## 3. Generated wiki

For each non-trivial file and every module, repowise produces a short Markdown
page that names the symbol's purpose, cites callers, and flags anything weird.
The wiki is the substrate `get_answer` and `get_context` retrieve from: the LLM
is reasoning over Repowise's prose, not raw source.

The pass runs one of two ways. With a provider configured, an LLM writes each
page. Without one, repowise renders the same page set from the graph and git
signals the earlier passes produced, with no model in the loop, which is why
`repowise init` works and exits 0 on a machine with no API key.

→ [Auto-generated wiki](https://docs.repowise.dev/intelligence/auto-wiki) ·
[Deterministic wiki](https://docs.repowise.dev/intelligence/deterministic-wiki)

## 4. Architectural decisions

Decisions are first-class. You write them by hand (`repowise decision add`) or
let repowise capture them from significant commits and inline markers. They link
to the files they constrain, so `get_why` can answer "why is this code
structured this way" with citations.

→ [Architectural decisions](https://docs.repowise.dev/intelligence/decisions)

## 5. Code health

A final deterministic pass scores every file 1 to 10 from markers across
three signals (defect risk, maintainability, performance), reusing the
graph (centrality) and git signals (ownership, churn, co-change) the earlier
passes produced, plus structural complexity, duplication, and static
performance risk. No LLM calls. The defect-risk weights are calibrated
against a real defect corpus, so the
score predicts where bugs will land, and `get_health` exposes it to your agent.

→ [Code health](https://docs.repowise.dev/intelligence/code-health)

---

## Change evidence

The same passes also read each merged change as a **Change Record**: the
components it touched, their owners, the tests that reach it, decisions it
crossed, AI provenance with coverage, and whether a later commit reverted or
fixed it. Components, a local change policy and evidence reports build on
those records. See [Change evidence](https://docs.repowise.dev/cli/changes).

---

The five layers are computed once, then refreshed incrementally on every push
(or every git commit, if you install the post-commit hook). See
[Auto-sync](https://docs.repowise.dev/auto-sync) for the five sync mechanisms.