Map Module

Produce a "how it works today" snapshot. Keep decision history in the paired .claude/decisions/<module-id>.md; do not turn the map into a design proposal or changelog.

Read references/report-contracts.md before dispatching research or verification tasks. Use its report contracts and final map template.

Choose the mode

• Use full mapping for a new map, an explicitly requested full refresh, broad architectural changes, an unverified existing map, or a change whose impact cannot be bounded confidently.
• Use targeted refresh when an existing verified map is being maintained after a bounded code change and only a limited set of mapped claims may have changed.
• If a targeted assessment proves that all mapped claims remain accurate, leave the map unchanged and report that no refresh was needed.

Load context progressively

• Start with repository and module inventories, heading outlines, symbol searches, and file sizes to establish the likely boundary before opening broad source files.
• Read the selected module's current map and paired decision file separately and to completion, chunking large files when needed. Do not concatenate them with large source files in one command.
• Inspect exact definitions, registration points, direct callers, direct callees, and relevant tests before opening adjacent files or related maps.
• Expand context only to answer a named unresolved question about a boundary, contract, lifecycle edge, dependency, invariant, or mapped claim. Record the question before expanding.
• If tool output is truncated, do not treat the file or result as covered; repeat with focused ranges until the required content is read.
• Stop loading when the subsystem boundary and required claims have enough first-hand evidence for the selected mode. More context is not itself verification.

Ownership and collaboration

• Keep synthesis, verdict judgment, file edits, module registration, and the final response in the root agent.
• Use read-only Explore subagents (the Agent tool with subagent_type: Explore) only for code research and verification. Full mapping uses the research and verification waves below. A bounded targeted refresh may be verified locally; use explorers when the affected flow crosses concerns or repositories. Tell every explorer not to edit files.
• Run explorers in bounded waves: launch one wave's agents in a single message so they run concurrently, wait for the wave to report, then dispatch the next. Reuse an explorer through SendMessage only for a related concern.
• Make verification independent: do not let an explorer verify its own research concern. Prefer fresh explorers; if capacity is constrained, cross-assign unrelated claims.
• Before mapping multiple modules or a very large subsystem, state the expected concern and verification counts so the cost is visible.

Phase 0: Scope and mode

1. Resolve <module-id> and the subsystem root. Derive them from the request and repository when safe; ask only if different interpretations would materially change the map.
2. Read .claude/MODULES.md, the paired decision file if present, and the current map if refreshing. Read a related map only when an identified boundary or unresolved question crosses into it.
3. Confirm that the root exists at the current HEAD. If it is missing, inspect Git history and symbol moves to distinguish a deleted historical subsystem from a renamed successor. Do not map a historical commit or switch module ids without user confirmation.
4. Inventory the root with the Glob tool (or rg --files), then inspect class declarations, constructors or registration points, public entry points, core state fields, and file sizes. Skim key files to confirm boundaries.
5. Choose full mapping or targeted refresh using the criteria above. If the current task's change boundary cannot be separated from unrelated working-tree changes, do not guess; use full mapping or report the unresolved boundary.
6. For full mapping, split by concern, not by file. Name specific classes, methods, states, and flows in each focus:
   • small subsystem (up to about 5 files): 3 research concerns;
   • medium subsystem: 4 concerns;
   • large subsystem or god-files: 5–6 concerns.
7. Build a short shared context containing the module purpose, root, core files, known related maps, and any external dependency source supplied through the task or environment.

Targeted refresh

Skip the full research and adversarial-verification phases only when the targeted-refresh criteria are met.

1. Use the current task and its staged and unstaged diff to identify the implementation change boundary. Preserve unrelated user changes.
2. Compare that boundary with the current map and list every potentially affected claim about responsibilities, key types, public entry points, lifecycle or data flow, inbound or outbound dependencies, invariants, bugs, open questions, and verification residuals.
3. Reopen the relevant source and verify every affected claim plus its immediately adjacent edges. Inspect dependency source supplied through the task or shared context when required. If required external source is unavailable, retain a concise residual under To verify instead of guessing. Do not infer that a claim is unchanged solely because its named file was untouched.
4. Escalate to full mapping if the affected claims span most sections, reveal an undocumented subsystem boundary, depend on an unverified baseline, or the internal impact cannot be checked from available project source. Missing external source alone is not a reason to escalate.
5. If no documented claim changed, do not edit the map.

