Codebase Survey

Recommended model tier: balanced (sonnet) - this skill performs structured queries

Understand the structure, technology, entry points, and change hotspots of a codebase. Survey describes WHAT the codebase IS — not code problems (use findings for that).

Available Tools

1. Survey Stats (mcp__plugin_aide_aide__survey_stats)

Start here. Get an overview of what has been surveyed: total entries, breakdown by analyzer and kind, and per-analyzer freshness (the git commit each analyzer last ran at, and how many commits behind HEAD it is).

Is the codebase surveyed?
→ Uses survey_stats
→ Returns: counts by analyzer (topology, entrypoints, churn, modules) and kind, plus freshness vs git HEAD

If freshness shows an analyzer is commits behind HEAD, re-run survey_run before trusting its data.

2. Survey Run (mcp__plugin_aide_aide__survey_run)

Run analyzers to populate survey data. Three analyzers available:

• topology — Packages, workspaces, build systems, tech stack detection (filesystem view)
• entrypoints — main() functions, HTTP handlers, gRPC services, CLI roots (cobra/urfave). Uses code index when available; falls back to file scanning
• churn — Git history hotspots (files/dirs that change most often)
• modules — Structural modules discovered by clustering the import/reference graph: what files actually belong together, which directory layout can hide. Requires the code index (aide code index)

Survey this codebase
→ Uses survey_run (no analyzer param = run all)
→ Returns: entry counts per analyzer, an added/removed diff vs the previous run, and the git commit the run is tagged with

3. Survey List (mcp__plugin_aide_aide__survey_list)

Browse entries filtered by analyzer, kind, or file path. No search query needed.

Kinds: module, entrypoint, dependency, tech_stack, churn, submodule, subproject, workspace, arch_pattern

What other projects live inside this repo?
→ Uses survey_list with kind=subproject
→ Returns: child project scopes (submodules, nested repos) with identity and whether each has its own .aide store — their files belong to THEIR stores, not this project's

What modules are in this codebase?
→ Uses survey_list with kind=module
→ Returns: all module entries

What technologies does this use?
→ Uses survey_list with kind=tech_stack
→ Returns: detected frameworks, languages, build systems

What files change most?
→ Uses survey_list with kind=churn
→ Returns: high-churn files ranked by commit count

4. Survey Search (mcp__plugin_aide_aide__survey_search)

Full-text search across entry names, titles, and details. Use when looking for specific modules or technologies.

Find anything related to "auth"
→ Uses survey_search with query="auth"
→ Returns: modules, entrypoints, churn entries matching "auth"

5. Call Graph (mcp__plugin_aide_aide__survey_graph)

Build a call graph for a symbol showing callers, callees, or both. BFS traversal over the code index.

Who calls BuildCallGraph?
→ Uses survey_graph with symbol="BuildCallGraph" direction="callers"
→ Returns: graph of calling symbols with file:line locations

What does handleSurveyRun call?
→ Uses survey_graph with symbol="handleSurveyRun" direction="callees"
→ Returns: graph of called symbols

Show call neighborhood of RunTopology
→ Uses survey_graph with symbol="RunTopology" direction="both"
→ Returns: both callers and callees

Parameters:

• symbol (required): Function/method name
• direction: "both" (default), "callers", "callees"
• max_depth: BFS hops (default 2)
• max_nodes: Max nodes (default 50)

Requires: Code index must be populated (aide code index).

Workflow

Orienting in an unfamiliar codebase

1. Check survey status:
   • Use survey_stats to see if data exists
   • If empty, run survey_run to populate
2. Understand the structure:
   • survey_list kind=module — What are the major modules?
   • survey_list kind=tech_stack — What technologies are used?
   • survey_list kind=workspace — Is this a monorepo?
3. Find entry points:
   • survey_list kind=entrypoint — Where does execution start?
   • Identifies main() functions, HTTP handlers, CLI roots
4. Identify hotspots:
   • survey_list kind=churn — What files change most? (complexity/bug magnets)
5. Trace call relationships:
   • survey_graph symbol="handleRequest" — Map the call neighborhood
   • Use direction=callers to find who invokes a function
   • Use direction=callees to understand what a function depends on

Answering specific questions

Survey vs Findings vs Code Search

Survey gives you the big picture. Code search gives you specific symbols. Findings gives you problems to fix.

Prerequisites

• Survey data: Run aide survey run or use survey_run tool
• Code index (for entrypoints + graph): Run aide code index
• Git history (for churn): Must be a git repository (uses go-git, no git binary needed)

Binary location: The aide binary is at .aide/bin/aide. If it's on your $PATH, you can use aide directly.

Notes

• Survey results are cached in BoltDB — re-run analyzers to refresh after significant changes
• Topology analyzer inspects the filesystem (build files, directory structure)
• Entrypoints analyzer uses the code index when available; falls back to file scanning
• Churn analyzer uses go-git to read git history directly (no git binary required)
• Call graph is computed on demand from the code index (not stored)