Autonomous Two-Phase Codebase Exploration

Overview

Traditional exploration assumes structure upfront or explores sequentially. This skill takes an autonomous two-phase approach: discover the natural perspectives of the codebase first, then deep dive into each discovered perspective with targeted explorers.

Core principle: Let the codebase reveal its own structure, then explore each structure element thoroughly with adaptive parallel agents.

MANDATORY ANNOUNCEMENT at start:

"I'm using the ring:exploring-codebase skill to autonomously discover and explore the codebase structure.

Before proceeding, I've checked the Red Flags table and confirmed:

• [X] Production pressure makes me WANT to skip discovery → Using skill anyway
• [X] I think I 'already know' the structure → Discovery will validate assumptions
• [X] This seems like a simple question → Location without context is incomplete
• [X] Colleague gave me high-level info → Discovery finds what they forgot

The skill's core principle: When pressure is highest, systematic approach matters most."

🚨 Red Flags: When You're About to Make a Mistake

STOP and use this skill if you catch yourself thinking:

| Red Flag Thought | What It Means | Do This Instead | |------------------|---------------|-----------------| | "I already know this architecture" | ⚠️ Dunning-Kruger | Run discovery to validate assumptions | | "Grep is faster for this simple question" | ⚠️ Optimizing for feeling productive | One exploration > multiple follow-ups | | "Production is down, no time for process" | ⚠️ Panic mode | High stakes demand MORE rigor | | "Colleague told me the structure" | ⚠️ Trusting abstractions | Discovery finds what they forgot | | "Being pragmatic means skipping this" | ⚠️ Conflating speed with value | Real pragmatism = doing it right | | "This is overkill for..." | ⚠️ Underestimating complexity | Incomplete understanding compounds | | "I'll explore progressively if I get stuck" | ⚠️ Reactive vs proactive | Discovery prevents getting stuck | | "Let me just quickly check..." | ⚠️ Ad-hoc investigation trap | Systematic > ad-hoc |

If 2+ red flags triggered: YOU NEED THIS SKILL.

💥 Violation Consequences: Real Costs of Skipping

"What's the worst that could happen if I skip discovery?"

Consequence 1: The Cascade Effect

Scenario: Skip discovery → Fix in wrong component → Break integration → New production issue

Example:

• Bug: "Account creation failing"
• Assumption: "It's in onboarding component"
• Reality: Transaction component has new validation that breaks onboarding
• Your fix: Modify onboarding (wrong component)
• Result: Original bug persists, NEW bug in onboarding, 2 issues instead of 1

Discovery would have revealed: Transaction component owns the validation now.

Consequence 2: The Multiple Round-Trip Effect

Scenario: Grep for location → Answer question → User asks follow-up → Grep again → Another follow-up

Example:

• Q1: "Where is validation?" → Grep → Answer: validation.go:45
• Q2: "How does it integrate?" → Read files → Answer: "Called from use case"
• Q3: "What else validates?" → Grep again → Answer: "Assert package + HTTP layer"
• Total: 3 round trips, 15 minutes, incomplete mental model

Exploration would have provided: All answers in one comprehensive document, 10 minutes total.

Consequence 3: The Stale Knowledge Effect

Scenario: "I already know" → Work based on old mental model → Code has changed → Wrong implementation

Example:

• Your knowledge: "3 components (onboarding, transaction, crm)"
• Reality: New audit component added last month for compliance
• Your fix: Modify account creation in onboarding
• Missing: Audit component now logs all account operations
• Result: Account created but not audited, compliance violation

Discovery would have revealed: 4 components now, audit is mandatory.

Consequence 4: The Hidden Dependencies Effect

Scenario: Skip discovery → Miss shared libraries → Duplicate code → Technical debt

Example:

• Task: Add account validation rule
• Grep finds: create-account.go has validation
• You add: New validation in same file
• Discovery would reveal: pkg/validator/account.go has shared validation library
• Result: Duplicate logic, inconsistent validation across codebase

Discovery would have revealed: Centralized validation library for reuse.

Cost Summary Table

| Skip Reason | Time "Saved" | Actual Cost | Net Loss | |-------------|--------------|-------------|----------| | "I already know" | 6-10 min | 2+ hours debugging stale knowledge | -110 to -114 min | | "Simple question" | 6-10 min | 3 round trips × 5 min each = 15 min | -5 to -9 min | | "Production emergency" | 6-10 min | Wrong fix + cascade = 2+ hours | -110 to -114 min | | "Colleague told me" | 6-10 min | Missing component/library = 1+ hour rework | -50 to -54 min |

Pattern: Every "time-saving" skip costs more time than it saves.**

The Two-Phase Flow

Phase 1: Discovery Pass (Meta-Exploration)

Goal: Understand "What IS this codebase?"

Launch 3-4 discovery agents to identify:

• Architecture pattern (hexagonal, layered, microservices, etc.)
• Major components/modules
• Natural boundaries and layers
• Organization principles
• Key technologies and frameworks

