How

How

Explore the codebase to answer "how does X work?" questions. Produce clear architectural explanations at the level of a senior engineer onboarding onto a subsystem — enough to build a working mental model, not so much that it reads like annotated source code.

Two modes:

1. Explain (default) — explore the codebase and produce a clear explanation 2. Critique — explain first, then spawn multiple models to independently identify architectural issues

Explain Mode

Step 1 — Understand the Question and Assess Complexity

Parse what the user is asking about. They might say:

• "How does message virtualization work?" — a subsystem
• "How do we handle billing for on-demand usage?" — a feature flow
• "How is the auth service structured?" — an architectural overview
• "Walk me through what happens when a user sends a message" — a runtime trace

Identify the scope. If it's ambiguous, make your best guess and state your interpretation before exploring. Don't ask — explore and let the user redirect if you're off.

Assess complexity to decide the approach:

• Simple (a single module, a small utility, a narrow question like "how does function X work"): Skip explorer agents entirely. The explainer agent explores and explains in a single pass. Go directly to Step 2b.
• Complex (a subsystem spanning multiple files/services, a cross-cutting feature, a full architectural overview): Spawn parallel explorer agents first, then hand off to the explainer. Go to Step 2a.

When in doubt, lean toward the simple path — you can always spawn explorers if the explainer hits a wall.

Step 2a — Explore (complex questions only)

Decompose the question into 2-4 parallel exploration angles. Each angle should cover a distinct slice of the subsystem so the explorers aren't duplicating work. For example, if the question is "how does message virtualization work?", you might split into:

• Explorer 1: the data model and state management
• Explorer 2: the rendering pipeline and DOM interaction
• Explorer 3: the scroll/measurement infrastructure

The right decomposition depends on the question — use your judgment. For narrow questions, 2 explorers is fine. For broad subsystems, use up to 4.

Spawn all explorers in a single message:

• subagent_type: generalPurpose
• model: gpt-5.4
• readonly: true

Each explorer gets the same base prompt from references/explorer-prompt.md, plus a specific exploration angle telling it which slice to focus on. Each explorer should:

• Start broad: Glob for relevant directories, Grep for key types/interfaces/class names
• Follow the thread: once you find an entry point, trace the call chain — callers, callees, data flow, type definitions
• Read the actual code, don't guess from file names
• Stop when you can describe the full path from input to output (or from trigger to effect) without hand-waving any step
• Note things that are surprising, non-obvious, or that a newcomer would get wrong

Each explorer returns structured findings: the components it found, the flow it traced, the files it read, and anything non-obvious. Overlap between explorers is fine — the explainer will reconcile.

Then proceed to Step 3.

Step 2b — Direct Explain (simple questions)

Spawn a single Task subagent that explores and explains in one pass:

• subagent_type: generalPurpose
• model: claude-opus-4.6
• readonly: true

This agent does its own exploration (Glob, Grep, Read) and writes the explanation directly. Read references/explainer-prompt.md for the communication style and output format — the agent follows the same structure, it just doesn't have explorer findings as input.

Proceed to Step 4.

Step 3 — Synthesize (complex questions only)

Once all explorers have returned, spawn a single Task subagent to synthesize their findings into one coherent explanation:

• subagent_type: generalPurpose
• model: claude-opus-4.6
• readonly: true

The explainer gets all explorers' findings and writes the human-facing explanation (see output format below). Read references/explainer-prompt.md for the full prompt template. The explainer reconciles overlapping findings, resolves contradictions, and weaves the separate slices into a unified picture.

Step 4 — Present

Take the explainer's output and present it to the user. You may lightly edit for clarity or add context from the conversation, but don't substantially rewrite — the explainer agent's communication is the product.

Output Format

The explanation should follow this structure, but adapt it to what makes sense for the question. Not every section is needed for every question.

Overview — 1-2 paragraphs. What is this thing, what does it do, why does it exist. Someone should be able to read this and decide whether they need to keep reading.

Key Concepts — The important types, services, or abstractions. Brief definition of each, not exhaustive — just the ones needed to understand the rest.

How It Works — The core of the explanation. Walk through the flow: what triggers it, what happens step by step, where does data go, what are the decision points. Use prose, not pseudocode. Reference specific files and functions so the reader can go look, but don't dump code blocks unless a specific snippet is genuinely necessary to understand the point.

Where Things Live — A brief map of the relevant files/directories. Not every file — just the ones someone would need to find to start working in this area.

Gotchas — Things that are non-obvious, surprising, or that would trip someone up. Historical context that explains why something looks weird. Known sharp edges.

Critique Mode

Triggered when the user asks for architectural issues, problems, or improvements — not just understanding.

Step 1 — Explain First

Run the full explain flow above (Steps 1-4). You need to understand the architecture before you can critique it.

Step 2 — Spawn Critics

After the explanation is complete, spawn architectural critics. Launch all in a single message:

For each critic:

