Codebase Cartographer

---
name: codebase-cartographer
description: >
  Map an unfamiliar codebase by parsing its actual structure, then draw it. Use when
  the user asks to understand, diagram, or navigate a repository: "explain this
  codebase", "diagram the architecture", "show the call graph", "what depends on what",
  "how does this module flow", "I inherited this repo". Produces Mermaid/Graphviz
  diagrams grounded in parsed ASTs and import graphs, not in a skim. Do NOT use for
  writing new code or for single-function explanations that need no structural map.
---

# Codebase Cartographer

The default failure mode when Claude is asked to explain a codebase is to skim a few
files and narrate a plausible-sounding architecture that may not be real. This skill
forbids that: parse first, then draw only what the parse supports.

Distilled from four patterns: incremental-compiler-dependency-graph (map pipeline steps
as dependency rules over source files), AST-to-ABI generation (extract public interfaces
and types from an AST), canvas-workflow-graph-compiler (resolve nodes+edges into a
dependency-ordered DAG), and AST control-flow-graph visualization (emit a graph as
Graphviz/Mermaid). Provenance includes real compiler and graph-compiler codebases.

## Procedure

### 1. Inventory
Walk the repo. Identify languages, entry points, package/module boundaries, and build
manifests (package.json, pyproject.toml, Cargo.toml, go.mod). Do not read every file;
read manifests and entry points first to get the skeleton.

### 2. Parse, do not skim
Build a real import/dependency graph by parsing each module's imports with a language-
appropriate parser (Python ast, tree-sitter for polyglot repos, or language tooling).
Extract each module's public interface (exported functions, classes, types) via the
AST. Where the user wants control flow, build the call graph for the target module from
parsed function definitions and call sites — not from prose inference.

### 3. Resolve into an ordered graph
Merge the parsed nodes and edges into a dependency-ordered DAG. Detect and flag cycles
(circular imports), orphan modules (imported by nothing), and god-modules (imported by
almost everything) — these are the findings a human actually wants.

### 4. Draw
Emit Mermaid (preferred for inline rendering) or Graphviz. Offer the views that fit the
question: module dependency graph, package-level architecture, call graph for a chosen
entry point, or data-flow through a pipeline. Keep each diagram legible — collapse
subtrees and link to detail rather than rendering 500 nodes at once.

## Acceptance check
Every node and edge in the diagram traces to a real parsed import or call — pick three
edges at random and point to the source line that produced each. Cycles and orphans are
reported explicitly. The diagram renders without syntax errors.