Output: Structural map of the codebase

Phase 2: Deep Dive Pass (Adaptive Exploration)

Goal: Understand "How does [target] work in each discovered area?"

Based on Phase 1 discoveries, launch N targeted explorers (where N adapts):

• One explorer per discovered perspective/component/layer
• Each explorer focuses on the target within their scope
• Number and type of explorers match codebase structure

Output: Comprehensive understanding of target across all perspectives

When to Use

Decision flow:

• Need codebase understanding? → Is it trivial (single file/function)? → Yes = Use Read/Grep directly
• No → Is it unfamiliar territory or spans multiple areas? → Yes = Two-phase exploration
• Are you about to make changes spanning multiple components? → Yes = Two-phase exploration

Use when:

• Understanding how a feature works in an unfamiliar codebase
• Starting work on new component/service
• Planning architectural changes
• Need to find where to implement new functionality
• User asks "how does X work?" for complex X in unknown codebase

Don't use when:

• Pure reference lookup: "What's the signature of function X?"
• File existence check: "Does utils.go exist?"
• Reading known error location: "Show me line 45 of errors.go"

COMMON TRAPS - These SEEM like valid skip reasons but are NOT:

❌ Trap 1: "Simple Question About Location"

Rationalization: "User just asked 'where is X?' - grep is faster"

Reality: Location questions lead to "how does X work?" next

• Question: "Where is validation logic?"
• Grep answer: validation.go:45
• Follow-up: "How does it integrate with the system?"
• Follow-up: "What else validates this?"
• Result: 3 questions, incomplete picture, wasted time

Counter: Run exploration once, answer current + future questions.

❌ Trap 2: "I Already Know the Architecture"

Rationalization: "I worked here before, discovery is redundant"

Reality: Prior knowledge is dangerously incomplete

• You know high-level (components exist)
• You don't know details (how they're wired, what changed)
• Assumptions about "known" code cause most bugs

Counter: Discovery validates assumptions and reveals what changed.

❌ Trap 3: "Production Emergency, No Time"

Rationalization: "Production is down, skip the process"

Reality: High stakes demand MORE rigor, not less

• 6-10 min discovery prevents hours of wrong assumptions
• Production bugs from incomplete context cost >> discovery time
• "I know where to look" under stress = peak Dunning-Kruger

Counter: See "When Pressure is Highest" section below.

❌ Trap 4: "Colleague Told Me Structure"

Rationalization: "They said '3 microservices', why rediscover?"

Reality: High-level descriptions miss critical details

• "3 microservices" doesn't mention shared libraries, background jobs, API gateways
• Mental models are abstractions, not complete maps
• People forget to mention "obvious" infrastructure

Counter: Use colleague info as validation context, not replacement for discovery.

When Pressure is Highest, Use Skill Most

CRITICAL INSIGHT: Production emergencies DEMAND systematic understanding.

The Emergency Trap

False logic: "Production down → Skip process → Fix faster" True logic: "Production down → Need accuracy → Use systematic approach"

Why Discovery Matters MORE Under Pressure

| Shortcut Path | Systematic Path | |---------------|-----------------| | Grep "CreateAccount" (30 sec) | Run two-phase exploration (6-10 min) | | Read 2-3 files (2 min) | Get complete architecture + target impl | | Make assumption-based fix (10 min) | Fix with full context (5 min) | | Fix breaks something else (2 hours) | Fix correct first time | | Total: 2+ hours + new bugs | Total: 15-20 minutes, done right |

The "Surgeon Textbook" Analogy is Wrong

Bad analogy: "Surgeon doesn't read textbook while patient bleeds" Correct analogy: "Surgeon checks vitals before operating"

Discovery is NOT reading theory - it's gathering critical context:

• ✅ Discovery = Checking patient vitals (essential context)
• ❌ Reading textbooks = Reading unnecessary theory

You wouldn't skip vitals because "emergency" - same principle applies here.

Production Emergency Protocol

When production is down:

1. Acknowledge the pressure - "This is urgent, I feel pressure to skip discovery"
2. Recognize the trap - "That pressure is EXACTLY when I need systematic approach"
3. Invest 6-10 minutes - Run two-phase exploration
4. Fix with confidence - Full context prevents cascading failures

Reality check: If you don't have 6-10 minutes for discovery, you don't have 2+ hours to undo wrong fixes.

Real vs False Pragmatism

False Pragmatism (Shortcuts that Backfire)

| Shortcut | Seems Pragmatic | Actual Result | |----------|-----------------|---------------| | "Skip discovery, I already know" | Saves 6-10 min | Hours debugging wrong assumptions | | "Grep for simple questions" | Faster than exploration | Multiple follow-up questions, incomplete picture | | "Production emergency, no process" | Fixes faster | Wrong fix, breaks more things | | "Colleague told me structure" | Use existing knowledge | Miss shared libs, background jobs, actual impl |

Real Pragmatism (Invest to Save)