6. Otherwise, patch only the affected statements and sections. Preserve the previous full Verified line and keep exactly one Maintained line after it, separated by a bare > line:

   > Verified: YYYY-MM-DD (verification summary)
   >
   > Maintained: YYYY-MM-DD (targeted verification only since the full mapping: <areas changed since then, this change last>)

   Rewrite the whole line on each refresh; never append to it. Keep it to one sentence of about 250 characters at most, naming the areas changed since Verified as they stand now, not each step that led there, and leaving out changes that later ones undid: the commits and the decision file hold the history. If the areas no longer fit in that sentence, the map rests on an unverified baseline; escalate to full mapping (step 4).

7. Keep evidence out of the map, run the validation steps below, and report which mapped claims changed. Do not commit or push unless the user explicitly asks.

Phase 1: Full research

1. Dispatch one explorer per concern, in bounded waves, using the reader task contract.
2. Require first-hand source inspection and evidence as repository-relative path:line in the research report. Evidence is for synthesis confidence and must not enter the final map.
3. Collect every report. If a reader fails, cover the gap locally or mark the concern for extra first-hand verification; never synthesize a failed concern as established fact.
4. Synthesize a baseline map using the final map template. Merge overlaps, distinguish public names from class or package names, and place uncertainty only under Open questions or To verify.
5. Write or update .claude/maps/<module-id>.md with the Write tool (new file) or the Edit tool (existing file).

Phase 2: Full adversarial verification

1. Select checkable claims from the baseline:
   • state transitions and lifecycle edges;
   • public contracts and entry points;
   • routing, error codes, defaults, feature gates, and implementation differences;
   • invariants, suspected bugs, and all inferred or unverified assertions.
2. Use 8–10 claims for a small subsystem, 12–15 for a medium subsystem, and at least 15 for a large subsystem. Weight failed-reader and state-machine concerns more heavily.
3. Group claims into independent verifier assignments by concern and dispatch bounded explorer waves using the verifier task contract. Require one verdict per claim and fresh source reads.
4. Judge the returned evidence yourself. Treat low-confidence or unsupported verdicts as unresolved even if an explorer labels them confirmed.

Phase 3: Full patch

Apply verdicts as follows:

• confirmed: promote important facts into the body and remove matching To verify items.
• refuted or partial: correct the body with correctedStatement.
• external_unverifiable: retain a concise residual under To verify.
• isBug: true: add one impact-oriented item under Confirmed bugs / technical debt.

Add or replace > Verified: YYYY-MM-DD (verification summary) only after the full verification pass, and remove a stale > Maintained: line together with the bare > line above it. Keep genuinely open design or intent questions under Open questions. Do not claim full verification if assignments failed; state the residual explicitly.

Use the Edit tool for patches. Match the existing text exactly, punctuation included, when replacing it. For large section rewrites, anchor on unique headings; if a match is ambiguous, widen the anchor rather than guessing.

Phase 4: Register, connect, and validate

1. If the module is new, add it to the matching section of .claude/MODULES.md only after the map is verified. Keep the registry near its documented size and describe the verified boundary.
2. Check whether the root CLAUDE.md tells Claude Code to resolve affected module IDs, read the matching map and decision files before editing, and conditionally run a targeted map refresh when implementation changes invalidate mapped facts. If those rules are missing or only mention decisions, do not edit CLAUDE.md. Tell the user that /commit-context will propose the canonical Knowledge Loop Conventions upgrade when the map is staged for commit. If /commit-context is unavailable, warn that the map will not be consumed automatically.
3. Confirm that the final map:
   • follows the reference template;
   • contains no source path:line citations;
   • separates facts, confirmed bugs, open questions, and external residuals;
   • pairs to the same module id under .claude/decisions/.
4. Run git diff --check and inspect the focused diff for the map and registry.
5. Do not commit or push unless the user explicitly asks. Mention confirmed risks that belong in a future Decision block.

Failure handling

• If all readers fail, stop before writing a map and report the research blocker.
• If one reader fails, recover through local inspection or extra verifier coverage and disclose any remaining gap.
• If dependency source cannot be found, record what source is missing; do not guess or mark it confirmed.
• If the requested root exists only in history, stop after identifying the likely successor and ask whether to map the historical snapshot or the current subsystem.
• If code and an existing map disagree, trust current source, update the map, and retain historical rationale only in the decision file.