Explore Subagent

Shared codebase exploration for discovering performance-critical code paths, module structures, and optimization opportunities. Results are cached to avoid redundant exploration across profiler and optimizer roles.

Design Rationale

Codebase exploration is a read-only operation shared between profiler (mapping bottlenecks) and optimizer (understanding implementation context). Caching explorations avoids redundant work when optimizer re-explores paths the profiler already mapped.

Invocation

Called by profiler, optimizer after needing codebase context for performance analysis or implementation:

Task({
  subagent_type: "cli-explore-agent",
  run_in_background: false,
  description: "Explore codebase for performance-critical paths in <target-scope>",
  prompt: `Explore the codebase to identify performance-critical code paths.

Target scope: <target-scope>
Session: <session-folder>
Focus: <exploration-focus>

Tasks:
1. Map the module structure and entry points within scope
2. Identify hot code paths (frequently called functions, critical loops)
3. Find performance-relevant patterns (caching, lazy loading, async, pooling)
4. Note any existing performance optimizations or benchmark harnesses
5. List key files with their roles in the performance-critical path

Output a structured exploration report with:
- Module map (key files and their relationships)
- Hot path analysis (call chains, loop nests, recursive patterns)
- Existing optimization patterns found
- Performance-relevant configuration (caching, pooling, batching settings)
- Recommended investigation targets for profiling`
})

Cache Mechanism

Cache Index Schema

<session-folder>/explorations/cache-index.json:

{
  "entries": [
    {
      "key": "<scope-hash>",
      "scope": "<target-scope>",
      "focus": "<exploration-focus>",
      "timestamp": "<ISO-8601>",
      "result_file": "<hash>.md"
    }
  ]
}

Cache Lookup Rules

Condition	Action
Exact scope+focus match exists	Return cached result from .md
No match	Execute subagent, cache result to .md, update index
Cache file missing but index has entry	Remove stale entry, re-execute
Cache older than current session	Use cached (explorations are stable within session)

Integration with Calling Role

The calling role is responsible for:

Before calling: Determine target scope and exploration focus
Calling: Check cache first, invoke subagent only on cache miss
After calling:

Result	Action
Exploration successful	Use findings to inform profiling/implementation
Exploration partial	Use available findings, note gaps
Exploration failed	Proceed without exploration context, use direct file reading

Output Schema

{
  "scope": "<target-scope>",
  "module_map": [
    { "file": "<path>", "role": "<description>", "hot_path": true }
  ],
  "hot_paths": [
    { "chain": "<call-chain>", "frequency": "<high|medium|low>", "files": ["<path>"] }
  ],
  "existing_optimizations": [
    { "type": "<pattern>", "location": "<file:line>", "description": "<what>" }
  ],
  "investigation_targets": ["<file-or-pattern>"]
}

Error Handling

Scenario	Resolution
Single exploration angle fails	Continue with partial results
All exploration fails	Return basic result from direct file listing
Target scope not found	Return error immediately
Cache corrupt	Clear cache-index.json, re-execute

3.5 KiB Raw Blame History