| Systematic Approach | Costs | Saves | |---------------------|-------|-------| | 6-10 min two-phase exploration | 6-10 minutes | Hours of debugging wrong assumptions | | Complete understanding first | Discovery time | Multiple follow-up questions | | Systematic under pressure | Feeling "slow" | Fixing wrong thing, cascading failures | | Validate colleague's mental model | Discovery vs assumption | Missing critical infrastructure |

Real pragmatism = Doing it right when stakes are high.

False pragmatism = Taking shortcuts that create bigger problems.

When Pragmatism Tells You to Skip...

If you think "being pragmatic means skipping this," ask:

1. Am I conflating "fast" with "good"? Speed without accuracy is just fast failure.
2. Am I optimizing for feeling productive? Grep gives quick dopamine, but incomplete understanding.
3. Am I making excuses under pressure? High stakes demand MORE rigor, not less.
4. Am I assuming I know more than I do? Dunning-Kruger peaks under stress.

If you answered yes to any: Use the skill anyway.

Rationalization Table

When you're tempted to skip the skill, check this table:

| Rationalization | Why It Feels Right | Why It's Wrong | Counter | |-----------------|--------------------|-----------------|---------| | "I already know the architecture" | You worked here before | Prior knowledge is high-level abstractions | Discovery reveals what you don't know to ask | | "Simple question, grep is faster" | Just need a file location | Leads to follow-ups, incomplete picture | One exploration answers current + future questions | | "Production emergency, no time" | Every second counts | Wrong fix wastes hours, creates new bugs | 6-10 min discovery prevents hours of wrong assumptions | | "Colleague told me the structure" | They work here, they'd know | Mental models miss details (shared libs, jobs) | Use as validation context, not replacement | | "Being pragmatic not dogmatic" | Process shouldn't be rigid | Shortcuts under pressure cause bigger problems | Real pragmatism = right approach when stakes high | | "Match tool to scope" | Simple task = simple tool | Context-free answer requires follow-ups | Comprehensive once > multiple partial searches | | "Skip discovery to save time" | 3-5 min vs 6-10 min | Saving 5 min, losing hours on wrong assumptions | False economy - incomplete understanding compounds | | "Progressive investigation works" | Start narrow, expand if stuck | Ad-hoc misses systematic patterns | Discovery first prevents getting stuck |

Process

Copy this checklist to track progress:

Two-Phase Exploration Progress:
- [ ] Phase 0: Scope Definition (exploration target identified)
- [ ] Phase 1: Discovery Pass (structure discovered - 3-4 agents)
- [ ] Phase 2: Deep Dive Pass (N adaptive explorers launched)
- [ ] Phase 3: Result Collection (all agents completed)
- [ ] Phase 4: Synthesis (discovery + deep dive integrated)
- [ ] Phase 5: Action Recommendations (next steps identified)

Phase 0: Scope Definition

Step 0.1: Identify Exploration Target

From user request, extract:

• Core subject: What feature/system/component to explore?
• Context clue: Why are they asking? (planning change, debugging, learning)
• Depth needed: Surface understanding or comprehensive dive?

Step 0.2: Set Exploration Boundaries

Define scope to keep agents focused:

• Include: Directories/components relevant to target
• Exclude: Build config, vendor code, generated files (unless specifically needed)
• Target specificity: "account creation" vs "entire onboarding service"

Phase 1: Discovery Pass (Meta-Exploration)

Goal: Discover the natural structure of THIS codebase

Step 1.1: Launch Discovery Agents in Parallel

CRITICAL: Single message with 3-4 Task tool calls

Dispatch discovery agents simultaneously:

Task(subagent_type="Explore", description="Architecture discovery",
     prompt="[Architecture Discovery prompt]")

Task(subagent_type="Explore", description="Component discovery",
     prompt="[Component Discovery prompt]")

Task(subagent_type="Explore", description="Layer discovery",
     prompt="[Layer Discovery prompt]")

Task(subagent_type="Explore", description="Organization discovery",
     prompt="[Organization Discovery prompt]")

See Discovery Agent Prompts section below for templates.

Step 1.2: Collect Discovery Results

Wait for all discovery agents to complete. Extract from results:

Structural Elements:

• Architecture pattern(s) used
• List of major components/services
• Layers within components (if applicable)
• Directory organization principle
• Technology stack per component

Perspective Matrix: Create a matrix of discovered perspectives:

Components: [A, B, C]
Layers (per component): [HTTP, UseCase, Repository, Domain]
Boundaries: [Component boundaries, Layer boundaries]
Organization: [By feature, By layer, By domain]

Step 1.3: Determine Deep Dive Strategy

Based on discoveries, decide exploration approach:

| Discovery Result | Deep Dive Strategy | |------------------|-------------------| | 3 components × 4 layers | Launch 3 explorers (one per component) | | Single component, clear layers | Launch 4 explorers (one per layer) | | Microservices architecture | Launch N explorers (one per service) | | Monolith by feature | Launch explorers per major feature | | Mix of patterns | Adaptive: explore each unique area |

