/map-codebase

name: map-codebase
description: "Bootstrap LID in an existing (brownfield) codebase. Deep-reads every file in the declared scope, offers lens-based clustering options, generates skeleton LLDs/HLD/EARS bottom-up, then creates arrow docs and prompts the user to flesh out the skeletons. Token-intensive by design. Use when asked to map a codebase, bootstrap arrows, reverse-engineer the design, or start LID on an existing project."
disable-model-invocation: true

Map Codebase (Brownfield Arrow Bootstrap)

This skill maps an existing codebase into the arrow of intent. It works bottom-up: read all the code in scope first, then propose lens-based clusterings for the user to choose among, then generate skeleton docs that describe what actually exists.

See [brownfield-bootstrap.md](references/brownfield-bootstrap.md) for detailed guidance per phase.

Five Critical Rules

These govern every phase. Apply consistently.

1. **Read actual code, don't guess.** Every claim in generated artifacts traces to file/line evidence. Speculation is flagged explicitly rather than presented as fact. 2. **Each STOP is mandatory.** The workflow has multiple stop points. None are optional. Rushing past a stop is how brownfield mapping produces bad LLDs that poison subsequent work. 3. **LLDs describe current reality, not aspirational design.** Output is what the code *is*, not what a greenfield version *would be*. Inferred design decisions carry `[inferred]` markers; known technical debt and behavioral quirks go in Open Questions. 4. **Thoroughness over speed.** Token budget is real but not dominant; skimming produces mappings that miss behaviors and lock in the wrong segmentation. 5. **Humble but guide.** The agent is not the expert on the user's system; the user is. But don't silently defer — when the user's framing conflicts with the evidence, surface the tension with evidence rather than just going along.

At invocation

**Newcomer tour offer.** Unless the state dispatch below sends the person to `/arrow-maintenance`, check whether the memory your harness already placed in your context shows that this person has met LID before: a record of the LID tour, or other memories of them working with LID. If it doesn't, load the `linked-intent-dev` skill, read its `references/tour-offer.md`, and follow it as a setup route. That puts a card at the top of your first message, above the token-intensity warning and your first question. If the `linked-intent-dev` skill isn't installed, make no offer.

Ask one question first:

• **Whole project, or specific parts?**
• **Whole project** → implies Full LID mode. Scope is the entire project.
• **Specific parts** → implies Scoped LID mode. Ask the user to name the parts (directories, file lists, or component names). The declared parts are both the sweep scope and the LID scope going forward.

This question determines scope *and* mode simultaneously — the user is not asked a separate "Full or Scoped?" later at terminal verification. Default to Full (whole project) if the user is undecided.

Then ask:

• **Subagent parallelism** — offer as an option. Recommended for large codebases; single-agent works for smaller ones.

**Token-intensity warning.** Tell the user upfront this is token-intensive by design — reading every file, proposing multiple lenses, drafting skeletons for every segment, multi-step reconciliation. Not a lightweight operation. Users expecting a quick one-shot map should reconsider.

**Undo.** The workflow's STOPs between phases are the undo mechanism — aborting at any STOP leaves nothing written to disk. Agent harnesses also provide their own session-level rewind. LID does not ship a dedicated `/unmap-codebase` command; users roll back via the agent framework's rewind or by reverting a git commit.

State dispatch

Inspect the project before starting:

• **Partial LID docs exist** (HLD or some LLDs, but not complete). Ask the user: treat existing docs as authoritative (draft skeletons only for uncovered segments) or supersede them? Do not silently overwrite.
• **Full LID docs exist but no `docs/arrows/`.** Redirect the user to `/arrow-maintenance` — that command bootstraps the overlay from existing docs without the brownfield sweep. Do not proceed here.
• **No LID docs, no overlay.** Standard brownfield flow (below).

Phase 1 — Sweep (Reconnaissance)

Read **every file** in the declared scope. Not a sample. Sampling risks missing behaviors that only surface in edge-case files and locks in segmentation based on incomplete view.

For each file, record a structured summary:

• **Purpose** — what this file appears to do.
• **Exports** — functions, classes, types, endpoints exposed to other parts of the system.
• **Dependencies** — what the file imports or calls.
• **Data shapes** — structures it produces or consumes.
• **Side effects** — filesystem, network, database, logs.
• **Role** — how this file fits into the larger system (UI component, API handler, background job, pure utility, etc.).
• **Observations** — anything unusual, deprecated-looking, or flagged by comments.

Output: a flat list of observed behaviors with file/line references. **No segmentation attempted here.**

**Capacity constraint handling.** If the declared scope exceeds the invocation's capacity (single-agent context window, or the chosen subagent budget), surface the constraint with concrete sizing evidence, warn the user that a sampled sweep produces lower-quality mapping, and recommend narrowing scope or enabling subagent parallelism. The user may override and proceed with sampling anyway. Under override, preserve state across truncation points via per-subagent files (`docs/arrows/_map-codebase/sweep-{N}.md`) or by incrementally writing arrow-doc partial drafts during reconnaissance — never silently discard information the orchestrator cannot hold.

When subagents ran in parallel, each subagent writes its sweep to its own file; the orchestrator processes them in chunks durin