# Map

> Static mapping and standalone navigation of existing map evidence. TRIGGER WHEN: project questions, unfamiliar code, debugging, feature work, refactors, reviews or documentation. Consult map evidence before broad exploration. Loading the skill starts no analysis or refresh. Verify claims against source; search the repository without usable maps. DO NOT TRIGGER WHEN: no project code or documentation.

- Skill: `acaprino/map` (Agent Skill, multi-file: 51 files)
- Install (CLI): `npx get-skill add acaprino/map`
- Raw SKILL.md: https://api.skillmd.com/api/skills/acaprino/map/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: acaprino (https://skillmd.com/u/acaprino)
- Updated: 2026-11-11
- Page: https://skillmd.com/skills/acaprino/map

---


# Codebase Map Analysis Skill

## Language Support

| Language | Extensions | Structural extraction | Comment syntax |
|---|---|---|---|
| Python | `.py`, `.pyi` | stdlib `ast` (always available) | `#` line + docstrings |
| Java | `.java` | tree-sitter (preferred) or regex | `//`, `/* */`, Javadoc `/** */` |
| JavaScript | `.js`, `.mjs`, `.cjs`, `.jsx` | tree-sitter (preferred) or regex | `//`, `/* */`, JSDoc `/** */` |
| TypeScript | `.ts`, `.tsx`, `.mts`, `.cts` | tree-sitter (preferred) or regex; adds interfaces, enums, type aliases | `//`, `/* */`, JSDoc `/** */` |
| SQL | `.sql`, `.ddl`, `.dml` | DDL + table/view reference graph (`sql-ast` / optional `sqlglot`) | `--`, `/* */` |
| PL/SQL (Oracle) | `.pks`, `.pkb`, `.plsql`, `.pls`, `.pck`, `.prc`, `.fnc`, `.trg` | regex (packages, package bodies, type bodies, cursors, exceptions, %TYPE/%ROWTYPE references) | `--`, `/* */` |
| Rust | `.rs` | tree-sitter (preferred) or regex; structs, enums, traits, impls (with `Trait for Type` naming), mods, unions, type aliases, `#[tauri::command]` exports | `//`, `/* */`, rustdoc `///` / `//!` / `/** */` / `/*! */` |
| Go | `.go` | tree-sitter (preferred) or regex; functions, methods, types | `//`, `/* */` |
| Kotlin | `.kt`, `.kts` | tree-sitter (preferred) or regex; classes, interfaces, objects, suspend functions, properties | `//`, `/* */`, KDoc `/** */` |
| C# | `.cs` | tree-sitter (preferred) or regex; namespaces, classes, interfaces, structs, records, enums, async methods, properties | `//`, `/* */`, XML doc `///` |
| Vue / Svelte | `.vue`, `.svelte` | byte-aligned `<script>` / `<script setup>` extraction via JS/TS adapters | `//`, `/* */` inside script blocks |
| CSS, SCSS, LESS | `.css`, `.scss`, `.less` | stdlib tokenizer, never tree-sitter; one symbol per applied rule (flattened selector within enclosing at-rules); top-level at-rules, Sass/LESS variables, mixins, Sass functions; `@import`/`@use`/`@forward`; Tailwind `@apply` layout utilities expanded as declarations | `/* */`, and `//` outside plain CSS |

`.sql` is disambiguated against PL/SQL by Oracle-specific content markers (`languages/__init__.py`); `plpgsql` stays SQL.

## How This Skill Is Invoked

`references/entry-analyze.md` dispatches isolated `codebase-map:map-analyst`;
`references/entry-team-analyze.md` uses isolated partition workers. Entries own
`.daodan/map/` publication (`references/run.md`).
Loading `codebase-map:map` starts no analysis or run.

## Load map

