repo-cartographer
Maps an unfamiliar codebase into a visual onboarding document (docs/architecture.md) with Mermaid diagrams — system layers, module dependencies, a traced core data flow — plus an opinionated 5-file re
SKILL.mdSKILL.md
GitHubRepo Cartographer
Turn any repository into a map a newcomer can read in 10 minutes: docs/architecture.md.
Output contract
One file: docs/architecture.md, with exactly these sections in this order:
- TL;DR — what the project does (2–3 sentences) + tech stack in one line + the archetype you classified (see Phase 2).
- System Map — Mermaid
flowchartof top-level components/layers and how they connect. - Module Dependencies — Mermaid
flowchartof who imports/calls whom. Core modules only. - Core Flow — one Mermaid
sequenceDiagramof the most representative runtime flow (e.g. a request from entry to response, a command from argv to output). - Reading Order — exactly 5 files, in order, each with a one-line reason. This is the most valuable section: be opinionated.
- Conventions — small table: build command, test command + where tests live, error-handling style, naming style, anything surprising.
If docs/architecture.md already exists, overwrite it and say so.
Method
Work in four phases. Do not skip phases; each feeds the next.
Phase 1 — Scout (breadth, not depth)
Goal: build an inventory, not an understanding.
- Read the manifest first:
package.json/pyproject.toml/go.mod/Cargo.toml/pom.xml/*.csproj, etc. Note entry points (main,bin, scripts), major dependencies, module/workspace declarations. - Read the README (and the
docs/index if present) for the project's own self-description. - List the top 2 directory levels. For monorepos, list each package once.
- Identify entry points: HTTP server bootstrap, CLI main, library public API (
__init__.py,index.ts,lib.rs).
Phase 2 — Classify
Decide the repo archetype. This determines which flow is "most representative":
| Archetype | Representative flow to trace |
|---|---|
| Web/backend service | one HTTP request: route → handler → service → data store → response |
| CLI tool | one command: argv → parse → execute → output |
| Library/SDK | one public API call: export → implementation → internals |
| Frontend app | one user interaction: event → state change → render |
| Data pipeline | one record: ingest → transform → store |
| Monorepo | pick the package the README leads with; note inter-package deps |
State the archetype in the TL;DR.
Phase 3 — Trace (now go deep, but only along one line)
- Pick the representative flow from Phase 2.
- Follow it through the actual code: open each file the flow touches, in call order. Verify each hop exists — never assume a call from a file name.
- Collect the real module boundaries you crossed; these become your dependency-graph nodes.
- While tracing, note the 5 files that mattered most → seeds of the Reading Order.
- For anything you could not verify (dynamic dispatch, DI, reflection, config-driven wiring), mark the node
name (?)in diagrams and add one line below the diagram saying why.
Phase 4 — Draw & write
Write docs/architecture.md per the output contract. Rules:
- ≤ 15 nodes per diagram. Merge or omit; a map that shows everything shows nothing. Put detail in prose below the diagram if it matters.
- Every edge has a label naming the real relationship (
calls,imports,publishes to,reads from), not a bare arrow. - Mermaid must be valid: quote node labels containing special characters; verify mentally that it parses.
- Direction:
flowchart TDfor layers,flowchart LRfor dependencies/pipelines. - Never invent modules, files, or relationships you did not see. Uncertainty is marked
(?), not guessed away. - Reading Order entries use real relative paths that exist in the repo.
- Keep the document ≤ ~200 lines. It is a map, not a book.
Large repos (>500 files)
- Do not read exhaustively — sample. Manifest + entry points + one traced flow is enough signal.
- Use search tools for "where is X handled" / "who imports Y". Prefer grep over opening files at random.
- Prefer a depth-2 directory listing; go deeper only into directories the traced flow enters.
- If the repo has multiple independent subsystems, draw the System Map at subsystem level and trace a flow in only the primary one; describe the others in one line each.
After writing
Reply with: the file path created, the archetype you classified, and a 3-line summary of the architecture. Nothing else — the document is the deliverable.