/exploring-codebases

name: ring:exploring-codebases
description: "Exploring a codebase across phases: scopes the target, detects architecture, components, and layers, deep-dives each discovered perspective, then synthesizes findings into actionable guidance with file:line evidence. Use to understand how a feature or system works before planning changes, or to orient on an unfamiliar codebase. Skip for a single signature lookup, a file-exists check, or reading an error from a known file."

Autonomous Multi-Phase Codebase Exploration

When to use

• Need to understand how a feature/system works across the codebase
• Starting work on unfamiliar codebase or component
• Planning changes that span multiple layers/components
• User asks "how does X work?" for non-trivial X
• Need architecture understanding before implementation

Skip when

• Pure reference lookup (function signature, type definition)
• Checking if specific file exists (yes/no question)
• Reading error message from known file location

Sequence

**Runs before:** ring:writing-plans

Related

**Similar:** dispatching-parallel-agents

Multi-phase approach: **Phase 0 scopes** the target, **Phase 1 discovers** the natural structure of the codebase, **Phase 2 deep-dives** into each discovered area in parallel, **Phase 3 collects** results, and **Phase 4 synthesizes** findings.

**Announce at start:** "Using ring:exploring-codebases for multi-phase autonomous exploration."

How It Works

Phase 1: Discovery (3-4 parallel agents)
  → Architecture, Components, Layers, Organization

Phase 2: Deep Dive (N adaptive agents, one per discovered perspective)
  → Target implementation in each area

Phase 3: Synthesis → Actionable guidance with file:line evidence

Phase 0: Scope Definition

Extract from user request: core subject, context/intent, depth needed. Set exploration boundaries (include/exclude directories).

Phase 1: Discovery Pass

⛔ STOP-CHECK BEFORE DISPATCH

Before emitting any Task call, count the discovery agents you intend to launch in this turn.

• Count MUST equal the number of discovery perspectives you scoped (typically 3-4: Architecture, Components, Layers, Organization).
• If your dispatch count diverges from your scoped count → STOP and reconcile.
• No substitutions, no omissions.

⛔ MUST NOT trickle-dispatch

All discovery agents leave in the SAME TURN, before reading any agent output.

Forbidden sequences:

• Dispatch agent 1 → read result → dispatch agent 2
• Dispatch a subset → wait → dispatch the rest
• Dispatch follow-up agents conditioned on partial output
• Loop sequentially over the discovery angles

If you find yourself about to dispatch a discovery agent in a turn AFTER any agent has already returned a result → STOP. You violated parallel dispatch. Report the violation and mark the phase INCOMPLETE rather than completing the trickle.

Self-verify after dispatch

After the dispatch turn, verify all scoped Task calls were emitted in that single turn. If fewer went out than scoped, the phase did NOT execute correctly. Mark INCOMPLETE and surface the dispatch failure — do NOT silently continue with a partial pool.

Parallel dispatch — atomic batch

Emit all scoped Task calls (the count established in the STOP-CHECK above) in a SINGLE TURN, as one atomic batch.

**If your runtime exposes a `multi_tool_use.parallel` wrapper**, use it to dispatch the complete pool in one wrapped invocation. This is the canonical fan-out mechanism on OpenAI-style tool envelopes and on certain Anthropic SDK consumers — naming it explicitly activates parallel emission on runtimes where trickle-dispatch is the default behavior.

**If your runtime emits parallel tool_use blocks natively** (Claude Code with Claude models), `multi_tool_use.parallel` may not be needed — but naming it is harmless and serves as an enforcement anchor.

The STOP-CHECK, anti-trickle, and self-verify guards above remain binding regardless of which mechanism your runtime uses.

**Dispatch 3-4 discovery agents in a SINGLE turn (parallel):**

**Architecture Discovery:** Find pattern (Hexagonal, Layered, Microservices, Monolith, etc.). Evidence: top-level directory structure, layer separation, file paths. Output: pattern name + confidence + ASCII diagram.

**Component Discovery:** Identify all major components/modules. For each: name, location, responsibility, tech stack, size. Map dependencies between components.

**Layer Discovery:** Within each component, identify layers (HTTP/API, Business Logic, Data Access, Infrastructure). Document how layers are separated and how they communicate.

**Organization Discovery:** Find organizing principle (by layer vs by feature vs by domain). Document file naming conventions, test organization, config locations.

**After Phase 1:** Validate quality — all areas have file:line evidence, no major "unknowns" remain. Determine how many deep-dive agents to launch (one per discovered perspective).

<example> 3-component system → 3 deep-dive agents 4-layer monolith → 4 deep-dive agents (one per layer) 6-service microservices → 6 deep-dive agents </example>

Phase 2: Deep Dive Pass

⛔ STOP-CHECK BEFORE DISPATCH

Before emitting any Task call, count the deep-dive agents you intend to launch in this turn.

• Count MUST equal the number of perspectives discovered in Phase 1.
• If your dispatch count diverges from your scoped count → STOP and reconcile.
• One agent per discovered perspective. No substitutions, no omissions.

⛔ MUST NOT trickle-dispatch

All deep-dive agents leave in the SAME TURN, before reading any agent output.

Forbidden sequences:

• Dispatch agent 1 → read result → dispatch agent 2
• Dispatch a subset → wait → dispatch the rest
• Dispatch follow-up agents conditioned on partial output
• Loop sequentially over the perspective list

If you find yourself about to dispatch a deep-dive agent in a turn AFTER any agent has already returned a result → STOP. You violated parallel dispatch. Report