| Unit | Holds | Loaded by |
|---|---|---|
| `references/run.md` | classic/team runs, concurrency and perimeter | whoever owns the run |
| `references/snapshot.md` | snapshot ownership, scope, write, diff, carry and check commands | whoever owns the run's snapshot |
| `references/update.md` | incremental re-derivation | analyst on accepted updates |
| `references/deepen.md` | cards an area lacks | area deepening; analyst in `cards` mode |
| `references/evidence.md` | evidence, forbidden files, commands, source reading, classification; maintained-document verification separately | every phase worker and every consumer that reads source |
| `references/reading.md` | analysis reading | every consumer of a bound analysis |
| `references/standalone.md` | shared read-only map discovery, navigation, impact and fallback | every map consumer, including analysis and composed workflows |
| `references/locate.md` | the measured loop for finding the code a request is about: search by name, expand with outline and graph, read by symbol, reproduce, then fix | every agent that changes code with a map |
| `references/modules.md` | the module graph: build units read from manifests, modules declared by the project or proposed by a model, with members, relations, freshness and the name query | every consumer resolving a module or sub-app boundary, including review scope resolution |
| `references/scope.md` | progressive code scope: `scope_planner.py` selecting evidence from snapshots, edges and optional retrieval | whoever plans the evidence of an analysis or intervention |
| `references/context.md` | bounded context packets from a scope plan (`snapshot.py context`) | whoever prepares a recipient's input |
| `references/embeddings.md` | optional local embeddings, opt-in only | whoever explicitly selects the embedding provider |
| `references/mcp.md` | the MCP server, its tools and events | whoever runs or calls the server |
| `references/tools-guide.md` | which tool answers which question, with one example each | whoever has to choose a tool on a bound run, including review scope resolution |
| `references/phase-0.md` | Phase 0 knowledge discovery | analyst and team entry |
| `references/phases-1-2.md` | Phase 1 structure, Phase 2 interfaces | phase 1 and 2 workers |
| `references/phases-3-4.md` | Phase 3 flows, Phase 4 semantics and the analysis loop | phase 3 and 4 workers |
| `references/phases-5-6.md` | Phase 5 patterns and risks, Phase 6 documentation health | phase 5 and 6 workers |
| `references/phase-7.md` | Phase 7 final report | analyst and synthesizer |

## Depth

Full runs phases 0 to 7. Lite runs 0, 1, 2 and 5, omits `03`, `04` and `06`,
omits the diagrams of non-critical files in Phase 5, and condenses `07` to
structure, interfaces and risks: no Critical Paths, Design Insights, Key
Process Diagrams or Documentation vs Reality, with the three coverage lines
kept. In team mode lite spawns no behavior worker and the quality worker writes
only `05-risks.md`. `snapshot.py prepare` declares the artifacts; no unit
repeats this table.

## Consumer map

- Every map consumer, including analyze and composed workflows: `references/standalone.md` and `references/reading.md` section `Task views`. Ordinary standalone source reads add `references/evidence.md` sections `CRITICAL PRINCIPLE: EVIDENCE-ANCHORED OUTPUT` and `Forbidden Files`; composed consumers keep their own authorized evidence and producer procedures.
- Forbidden files: `references/evidence.md`.
- Consuming a bound analysis: `references/reading.md`, plus `references/evidence.md` before Maintained documentation for source. For durable-document verification, read its Maintained documentation section. Snapshot verification/refresh uses `references/snapshot.md` before Prerequisites.
- Run analyses through `references/entry-analyze.md`; composed callers declare isolated `codebase-map/map-analyst`.

## Team bindings

Use canonical skeletons in owned output. Put partition identity below titles, never in headings. Workers and synthesizers do not update classic state.

## Resources

Python >= 3.12 scripts: `${CLAUDE_PLUGIN_ROOT}/skills/map/scripts/`.
Language Support above applies throughout. These are the entry points; the
other modules beside them are libraries they import.

- `mcp_server.py`: the MCP server over `mcp_service.py` (`references/mcp.md`).
- `ast_parser.py`: structural extraction dispatcher.
- `analyze_file.py`: classification/structure/usages; workflows reuse `--snapshot`.
- `classifier.py`: language-aware criticality.
- `usage_finder.py`: cross-file symbol usages.
- `comment_rewriter.py`: multi-language comment analysis.
- `rewrite_comments.py`: comment quality CLI: scan/analyze/rewrite/report.
- `doc_review.py`: documentation maintenance (Phase 6).
- `confinement.py`: project binding, link refusal and the per-project lock every helper shares.
- `snapshot.py`: scope, SQLite snapshots (explicit JSON), run resolution, incremental changes.
- `modules.py`: module graph beside a snapshot (`modules.json`/`.md`): `build`, `query`, `brief` for a model, `propose` to record its verified proposals.
- `source_reader.py`: manifest graphs, outlines and validated source blocks.
- `resolve_edges.py`: engine call resolution into `engine-edges.sqlite` (`--engine jedi` by default, or `--engine scip`); `snapshot.py write` and run creation start it in the background.
- `semantic_map.py`: `semantic-map.md` view of an area's cards (`references/deepen.md`).
- `tree_scope.py`: shared Git, dot-directory and dependency/build perimeter.
- `cascade_scan.py`: global stylesheet layout risks, cascade overrides and screen rules (Phase 5).
- `languages/`: per-language adapters listed above.
- `requirements.txt`: tree-sitter, tree-sitter-language-pack and sqlglot, which the MCP server installs itself.