Step 1.4: Validate Discovery Quality

✅ Quality checks:

• [ ] Architecture pattern clearly identified
• [ ] Major components/modules enumerated
• [ ] Boundaries and layers documented
• [ ] File paths provided as evidence
• [ ] No major "unknown" areas remaining

If quality insufficient: Re-run specific discovery agents with refined prompts.

Phase 2: Deep Dive Pass (Adaptive Exploration)

Goal: Explore target within each discovered perspective

Step 2.1: Generate Adaptive Prompts

For each discovered perspective, create a targeted prompt:

Template structure:

Explore [TARGET] in [DISCOVERED_COMPONENT/LAYER].

Context from discovery:
- This is the [COMPONENT_NAME] which handles [RESPONSIBILITY]
- Architecture: [PATTERN]
- Location: [DIRECTORY_PATHS]
- Related components: [DEPENDENCIES]

Task:
1. Find how [TARGET] is implemented in this area
2. Trace execution flow within this scope
3. Identify key files and functions (with file:line references)
4. Document patterns and conventions used
5. Note integration points with other areas

Boundaries:
- Stay within [DIRECTORY_SCOPE]
- Maximum depth: [BASED_ON_LAYER]
- Focus on [TARGET] specifically

Output format: [Structured report with file:line references]

Step 2.2: Dispatch Adaptive Explorers in Parallel

CRITICAL: Single message with N Task tool calls (N = number of discovered perspectives)

Example for 3-component system:

Task(subagent_type="Explore", description="Explore target in Component A",
     prompt="[Adaptive prompt for Component A]")

Task(subagent_type="Explore", description="Explore target in Component B",
     prompt="[Adaptive prompt for Component B]")

Task(subagent_type="Explore", description="Explore target in Component C",
     prompt="[Adaptive prompt for Component C]")

Agent Configuration:

• subagent_type: Explore (fast agent specialized for codebase exploration)
• run_in_background: No (await results for synthesis)

Step 2.3: Await All Deep Dive Agents

Block until all N agents complete. Do not proceed with partial results.

Phase 3: Result Collection

Step 3.1: Organize Findings

Separate results into two buckets:

Discovery Results (from Phase 1):

• Architecture map
• Component catalog
• Layer definitions
• Organization principles

Deep Dive Results (from Phase 2):

• Per-perspective exploration reports
• File:line references for target
• Patterns observed in each area
• Integration points discovered

Step 3.2: Quality Check Deep Dives

For each deep dive agent result:

• ✅ Check completeness (did it find the target?)
• ✅ Verify file:line references provided
• ✅ Confirm it stayed within scope
• ⚠️ Note gaps ("target not found in this area" is valid)
• ⚠️ Identify conflicts between areas

Step 3.3: Cross-Reference Discovery vs Deep Dive

Validate that deep dives align with discovered structure:

• Do findings match the architecture pattern?
• Are all discovered components covered?
• Are there surprises (things not in discovery)?

If major misalignment: Investigation needed (discovery was incomplete or incorrect).

Phase 4: Synthesis

Step 4.1: Integrate Discovery + Deep Dive

Create unified understanding by layering deep dives onto discovery:

Integration process:

1. Start with structural map (from Phase 1)
2. Overlay target implementation (from Phase 2 per area)
3. Identify how target flows across discovered boundaries
4. Document patterns consistent across areas
5. Highlight variations between areas

Step 4.2: Create Synthesis Document

Output format:

# Autonomous Codebase Exploration: [Target]

## Executive Summary
[2-3 sentences: architecture + how target works]

---

## Phase 1: Discovery Findings

### Architecture Pattern
[Pattern name with evidence]

### Component Structure
[Components discovered with responsibilities]

### Layer Organization
[Layers identified with boundaries]

### Technology Stack
[Key technologies per area]

### Structural Diagram
[ASCII/markdown diagram of discovered structure]

---

## Phase 2: Deep Dive Findings

### [Discovered Area 1 - e.g., "Onboarding Component"]
**Scope:** `components/onboarding/`
**Target Implementation:**
- Entry point: `path/to/file.ext:line`
- Flow: [step-by-step with file:line references]
- Patterns: [patterns observed]
- Integration: [how it connects to other areas]

### [Discovered Area 2 - e.g., "Transaction Component"]
**Scope:** `components/transaction/`
**Target Implementation:**
- Entry point: `path/to/file.ext:line`
- Flow: [step-by-step with file:line references]
- Patterns: [patterns observed]
- Integration: [how it connects to other areas]

[... repeat for each discovered area ...]

---

## Cross-Cutting Insights

### Pattern Consistency
[Where patterns are consistent across areas]

### Pattern Variations
[Where implementation differs and why]

### Integration Points
[How discovered areas interact for target]

### Data Flow
[How data flows across boundaries]

### Key Design Decisions
[Architectural choices evident from exploration]

