# Survey

> Explore codebase structure, entry points, tech stack, hotspots, and call graphs

- Skill: `jmylchreest/survey` (Agent Skill)
- Install (CLI): `npx skillmds@latest add jmylchreest/survey`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jmylchreest/survey/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: jmylchreest (https://skillmd.com/u/jmylchreest)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/jmylchreest/survey

---


# 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

| Question                      | Tool            | Parameters                  |
| ----------------------------- | --------------- | --------------------------- |
| "What is this codebase?"      | `survey_list`   | kind=module                 |
| "What tech stack?"            | `survey_list`   | kind=tech_stack             |
| "Where are the entry points?" | `survey_list`   | kind=entrypoint             |
| "What changes most?"          | `survey_list`   | kind=churn                  |
| "Is there an auth module?"    | `survey_search` | query="auth"                |
| "Who calls this function?"    | `survey_graph`  | symbol=X, direction=callers |
| "What does this call?"        | `survey_graph`  | symbol=X, direction=callees |

## Survey vs Findings vs Code Search

| Tool            | Purpose              | Example                                  |
| --------------- | -------------------- | ---------------------------------------- |
| **Survey**      | WHAT the codebase IS | Modules, tech stack, entry points, churn |
| **Findings**    | Code PROBLEMS        | Complexity, security issues, duplication |
| **Code Search** | Symbol DEFINITIONS   | Find function signatures, call sites     |

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)