| name | marsai:exploring-codebase |
| description | Autonomous two-phase codebase exploration - first discovers natural perspectives
(layers, components, boundaries), then dispatches adaptive deep-dive explorers
based on what was discovered. Synthesizes findings into actionable insights.
|
| trigger | - 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
WARNING: These are NOT valid skip reasons:
- "I already know the architecture" → Prior knowledge is incomplete
- "Simple question about location" → Location without context is incomplete
- "Production emergency, no time" → High stakes demand MORE rigor
- "Colleague told me structure" → High-level ≠ implementation details
|
| related | {"similar":["dispatching-parallel-agents","systematic-debugging"],"sequence_after":["brainstorming"],"sequence_before":["marsai:writing-plans","marsai:executing-plans"]} |
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 marsai:exploring-codebase skill to autonomously discover and explore the codebase structure.
Before proceeding, I've checked the Red Flags table and confirmed:
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:
- Acknowledge the pressure - "This is urgent, I feel pressure to skip discovery"
- Recognize the trap - "That pressure is EXACTLY when I need systematic approach"
- Invest 6-10 minutes - Run two-phase exploration
- 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:
- Am I conflating "fast" with "good"? Speed without accuracy is just fast failure.
- Am I optimizing for feeling productive? Grep gives quick dopamine, but incomplete understanding.
- Am I making excuses under pressure? High stakes demand MORE rigor, not less.
- 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:
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:
- Start with structural map (from Phase 1)
- Overlay target implementation (from Phase 2 per area)
- Identify how target flows across discovered boundaries
- Document patterns consistent across areas
- 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:
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 /marsai: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.extexample-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]
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]
path/file1.ext:line - [Primary implementation]path/file2.ext:line - [Secondary/helper]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 |
|---|
| marsai:brainstorming | Use marsai:exploring-codebase in Phase 1 (Understanding) to gather context |
| marsai:writing-plans | Use marsai:exploring-codebase before creating implementation plans |
| marsai:executing-plans | Use marsai:exploring-codebase if plan execution reveals gaps |
| marsai:systematic-debugging | Use marsai:exploring-codebase to understand system before debugging |
| marsai: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:
✅ Phase 2 (Deep Dive) completeness:
✅ Synthesis quality:
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 |