---

## Implementation Guidance

### For Adding New Functionality
**Where to add code:**
- In [Component]: `path/to/directory/`
- In [Layer]: Follow pattern from `example/file.ext:line`

**Patterns to follow:**
- [Pattern 1] as seen in `file.ext:line`
- [Pattern 2] as seen in `file.ext:line`

**Integration requirements:**
- Connect to [Component A] via [interface]
- Update [Component B] to handle [scenario]

### For Modifying Existing Functionality
**Files to change:**
- Primary: `path/file.ext:line`
- Secondary impacts: `path/file2.ext:line`

**Ripple effects:**
- Changes in [Component A] require updates in [Component B]

### For Debugging
**Start investigation in:**
- [Component/Layer]: `path/file.ext:line`

**Data inspection points:**
- [Layer 1]: `file.ext:line` - [what to check]
- [Layer 2]: `file.ext:line` - [what to check]

**Common failure points:**
- [Area identified from cross-cutting analysis]

---

## Appendix: Discovery Evidence

[File:line references supporting structural discoveries]

Step 4.3: Validate Synthesis

✅ Completeness check:

• [ ] Both Phase 1 and Phase 2 integrated
• [ ] All discovered areas covered in deep dive
• [ ] Cross-cutting insights identified
• [ ] Implementation guidance specific and actionable

Phase 5: Action Recommendations

Based on synthesis, provide context-aware next steps:

If user's goal is implementation:

Based on autonomous exploration:

**Codebase Structure:**
- Architecture: [Discovered pattern]
- Components: [List with responsibilities]

**To implement [TARGET]:**
1. Add new code in: [Component/Layer] at `path/`
2. Follow pattern: [Pattern name] from `file.ext:line`
3. Integrate with: [Other components] via [mechanism]
4. Test using: [Test pattern discovered]

**Critical files to understand:**
- `file1.ext:line` - [why important]
- `file2.ext:line` - [why important]

Ready to create implementation plan? (Use /ring:write-plan)

If user's goal is debugging:

Based on autonomous exploration:

**Investigation starting points:**
- [Component A]: `file.ext:line` - [what to check]
- [Component B]: `file.ext:line` - [what to check]

**Data flow for [TARGET]:**
[Origin] → [Transform 1] → [Validation] → [Destination]

**Common failure modes:**
- [Pattern from cross-cutting analysis]

Ready to investigate systematically? (Use systematic-debugging)

If user's goal is learning:

Based on autonomous exploration:

**Codebase organization:**
- [Discovered architecture pattern]
- [N components] with [responsibilities]

**Reading path for [TARGET]:**
1. Start: `file1.ext:line` - [entry point]
2. Then: `file2.ext:line` - [core logic]
3. Finally: `file3.ext:line` - [persistence/output]

**Key patterns to understand:**
- [Pattern 1]: Explained in `file.ext:line`
- [Pattern 2]: Explained in `file.ext:line`

**Related areas to explore next:**
- [Connection found during exploration]

Discovery Agent Prompts

Template: Architecture Discovery Agent

**Goal:** Discover the architecture pattern(s) used in this codebase.

**Scope:** Entire codebase (focus on [TARGET_AREA if specified])

**Task:**
1. Examine directory structure at top level
2. Identify architectural pattern(s):
   - Hexagonal (Ports & Adapters)?
   - Layered (N-tier)?
   - Microservices?
   - Monolith (modular or big ball)?
   - Clean Architecture?
   - MVC/MVVM?
   - Event-driven?
   - Other or mixed?
3. Document evidence for pattern identification:
   - Directory names suggesting layers/boundaries
   - Presence of "adapters", "ports", "domain", "infrastructure"
   - Service separation or monolithic structure
4. Note if multiple patterns coexist (e.g., hexagonal within each microservice)

**Evidence to collect:**
- Directory structure (top 2-3 levels)
- Key directory names that indicate architecture
- Example file paths showing layer separation
- README or docs mentioning architecture

**Output format:**

Architecture Discovery

Primary Pattern: [Pattern Name]

Evidence:

• Directory structure shows: [what indicates this pattern]
• Example paths:
  • path/to/adapter/ - [adapter layer]
  • path/to/domain/ - [domain layer]
  • path/to/infrastructure/ - [infrastructure layer]

Confidence: [High/Medium/Low]

[Explain confidence level]

Secondary Patterns: [If any]

[Any mixed or nested patterns]

Architectural Diagram:

[ASCII diagram of discovered architecture]

Key Insights:

• [Any notable architectural decisions or trade-offs visible]

Template: Component Discovery Agent

**Goal:** Identify all major components/modules/services in the codebase.

**Scope:** Entire codebase (focus on [TARGET_AREA if specified])

**Task:**
1. Identify major components:
   - By directory (e.g., `services/`, `components/`, `modules/`)
   - By responsibility (what each component does)
   - By deployment unit (if microservices)
