understand - SKILL.md Agent Skill

name: understand description: Build an accurate mental map of unfamiliar code before changing it. Use when starting work in a codebase or area you don't know well, before editing code whose ripple effects you can't predict, or when the user asks how something works or where something lives.

██╗   ██╗███╗   ██╗██████╗ ███████╗██████╗ ███████╗████████╗ █████╗ ███╗   ██╗██████╗
██║   ██║████╗  ██║██╔══██╗██╔════╝██╔══██╗██╔════╝╚══██╔══╝██╔══██╗████╗  ██║██╔══██╗
██║   ██║██╔██╗ ██║██║  ██║█████╗  ██████╔╝███████╗   ██║   ███████║██╔██╗ ██║██║  ██║
██║   ██║██║╚██╗██║██║  ██║██╔══╝  ██╔══██╗╚════██║   ██║   ██╔══██║██║╚██╗██║██║  ██║
╚██████╔╝██║ ╚████║██████╔╝███████╗██║  ██║███████║   ██║   ██║  ██║██║ ╚████║██████╔╝
 ╚═════╝ ╚═╝  ╚═══╝╚═════╝ ╚══════╝╚═╝  ╚═╝╚══════╝   ╚═╝   ╚═╝  ╚═╝╚═╝  ╚═══╝╚═════╝

Understand before you touch

Editing code you haven't mapped is the fastest route to breakage. Spend a little to orient first, then change with confidence. The goal is a short, accurate map in the project's own vocabulary — not a file dump.

1. Pick the cheapest accurate lens

If CodeGraph MCP tools are available (codegraph_explore, codegraph_search, codegraph_callers, codegraph_impact — present when /codegraph-here has been activated for this repo): prefer codegraph_explore for "how does X work / how does X reach Y" and codegraph_impact before changing a symbol. One call replaces many grep/read round-trips and follows dynamic-dispatch hops grep can't.
Else use forge:graph — forge's always-on, zero-setup live code map. node ~/.claude/skills/forge/scripts/graph.js map for hotspots + module layout, neighbors <file> / impact <file> for blast radius. One call beats grepping around.
Then Grep/Glob for entry points and definitions and Read only the files on the relevant path — don't read the whole tree. (If forge:graph is unavailable, approximate fan-in by grepping a symbol's definition name for its call sites.)
Read the tests and the types/interfaces first. A module's tests state its contract (and the repo's vocabulary) more densely than its implementation; type/interface signatures map the shape faster than reading call sites. Start there, then drop into bodies only as needed.

2. Iterative retrieval — learn the repo's words

The codebase rarely uses your words. Search by the obvious term; if it comes back empty, that's a signal, not a dead end:

Search the concept ("rate limit").
Empty? Find what this repo calls it (skim a nearby module, a config, a test) — maybe it's "throttle" or "quota".
Re-search with the repo's term. Repeat up to ~3 cycles. After 3 empty cycles, stop and ask the user for the in-repo term (or state plainly that the concept may not exist here) — don't keep guessing.

Adopt the repo's vocabulary in everything you write afterward — it makes your map, plans, and PRs legible to the team.

3. Produce the map, then stop

Before editing, state a compact map:

Entry points — where execution starts for this area.
Key modules — the 3-6 that matter, one line each, in the project's vocabulary.
The path — the call/data flow relevant to the task (A → B → C).
Hotspots — the most complex / highest-fan-in pieces you'll be near (handle with extra care).

Validate the map before trusting it: trace one concrete execution end-to-end (a real entry point → the site you'll change) and confirm each hop actually exists in the code. An untraced map is a guess.

If you're lost, zoom out one layer: ask for a map of the relevant modules and their callers rather than diving deeper into one file.

When to skip

A localized edit in code you already understand doesn't need a mapping pass. This is for unfamiliar territory or changes with non-obvious blast radius. Pair with forge:architect (designing new shape) or forge:debug (tracing a failure).