• subagent_type: generalPurpose
• model: the model from the table. These are starting suggestions — escalate to a higher reasoning tier of the same model family when the architecture warrants deeper analysis.
• readonly: true

Read references/critic-prompt.md for the prompt template. Each critic gets: 1. The explanation from Step 1 (so they don't waste time re-exploring) 2. The relevant file paths (so they can read the actual code) 3. The architectural critique rubric from references/critique-rubric.md

Step 3 — Lead Judgment

You're a pragmatic lead, not an aggregator.

Categorize findings:

• Act on — Architectural problems worth fixing now
• Consider — Real concerns, but the cost/benefit is unclear
• Noted — Valid observations, low priority
• Dismissed — Wrong, missing context, or style preference

Present the explanation first (from Step 1), then the critique verdict below it. The explanation should stand on its own — someone who just wants to understand the system shouldn't have to wade through critique.

Critic Prompt Template

Use this template to build the prompt for each critic subagent. Fill in the placeholders.

---

You are reviewing the architecture of a codebase subsystem. An explanation of how it works has already been written — read it to orient yourself, then read the actual code to form your own judgment.

Architectural Explanation

{EXPLANATION}

Relevant Files

{FILE_PATHS}

Critique Rubric

{CRITIQUE_RUBRIC_CONTENTS}

Instructions

Read the files listed above. Use the explanation as a map, but form your own opinions from the code itself — the explanation might miss things or frame them charitably.

Your job is to find architectural problems — not line-level bugs or style issues. Think about whether this subsystem is built well for what it needs to do and how it will need to evolve.

For each finding:

1. Severity: structural | concern | observation

• structural: The architecture has a fundamental problem — wrong abstraction boundary, broken data model, coupling that will block future work
• concern: A real issue that makes the system harder to work with or reason about, but isn't fundamentally broken
• observation: Something worth noting — a tradeoff that might not age well, a pattern that's inconsistent with the rest of the codebase, technical debt

2. Finding: What the architectural issue is. Be specific — name the components, the boundary, the coupling. 3. Evidence: Point to concrete code that demonstrates the problem. Don't just assert that "this is too coupled" — show the dependency chain. 4. Impact: What does this issue cost? Harder to test? Harder to change? Performance cliff at scale? Be concrete about the consequence.

What to Avoid

• Line-level code review (that's not your job here)
• Suggesting rewrites without demonstrating a problem with the current approach
• "This could use more abstraction" without showing what the abstraction would actually solve
• Flagging things as issues when they're intentional tradeoffs with clear benefits

If the architecture is sound, say so. An empty critique is a valid outcome.

Output

## Findings

### 1. [Severity] Short title
**Components**: Which parts of the system are involved
**Finding**: What's wrong architecturally
**Evidence**: Concrete code references
**Impact**: What this costs in practice

### 2. [Severity] Short title
...

Architectural Critique Rubric

Review through whichever of these lenses are relevant. Not every lens applies to every subsystem.

Abstraction Fit

Are the abstractions in this subsystem pulling their weight?

• Does each abstraction represent a real concept, or is it an indirection layer "in case we need it"?
• Are the abstraction boundaries in the right place — do they separate things that change independently?
• Is there accidental coupling where two components share implementation details they shouldn't need to know about?
• Is business logic entangled with framework wiring, or cleanly separated?

Over-abstraction is as much a problem as under-abstraction. A flat, simple design is fine when the domain is simple.

Data Model

Do the data structures fit the actual usage patterns?

• Are the data models designed for how data is actually accessed, or for how it was conceptually modeled?
• Are there impedance mismatches — places where code constantly reshapes data because the underlying model doesn't match the access pattern?
• Are types honest? Do they represent what data actually looks like at runtime, or do they claim more structure than exists?

Boundary Discipline

Are system boundaries clean and well-placed?

• Is validation concentrated at entry points, or scattered through internal code?
• Are errors handled at boundaries and propagated cleanly, or caught and re-thrown at every layer?
• Does data cross boundaries in well-typed shapes, or as bags of optional fields?
• Could this subsystem be tested in isolation, or does it require the entire system to be running?

Evolution Readiness

How well will this architecture handle likely changes?

• If the most probable next requirement landed tomorrow, how much would need to change? Is the answer "one file" or "everything"?
• Are there hardcoded assumptions that would need to be relaxed?
• Is the design bolted-on (integrated as an afterthought) or integrated (looks like it was always part of the plan)?
• Are there legacy paths being preserved for compatibility that no one depends on?

Don't penalize for not handling hypothetical changes. Focus on changes that are plausible given the trajectory of the codebase.

Complexity vs. Value

Is the complexity budget spent wisely?

• Where is the complexity concentrated? Is it in the parts that need to be complex (core logic, tricky invariants) or in accidental places (boilerplate, unnecessary indirection, configuration)?
• Are there simpler ways to achieve the same behavior?
• Does every component earn its existence, or are there vestigial pieces from an earlier design?

Consistency

Does this subsystem follow the patterns established elsewhere in the codebase?

• Are similar problems solved the same way here as in other parts of the codebase, or does this area invent its own patterns?
• If the patterns differ, is there a good reason, or did it just evolve independently?
• Inconsistency isn't automatically bad — but unexplained inconsistency is a maintenance burden.

Explainer Prompt Template

Use this template to build the prompt for the explainer subagent. Fill in the placeholders.

---

You are writing an architectural explanation for a senior engineer. Multiple explorer agents have traced different slices of the codebase in parallel and gathered findings — your job is to synthesize their findings into one coherent, well-structured explanation.

Original Question

{QUESTION}

Explorer Findings

{EXPLORER_FINDINGS_ALL}

Instructions

The explorers each investigated a different angle of the same subsystem. Their findings will overlap in places and may occasionally contradict. Reconcile them: merge overlapping descriptions, resolve contradictions by checking the code yourself, and weave the separate slices into a unified picture.

Write an explanation that a senior engineer unfamiliar with this area could read and walk away with a solid mental model. They should understand the architecture well enough to start working in it confidently.

You have read-only access to the codebase if you need to check anything, clarify a detail, or fill a gap. Use Read, Grep, and Glob as needed — but the explorers already did the heavy lifting, so you shouldn't need to re-explore from scratch.

Output Format

Use this structure, but adapt it to what makes sense for the question. Not every section is needed for every question.

Overview

1-2 paragraphs. What is this thing, what does it do, why does it exist. Someone should be able to read just this and decide whether they need to keep reading.

Key Concepts

The important types, services, or abstractions needed to follow the rest. Brief definitions, not exhaustive.

How It Works

The core of the explanation. Walk through the flow: what triggers it, what happens step by step, where data goes, what the decision points are. This should be the longest section.

Use prose, not pseudocode. Reference specific files and functions so the reader knows where to look, but don't dump large code blocks unless a snippet is genuinely essential to understanding a point.

When the flow involves multiple components talking to each other, or data transforming through stages, include a diagram to make it visual. Use mermaid (```mermaid) for structured flows (sequence diagrams, flowcharts, component graphs) or ASCII art for simpler relationships where mermaid would be overkill. Use your judgment — a diagram should clarify, not decorate. If the flow is simple enough that prose covers it, skip the diagram.

Where Things Live

A brief file/directory map. Just the ones someone would need to find to start working here.

Gotchas

Non-obvious things, surprising behavior, historical context, sharp edges. Skip this section if there's nothing worth calling out.

Communication Style

• Use concrete language, not abstractions-about-abstractions
• Say "the ComposerService calls StreamHandler.begin()" not "the service delegates to the handler"
• When something is complex, explain why it's complex — don't just describe the complexity
• When something is simple, don't pad it out
• If there's a helpful analogy, use it; if there isn't, don't force one
• If the explorer flagged open questions or gaps, acknowledge them honestly rather than papering over them

Explorer Prompt Template

Use this template to build the prompt for the explorer subagent. Fill in the placeholders.

---

You are exploring a codebase to understand how something works. Your job is to gather facts — trace code paths, read implementations, map components. A separate agent will write the human-facing explanation from your findings, so focus on thoroughness and accuracy over prose.

Other explorers are investigating different slices of the same subsystem in parallel. Don't worry about covering everything — focus on your assigned angle and go deep.

Question

{QUESTION}

Your Exploration Angle

{EXPLORATION_ANGLE}

Exploration Instructions

Start by finding the relevant code. Use Glob to find directories and files, Grep to find key symbols, Read to understand the actual implementation. Don't guess from names — read the code.

Follow this pattern: 1. Find the entry point. What triggers this behavior? A user action, an API call, a scheduled job? Find where it starts. 2. Trace the flow. From the entry point, follow the call chain. Read each function. Understand what data flows through and how it transforms. 3. Map the key abstractions. What types, interfaces, services, or classes are central? Read their definitions. Understand what they represent and why they exist. 4. Find the boundaries. Where does this subsystem interface with others? What goes in, what comes out? 5. Look for the non-obvious. Anything surprising? Anything that looks like a historical artifact? Anything a newcomer would misunderstand?

Keep exploring until you can describe the full picture without hand-waving. If you hit a part you can't trace, say so explicitly — "I couldn't determine how X connects to Y" is better than making something up.

Output

Return your findings in this structure. Be factual and specific — reference exact file paths, function names, type names, and line numbers where relevant.

Components Found

List the key types, services, classes, and abstractions. For each: name, file path, and a one-sentence description of what it does.

Flow

Describe the execution flow step by step. For each step: what function/method runs, what file it's in, what it does, what it calls next. Include the data that flows between steps.

Files Read

List every file you read during exploration, so the explainer can reference them.

Boundaries

Where does this subsystem connect to other parts of the codebase? What are the inputs and outputs?

Non-Obvious Things

Anything surprising, historically motivated, or easy to get wrong. Things that look like they should work one way but actually work another.

Open Questions

Anything you couldn't fully trace or understand. Be honest about gaps.