2. For each component, document:
   - Name and location (directory path)
   - Primary responsibility (one sentence)
   - Key technologies used (language, framework)
   - Size/scope (small, medium, large)
3. Map dependencies between components:
   - Which components depend on which?
   - Are dependencies clean or tangled?
4. Identify shared libraries or common code

**Evidence to collect:**
- List of top-level directories
- README files describing components
- Import/dependency patterns
- Package.json, go.mod, or similar dependency files

**Output format:**

Component Discovery

Components Identified: [N]

Component 1: [Name]

• Location: path/to/component/
• Responsibility: [One sentence]
• Technology: [Language + framework]
• Size: [Lines of code or file count]
• Key entry points:
  • file1.ext - [purpose]
  • file2.ext - [purpose]

Component 2: [Name]

[... same structure ...]

Dependency Map:

[Component A] ──→ [Component B]
              ──→ [Shared Lib]
[Component B] ──→ [Shared Lib]
[Component C] ──→ [Component A]
              ──→ [Shared Lib]

Shared Libraries:

• lib/common/ - [what it provides]
• pkg/utils/ - [what it provides]

Dependency Health:

✅ Clean: [Examples] ⚠️ Tangled: [Examples of circular or unclear dependencies]

Template: Layer Discovery Agent

**Goal:** Discover layers/boundaries within components.

**Scope:** [Specific component if multi-component, else entire codebase]

**Task:**
1. Within each component, identify layers:
   - Presentation/API layer (HTTP handlers, controllers, etc.)
   - Business logic layer (use cases, services, domain)
   - Data access layer (repositories, database)
   - Infrastructure layer (external integrations)
2. Document how layers are separated:
   - By directory?
   - By naming convention?
   - By file organization?
3. Check for layer violations:
   - Does presentation layer directly access database?
   - Does business logic depend on infrastructure?
4. Identify patterns used for layer communication:
   - Dependency injection?
   - Interfaces/abstractions?
   - Direct coupling?

**Evidence to collect:**
- Directory structure showing layer separation
- File naming conventions indicating layer
- Import patterns (what imports what)
- Interface/abstraction usage

**Output format:**

Layer Discovery

Component: [Name]

Layers Identified:

Layer 1: [Name - e.g., "HTTP/API Layer"]

• Location: path/to/layer/
• Responsibility: [What it does]
• Key files:
  • file1.ext - [purpose]
  • file2.ext - [purpose]
• Dependencies: [What it depends on]

Layer 2: [Name - e.g., "Business Logic"]

[... same structure ...]

Layer 3: [Name - e.g., "Data Access"]

[... same structure ...]

Layer Communication Pattern:

[How layers interact - interfaces, DI, direct calls, etc.]

Layer Diagram:

┌─────────────────────┐
│   HTTP/API Layer    │
└─────────┬───────────┘
          │
┌─────────▼───────────┐
│   Business Logic    │
└─────────┬───────────┘
          │
┌─────────▼───────────┐
│   Data Access       │
└─────────────────────┘

Layer Health:

✅ Clean separation: [Evidence] ⚠️ Violations found: [Examples with file:line]

Repeat for other components if multi-component system

Template: Organization Discovery Agent

**Goal:** Understand the organizing principle of this codebase.

**Scope:** Entire codebase

**Task:**
1. Identify primary organization principle:
   - By layer (all controllers together, all models together)
   - By feature (each feature has its own directory with all layers)
   - By domain (organized around business domains)
   - By component type (frontend, backend, shared)
   - Mixed or unclear
2. Document file naming conventions:
   - kebab-case, snake_case, camelCase?
   - Suffixes or prefixes? (e.g., `UserController`, `user.controller.ts`)
3. Identify test organization:
   - Co-located with source?
   - Separate test directory?
   - Naming convention for tests?
4. Note configuration and build setup:
   - Where are config files?
   - Build tool used?
   - Environment-specific configs?

**Evidence to collect:**
- Directory structure examples
- File naming examples
- Test file locations
- Config file locations

**Output format:**

Organization Discovery

Primary Organization: [Principle Name]

Evidence:

• Feature X has all its files in: path/to/feature/
• OR: Controllers are all in: path/controllers/, Models in: path/models/

Example structure:

[Show representative directory tree]

File Naming Convention:

• Style: [kebab-case, snake_case, camelCase, etc.]
• Pattern: [Describe pattern]
• Examples:
  • example-file-1.ext
  • example-file-2.ext

Test Organization:

