codebase-exploration

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 + one confidence trust 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 (a row without one is path::name). 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

1. New area you don't know → get_overview() once.
2. 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.
3. 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.
4. 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 your own file-reading and searching tools 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), or
• confidence is medium/low, 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.