Map and Navigate Codebases with DSP

This skill solves LLM coding agents losing context between tasks and burning tokens on "orientation" in large codebases by externalizing the project's structural map into a persistent, queryable graph stored in a .dsp/ directory next to the code. DSP is not documentation for humans and not an AST dump - it captures meaning (why an entity exists), boundaries (what it imports and exposes), and reasons (why each connection exists), enough for an agent to navigate, refactor, and generate code without loading the entire source tree into context.

It models the codebase as a directed graph where nodes are entities (Objects for non-function things like modules/files/classes/configs/external dependencies, and Functions for exported functions/methods/handlers) and edges are imports and shared/exports. Every entity gets a stable UID (obj-<8hex> or func-<8hex>) anchored in source via a comment marker, so identity survives renames, moves, and reformatting - unlike file paths. Every recorded import stores a short "why" reason in the imported entity's exports/ reverse index, so the graph shows not just what imports what but what is safe to change and who will break.

Each entity gets a small plain-text directory under .dsp/ (a description, an imports list, a shared list of public API entities, and an exports/ reverse index recording who imports it and why) - fully diffable and reviewable with no database needed. Every imported file or artifact (code, images, styles, configs, JSON, wasm) must be represented as an Object; external dependencies are recorded as kind: external without analyzing their internals.

Initial setup requires downloading the standalone dsp-cli.py Python CLI (Python 3.10+) if missing from the project. Bootstrapping an empty .dsp/ traverses the project via DFS from root entrypoints, documenting each file's objects/functions/shared exports/imports before descending into its first non-external import, backtracking when no unvisited local imports remain, and recording external dependencies without descending into node_modules/site-packages.

Its workflow rules: before changing code, find affected entities via search/find-by-source/read-toc and read their description/imports for context; when creating a file, call create-object plus create-function per export plus create-shared; when adding an import, call add-import with a brief why (creating an external object first if needed); when removing an import/export/file, call the corresponding remove command (cascade cleanup is automatic); when renaming/moving a file, call move-entity (the UID never changes); and don't touch DSP for internal-only changes that don't affect purpose or dependencies. Its command categories cover Create (init, create-object, create-function, create-shared, add-import), Update (update-description, update-import-why, move-entity), Delete (remove-import, remove-shared, remove-entity), Navigate (get-entity, get-children --depth N, get-parents --depth N, get-path, get-recipients, read-toc), and Diagnostics (detect-cycles, get-orphans, get-stats).

Worked examples cover setting up DSP and documenting a module, navigating the graph before making changes (search, get-entity, get-children, get-recipients, get-path), and impact analysis before replacing a library (find-by-source to locate an entity, then get-recipients to see every module that imports it and why, enabling systematic replacement). Best practices: update DSP immediately on new files/imports/public API changes, always record a meaningful why reason (where most of the value lives), use kind: external for third-party libraries without analyzing internals, keep descriptions to 1-3 sentences about purpose not implementation, and treat .dsp/ diffs like code diffs - reviewed and kept accurate. It explicitly avoids touching DSP for internal-only changes, changing an entity's UID on rename/move, or creating UIDs for local variables or helpers (only file-level Objects and public/shared entities). It connects naturally to context-compression and context-optimization skills (DSP reduces compression need via targeted retrieval) and to architecture work (DSP captures the import/export boundaries that feed system design decisions).

curl -O https://raw.githubusercontent.com/k-kolomeitsev/data-structure-protocol/main/skills/data-structure-protocol/scripts/dsp-cli.py

python dsp-cli.py --root . init
python dsp-cli.py --root . create-object "src/app.ts" "Main application entrypoint"
python dsp-cli.py --root . create-function "src/app.ts#start" "Starts the HTTP server" --owner obj-a1b2c3d4
python dsp-cli.py --root . add-import obj-a1b2c3d4 obj-deadbeef "HTTP routing"

Use this skill when a project has a .dsp/ directory already set up, the user asks to set up/bootstrap/map a project's structure, creating/modifying/deleting code files in a DSP-tracked project (to keep the graph updated), navigating project structure or dependencies, the user mentions DSP/dsp-cli/.dsp, or performing impact analysis before a refactor or dependency replacement.

Inputs: a codebase to map, or an existing .dsp/-tracked project with a code change (new file, import, export, rename, or deletion) to reflect.

Outputs: a persistent, plain-text .dsp/ graph of entities with descriptions, imports, shared exports, and reverse-indexed import reasons - queryable via the dsp-cli.py CLI for navigation, search, and impact analysis without loading the full source tree.

dsp-cli.py (standalone Python 3.10+ CLI); connects to context-compression, context-optimization, and architecture skills.

Coding agents and developers working in large codebases who need targeted structural navigation and impact analysis instead of loading the entire source tree into context.