Codebase Exploration with Repowise
This project has a Repowise intelligence layer. Before grepping and reading raw
source to understand the codebase, reach for the Repowise MCP tools — they
return documentation, ownership, history, decisions, and graph structure that
plain file reads don't, usually in one round-trip instead of many.
Which tool for which question
| You want… |
Call |
| First orientation in an unfamiliar repo |
get_overview() — architecture summary, key modules, entry points, git health, knowledge map. Skip it once you have the map. |
| A direct answer to "how/where/why does X work" |
get_answer(question="…") — synthesised answer with citations + a retrieval_quality signal. Collapses the search → read → reason loop. |
| Find a symbol, file, or fuzzy concept |
search_codebase(query="…") — hybrid search. mode="auto" routes an identifier to indexed symbol hits (symbol_id/line bounds → pipe into get_symbol), a path to file pages (→ get_context), and prose to semantic wiki search (each hit reports search_method: embedding vs bm25). Force a branch with mode=symbol|path|concept|hybrid; narrow symbols with symbol_kind. |
| A triage card for specific files/symbols |
get_context(targets=[…]) — title, summary, signatures, hotspot bit, top callers, decision titles, symbol_ids. Batch many targets in one call. |
| The actual source of one symbol |
get_symbol("path/to/file.py::Name") — exact bytes with line bounds. Cheaper than Read + offset math. Use a symbol_id from get_context. |
Recommended flow
- New area you don't know →
get_overview() once.
- A specific question →
get_answer(question=…) first.
- High confidence → answer it, cite the paths.
medium/low confidence → follow best_guesses[0].file or
fallback_targets[0] into get_context, then get_symbol for bytes.
- A named symbol or a path →
search_codebase(query="Name") /
search_codebase(query="path/to/file.py"); symbol hits pipe straight into
get_symbol, file hits into get_context.
- More files around a concept →
search_codebase, then get_context on the
hits (batched), then get_symbol only for the bodies you actually need.
Fall back to raw Read/Grep only when the indexed context doesn't cover the
specific detail the user asked about.
Trust signals — verify when
_meta.stale_warning is present (the index has diverged from HEAD), orretrieval_quality is partial/weak, or- a result's
search_method is bm25.
Otherwise the response is current — act on it.
Error handling
- "No repositories found. Run 'repowise init' first." → suggest
/repowise:init.
Add --no-editor-setup if this repo is a scratch clone, a fixture, or a
worktree: init otherwise repoints the user's single global repowise MCP
entry at it.
- MCP tools unavailable → prefer the matching CLI slash commands when the
plugin is installed (
/repowise:ask, /repowise:context, /repowise:symbol,
/repowise:search) rather than grepping blind.
get_answer/search_codebase come back empty → the repo may have a
template-rendered wiki. Fall back to get_context with explicit paths, and note
that model-written pages (repowise generate, or /repowise:init with an LLM
provider) unlock richer docs + semantic search.- Tools fail to connect at all → the
repowise binary may not be installed;
suggest /repowise:init.
1---2name: codebase-exploration-23description: Use when exploring, understanding, or answering questions about a codebase that has Repowise indexed (a .repowise/ directory in the project root). Activates for "how does X work", "explain the architecture", "where is Y implemented", "what does this module do", or any task that needs an understanding of structure before diving into source files.4---56# Codebase Exploration with Repowise78This project has a Repowise intelligence layer. Before grepping and reading raw9source to understand the codebase, reach for the Repowise MCP tools — they10return documentation, ownership, history, decisions, and graph structure that11plain file reads don't, usually in one round-trip instead of many.1213## Which tool for which question1415| You want… | Call |16|---|---|17| First orientation in an unfamiliar repo | `get_overview()` — architecture summary, key modules, entry points, git health, knowledge map. Skip it once you have the map. |18| A direct answer to "how/where/why does X work" | `get_answer(question="…")` — synthesised answer with citations + a `retrieval_quality` signal. Collapses the search → read → reason loop. |19| Find a symbol, file, or fuzzy concept | `search_codebase(query="…")` — hybrid search. `mode="auto"` routes an identifier to indexed symbol hits (`symbol_id`/line bounds → pipe into `get_symbol`), a path to file pages (→ `get_context`), and prose to semantic wiki search (each hit reports `search_method`: `embedding` vs `bm25`). Force a branch with `mode=symbol\|path\|concept\|hybrid`; narrow symbols with `symbol_kind`. |20| A triage card for specific files/symbols | `get_context(targets=[…])` — title, summary, signatures, hotspot bit, top callers, decision titles, symbol_ids. Batch many targets in one call. |21| The actual source of one symbol | `get_symbol("path/to/file.py::Name")` — exact bytes with line bounds. Cheaper than Read + offset math. Use a `symbol_id` from `get_context`. |2223## Recommended flow24251. New area you don't know → `get_overview()` once.262. A specific question → `get_answer(question=…)` first.27 - High confidence → answer it, cite the paths.28 - `medium`/`low` confidence → follow `best_guesses[0].file` or29 `fallback_targets[0]` into `get_context`, then `get_symbol` for bytes.303. A named symbol or a path → `search_codebase(query="Name")` /31 `search_codebase(query="path/to/file.py")`; symbol hits pipe straight into32 `get_symbol`, file hits into `get_context`.334. More files around a concept → `search_codebase`, then `get_context` on the34 hits (batched), then `get_symbol` only for the bodies you actually need.3536Fall back to raw Read/Grep only when the indexed context doesn't cover the37specific detail the user asked about.3839## Trust signals — verify when4041- `_meta.stale_warning` is present (the index has diverged from HEAD), or42- `retrieval_quality` is `partial`/`weak`, or43- a result's `search_method` is `bm25`.4445Otherwise the response is current — act on it.4647## Error handling4849- "No repositories found. Run 'repowise init' first." → suggest `/repowise:init`.50 Add `--no-editor-setup` if this repo is a scratch clone, a fixture, or a51 worktree: `init` otherwise repoints the user's single global `repowise` MCP52 entry at it.53- MCP tools unavailable → prefer the matching CLI slash commands when the54 plugin is installed (`/repowise:ask`, `/repowise:context`, `/repowise:symbol`,55 `/repowise:search`) rather than grepping blind.56- `get_answer`/`search_codebase` come back empty → the repo may have a57 template-rendered wiki. Fall back to `get_context` with explicit paths, and note58 that model-written pages (`repowise generate`, or `/repowise:init` with an LLM59 provider) unlock richer docs + semantic search.60- Tools fail to connect at all → the `repowise` binary may not be installed;61 suggest `/repowise:init`.
repowise-dev