• Location: [Co-located or separate]
• Pattern: *.test.ext, *_test.ext, test/*, etc.
• Examples:
  • Source: src/service.ts
  • Test: src/service.test.ts

Configuration:

• Location: path/to/configs/
• Environment handling: [How envs are managed]
• Build tool: [Make, npm, cargo, etc.]

Key Insights:

• [Notable organizational choices]
• [Any inconsistencies or legacy patterns]

Deep Dive Agent Prompts

Template: Adaptive Deep Dive Agent

**Goal:** Explore [TARGET] within [DISCOVERED_PERSPECTIVE].

**Context from Discovery Phase:**
- **Architecture:** [Discovered pattern]
- **This area is:** [Component/Layer/Module name]
- **Responsibility:** [What this area handles]
- **Location:** [Directory paths]
- **Technologies:** [Stack for this area]
- **Related areas:** [Dependencies/connections]

**Task:**
1. **Find [TARGET] in this area:**
   - Search for relevant files containing [TARGET] implementation
   - Identify entry points (APIs, handlers, functions)
   - Document with file:line references

2. **Trace execution flow:**
   - Follow [TARGET] through this area's layers/components
   - Document each step with file:line
   - Note data transformations
   - Identify validation/error handling

3. **Document patterns:**
   - What patterns are used in this area for [TARGET]?
   - Error handling approach
   - Testing approach
   - Integration approach with other areas

4. **Identify integration points:**
   - How does this area connect to others for [TARGET]?
   - What interfaces/APIs are used?
   - What data is passed between areas?

**Boundaries:**
- **Stay within:** [Directory scope for this perspective]
- **Maximum depth:** [Based on layer - don't trace into frameworks]
- **Focus:** [TARGET] specifically (don't document unrelated code)

**Output Format:**

Deep Dive: [TARGET] in [PERSPECTIVE_NAME]

Overview

[2-3 sentences about how [TARGET] works in this area]

Entry Points

File: path/to/file.ext:line Function/Handler: functionName Triggered by: [API call, event, function call, etc.]

Execution Flow

Step 1: [Layer/Stage Name]

• File: path/to/file.ext:line
• What happens: [Description]
• Key code:

  [Relevant snippet if helpful]
  

Step 2: [Next Layer/Stage]

[... same structure ...]

[... repeat for all steps ...]

Data Transformations

• Input format: [Describe]
• Transform 1: At file.ext:line - [what changes]
• Transform 2: At file.ext:line - [what changes]
• Output format: [Describe]

Patterns Observed

• Error handling: [Approach with example]
• Validation: [Where and how]
• Testing: [Test patterns if visible]
• Integration: [How it connects to other areas]

Integration Points

Outbound: Calls to Other Areas

• To [Area X]: Via interface/api at file.ext:line
  • Purpose: [Why]
  • Data passed: [What]

Inbound: Called by Other Areas

• From [Area Y]: Via interface/api at file.ext:line
  • Purpose: [Why]
  • Data received: [What]

Key Files for [TARGET]

1. path/file1.ext:line - [Primary implementation]
2. path/file2.ext:line - [Secondary/helper]
3. path/file3.ext:line - [Integration point]

Notes

• [Any discoveries not fitting above categories]
• [Gaps: "Could not find X in this area"]
• [Surprises: "Unexpected implementation choice"]

Common Mistakes

| ❌ Bad | ✅ Good | |--------|---------| | Skip discovery, assume structure | Always run Phase 1 discovery first | | Use same deep dive agents for all codebases | Adapt Phase 2 agents based on Phase 1 | | Accept vague discoveries | Require file:line evidence | | Run explorers sequentially | Dispatch all in parallel (per phase) | | Skip synthesis step | Always integrate discovery + deep dive | | Provide raw dumps | Synthesize into actionable guidance | | Use for single file lookup | Use Read/Grep instead |

Integration with Other Skills

| Skill | When to use together | |-------|----------------------| | ring:brainstorming | Use ring:exploring-codebase in Phase 1 (Understanding) to gather context | | ring:writing-plans | Use ring:exploring-codebase before creating implementation plans | | ring:executing-plans | Use ring:exploring-codebase if plan execution reveals gaps | | ring:systematic-debugging | Use ring:exploring-codebase to understand system before debugging | | ring:dispatching-parallel-agents | This skill is built on that pattern (twice!) |

Output Format

When skill completes, provide:

1. Synthesis Document

[As defined in Phase 4.2 - includes both discovery and deep dive]

2. Structural Insights

**Discovered Architecture:**
- Pattern: [Name]
- Components: [List]
- Layers: [List]
- Organization: [Principle]

**[TARGET] Implementation:**
- Present in: [N components/layers]
- Entry points: [List with file:line]
- Integration: [How areas connect]
- Patterns: [Consistent patterns observed]

3. Next Step Recommendations

[As defined in Phase 5 - context-aware based on user goal]

Verification

After completing exploration:

✅ Phase 1 (Discovery) completeness:

• [ ] Architecture pattern identified with evidence
• [ ] All major components/modules enumerated
• [ ] Layers/boundaries documented
• [ ] Organization principle clear
• [ ] File:line references for structural elements

✅ Phase 2 (Deep Dive) completeness:

• [ ] All discovered perspectives explored
• [ ] [TARGET] found and documented in each area
• [ ] Execution flows traced with file:line
• [ ] Integration points identified
• [ ] Patterns documented per area

✅ Synthesis quality:

• [ ] Discovery and deep dive integrated
• [ ] Cross-cutting insights identified
• [ ] Inconsistencies explained
• [ ] Implementation guidance specific
• [ ] Next steps clear and actionable

Adaptive Examples

Example 1: Microservices Architecture

Phase 1 Discovery finds:

• 5 microservices (Auth, User, Order, Payment, Notification)
• Each service is independent
• Event-driven communication via message bus

Phase 2 adapts:

• Launch 5 deep dive agents (one per service)
• Each explores target within their service
• Focus on event publishing/subscribing for integration

Example 2: Monolithic Hexagonal Architecture

Phase 1 Discovery finds:

• Single application
• Hexagonal architecture (adapters + domain)
• 4 layers: HTTP → Application → Domain → Infrastructure

Phase 2 adapts:

• Launch 4 deep dive agents (one per layer)
• Each explores target within their layer
• Focus on dependency inversion at boundaries

Example 3: Feature-Organized Monolith

Phase 1 Discovery finds:

• Features organized in separate directories
• Each feature has its own layers
• 6 major features identified

Phase 2 adapts:

• Launch 6 deep dive agents (one per feature)
• Each explores target within their feature
• Focus on shared code and cross-feature integration

Key Principles

| Principle | Application | |-----------|-------------| | Discover, then dive | Phase 1 discovery informs Phase 2 exploration | | Adaptive parallelization | Number and type of agents matches structure | | Evidence-based | All discoveries backed by file:line references | | Autonomous | Codebase reveals its own structure | | Synthesis required | Raw outputs must be integrated | | Action-oriented | Always end with next steps | | Quality gates | Verify each phase before proceeding |

Required Patterns

This skill uses these universal patterns:

• State Tracking: See skills/shared-patterns/state-tracking.md
• Failure Recovery: See skills/shared-patterns/failure-recovery.md
• TodoWrite: See skills/shared-patterns/todowrite-integration.md

Apply ALL patterns when using this skill.

Notes

• Performance: Two phases complete faster than naive sequential exploration
• Cost: Optimized for fast, cost-effective exploration
• Adaptability: Works for any architecture (hexagonal, microservices, MVC, etc.)
• Scalability: Handles codebases from small (2-3 components) to large (10+ services)
• Reusability: Synthesis documents serve as permanent reference

Blocker Criteria

STOP and report if:

| Decision Type | Blocker Condition | Required Action | |---|---|---| | Scope Definition | Target exploration area is undefined or too vague | STOP and ask user to clarify exploration target | | Phase 1 Failure | Discovery agents return no structural information | STOP and report - codebase may be empty or inaccessible | | Agent Dispatch | Unable to launch parallel discovery agents | STOP and report infrastructure issue | | Synthesis Conflict | Deep dive results contradict discovery findings | STOP and investigate - discovery may have been incomplete |

Cannot Be Overridden

The following requirements CANNOT be waived:

• MUST run Phase 1 discovery before Phase 2 deep dive - skipping discovery is FORBIDDEN
• MUST provide file:line references as evidence for all structural claims
• MUST synthesize results into actionable guidance - raw dumps are NOT acceptable
• CANNOT proceed with partial Phase 1 results - all discovery agents must complete

Severity Calibration

| Severity | Condition | Required Action | |---|---|---| | CRITICAL | Phase 1 discovery finds no architecture pattern | MUST investigate - codebase may not follow standard patterns | | HIGH | Deep dive agent finds target missing in expected area | MUST document gap and adjust understanding | | MEDIUM | Inconsistent patterns across discovered components | Should document variations and explain why | | LOW | Minor naming convention differences between areas | Fix in next iteration |

Pressure Resistance

| User Says | Your Response | |---|---| | "Skip discovery, I already know the architecture" | "I MUST run discovery to validate assumptions. Prior knowledge is often incomplete - discovery takes 6-10 minutes but prevents hours of debugging wrong assumptions." | | "Production is down, just grep for the answer" | "CANNOT skip systematic exploration under pressure. High stakes demand MORE rigor. 6-10 minutes of discovery prevents cascading failures from wrong fixes." | | "This is a simple question, just find the file" | "I MUST complete two-phase exploration. Location without context leads to follow-up questions. One exploration answers current and future questions." |

Anti-Rationalization Table

| Rationalization | Why It's WRONG | Required Action | |---|---|---| | "I already know this codebase structure" | Prior knowledge is high-level abstraction, not implementation detail. Assumptions cause most bugs. | MUST run discovery to validate assumptions | | "Grep is faster for this simple lookup" | Location without context requires multiple follow-ups. Ad-hoc investigation compounds time. | MUST use systematic exploration | | "Being pragmatic means skipping discovery" | False pragmatism. Shortcuts under pressure create bigger problems than they solve. | MUST invest 6-10 minutes in proper exploration | | "The user seems impatient, I'll skip Phase 1" | User impatience is not justification for incomplete work. Wrong answers waste more time. | MUST complete both phases regardless of pressure |