codemap-usage

name	codemap-usage
description	This skill should be used when the user mentions "codebase map", "CODEBASE_MAP.md", "codemap", "dependency map", "file dependencies", "blast radius", "what imports this", "what does this file affect", "what depends on this", "impact of changing this file", "what will break", "find affected files", "side effects in codebase", or asks about navigating or understanding the structure of their codebase for making changes. It teaches Claude how to use the codebase map as a navigational aid during coding sessions.
version	1.0.0

Using the Codebase Map

The codebase map (CODEBASE_MAP.md) is a structural index of the project designed for LLM navigation during agentic coding. It is NOT documentation — every line answers: what is this, what does it touch, and why should you care when making changes.

Before Making Any Change

1. Read the file's map entry — Check its dependencies, exports, and side effects
2. Check inbound dependencies — Find what other files import this one. These are your blast radius.
3. Respect side-effect warnings — Files marked with side effects have hidden behavior (callbacks, event listeners, global state mutations) that won't be visible in the direct call chain
4. Read annotations — Human-written descriptions and gotchas contain critical context that code alone doesn't reveal

How to Read the Map

Dependencies Section (Most Important)

**Dependencies:**
- <- `src/controllers/user.ts` (imports this)     ← INBOUND: will break if you change this file's interface
- -> `internal:./auth/service` (uses: AuthService) ← OUTBOUND: this file depends on AuthService
- -> `external:express` (uses: Router)             ← EXTERNAL: library dependency

Inbound dependencies (<-) tell you blast radius — how many files break if you change this file's exports. Outbound dependencies (->) tell you what this file needs — if those change, this file may break.

Side Effects Section

Files with a Side Effects section have behavior that executes implicitly:

• Lifecycle callbacks (before_save, useEffect, @PostConstruct)
• Event listeners/subscribers
• Background job enqueuing
• Global state mutations

These are the #1 source of bugs during agentic coding. The LLM can't see behavior that triggers outside the direct call chain.

Annotations

• Annotation: Human-curated one-liner about the file's purpose and impact
• Gotcha: Non-obvious behavior that could cause bugs
• Domain notes: Business context not obvious from code

Files marked "Needs annotation" lack human context — treat them with extra caution.

Commands

• /codemap:generate — Generate or regenerate the full codebase map
• /codemap:annotate — Add annotations to unannotated files interactively
• /codemap:status — Check map freshness, annotation coverage, file counts

Two-Layer Architecture

• Layer A (auto-generated): File paths, exports, imports, signatures, side effects. Regenerated on every /codemap:generate run. Disposable.
• Layer B (human annotations): Stored in CODEBASE_MAP.annotations.yml. Preserved across regenerations. Removed files have annotations moved to orphaned section, never deleted.

When the Map is Stale

If the session-start hook reports the map is stale, prompt the user to regenerate before making changes. A stale map may have outdated dependency information that leads to missed blast radius.