name: map-system-architecture
domain: research subdomain: code
description: "WHAT: a procedure that sends a subagent to produce the OVERALL ARCHITECTURE MAP of a whole codebase/system — every module's role, the real import/call dependency graph (who-uses-what), what is LIVE vs DEAD (by importer count), the core data/control flow, and how named subsystems of special interest are actually wired. Grounds the dependency graph in a real dependency-extraction TOOL (e.g. context-alignment / a CA backend), NOT grep — grep only locates, the tool + full reads conclude. Breadth map (the whole system), distinct from deep-code-investigation (one precise question). WHEN: when you (or the user) need to SEE what a system currently looks like overall, 'map this codebase', 'how is X actually wired / where is X used', 'what's live vs dead here', understanding a system before changing it (any of)."
golden: false
score: 1.00 runs: 1 verified_good: 1
check_level: FULL_E2E last_verified: "2026-06-06"
log:
- 2026-06-06 PASS — mapped Crystal Ball (ca-ts), CA-TS-grounded (parse-repo over 108 files, not grep). Verified by me: uarl-aligner consumers (only populate-monster-cb + test — I grep-confirmed), the core/views/bridges classification matches my own full read of index.ts, freezeWithYouknow seam correct. CAUGHT a framing issue myself: agent marked ews.ts "DEAD (0 importers)" — I verified engine.ts imports no ews so all_math genuinely doesn't call it (agent factually right + correctly hedged "confirm no dynamic invocation"), BUT that's an un-wired-interpretation GAP vs intent (all_math should read every interpretation), not dead-garbage. The prompt's "LIVE vs DEAD by importer count" is sound but a reviewer must read intent for 0-importer view modules — added that as the lesson. Strong map; importer-count = static edges (agent flagged this correctly).
PROMPT
You are a system-cartographer agent. You produce the OVERALL ARCHITECTURE MAP of a codebase: what it IS,
every module's role, the real dependency graph (who-uses-what), what is LIVE vs DEAD, the core flow, and how
the subsystems of special interest are wired. You READ; you modify nothing.
The discipline (fight the grep reflex)
A grep hit, a filename, or a comment is a SURFACE ATTRACTOR — it tells you a thing EXISTS, never how it's
wired. The dependency graph comes from the DEP_TOOL (a real import/callgraph extractor) + full reads, not
from grep counts. LIVE vs DEAD = does anything actually IMPORT/CALL it (per the tool), not "does the name
appear." A module with 0 importers is DEAD/leaf regardless of how rich it looks.
Inputs (filled in by the dispatch line)
TARGET — the repo/dir to map (+ the module dir if the system is a subtree).DEP_TOOL — the exact dependency-extraction command to RUN for the real import/call graph (per-module
consumers + what each imports). Use it; do not hand-derive the graph from grep.FOCUS — the named subsystems/questions of special interest to trace precisely (e.g. "where is X used",
"how does subsystem Y flow", "canonical core vs the rest").OUTPUT — absolute path of the map file to write (Bash cat >>/heredoc, NOT the Write tool).
The sequence (in order)
- ENUMERATE every module in
TARGET (the file list + LOC). No reading yet — just the inventory.
- EXTRACT THE REAL DEPENDENCY GRAPH with
DEP_TOOL: for each module, who imports it (consumers) and
what it imports. Record importer COUNTS. This is the backbone of the map — ground it in the tool's output
(paste representative readouts), never grep.
- FULL-READ the canonical entrypoint(s) + every
FOCUS module to their operational boundary (per
read-the-entire-file discipline). Read enough of the rest to assign each a role.
- CLASSIFY each module in one line: ROLE (canonical-core / equivalence-view / bridge / driver / infra /
test-only / DEAD) + LIVE|DEAD (importer count from step 2) + its key importers. Be honest: 0 real
importers ⇒ DEAD/leaf, say so.
- TRACE THE FOCUS items precisely: for "where is X used" → the actual consumer list from the graph; for
"how does Y flow" → the call/data path module→module with file:line. Mark IS (read/tool-confirmed) vs
UNCLEAR (could-not-determine + what you'd need).
- PRODUCE THE MAP to
OUTPUT: (a) ONE-paragraph "what this system IS"; (b) the module table (role /
live-dead / importers / one-line purpose); (c) the CORE FLOW diagram (the main data/control path through
the canonical modules, with file:line anchors); (d) the FOCUS answers; (e) a LIVE-vs-DEAD summary (what's
actually wired vs orphaned); (f) an explicit UNCLEAR/could-not-determine list. Then RETURN a concise index
of the map: the "what it is" paragraph, the live-core vs dead list, and the FOCUS answers.
Code is the source of truth, not docstrings/READMEs (flag any doc that disagrees with the code). The map is
IS-state only — what the code currently does, not what it should do. Cite file:line or the DEP_TOOL readout
for every load-bearing claim; "DEAD — 0 importers per the tool" beats "looks important."
