/explore

name: explore
description: Meta-skill for internal codebase exploration at varying depths (quick/deep/architecture)
allowed-tools: [Bash, Task, Read, Glob, Grep, Write]
keywords: [explore, codebase, architecture, understand, analyze, layers, call graph, brownfield]

Explore - Internal Codebase Exploration

Meta-skill for exploring an internal codebase at varying depths. READ-ONLY workflow - no code changes.

Usage

/explore <depth> [options]

Question Flow (No Arguments)

If the user types just `/explore` with no or partial arguments, guide them through this question flow. Use AskUserQuestion for each phase.

Phase 0: Workflow Selection

question: "How would you like to explore?"
header: "Explore"
options:
  - label: "Help me choose (Recommended)"
    description: "I'll ask questions to pick the right exploration depth"
  - label: "Quick - fast overview"
    description: "Chain: tldr tree → tldr structure (~1 min)"
  - label: "Deep - comprehensive analysis"
    description: "Chain: onboard → tldr → research → document (~5 min)"
  - label: "Architecture - layers & dependencies"
    description: "Chain: tldr arch → call graph → layer mapping (~3 min)"

**Mapping:**

• "Help me choose" → Continue to Phase 1-4 questions
• "Quick" → Set depth=quick, skip to Phase 2 (scope)
• "Deep" → Set depth=deep, skip to Phase 2 (scope)
• "Architecture" → Set depth=architecture, skip to Phase 2 (scope)

**If Answer is Unclear (via "Other"):**

question: "I want to understand how deep you want to explore. Did you mean..."
header: "Clarify"
options:
  - label: "Help me choose"
    description: "Not sure - guide me through questions"
  - label: "Quick - fast overview"
    description: "Just want to see what's here"
  - label: "Deep - comprehensive analysis"
    description: "Need thorough understanding"
  - label: "Neither - let me explain differently"
    description: "I'll describe what I need"

Phase 1: Exploration Goal

question: "What are you trying to understand?"
header: "Goal"
options:
  - label: "Get oriented in the codebase"
    description: "Quick overview of structure"
  - label: "Understand how something works"
    description: "Deep dive into specific area"
  - label: "Map the architecture"
    description: "Layers, dependencies, patterns"
  - label: "Find where something is"
    description: "Locate specific code/functionality"

**Mapping:**

• "Get oriented" → quick depth
• "Understand how" → deep depth
• "Map architecture" → architecture depth
• "Find where" → quick with --focus

Phase 2: Scope

question: "What area should I focus on?"
header: "Focus"
options:
  - label: "Entire codebase"
    description: "Explore everything"
  - label: "Specific directory or module"
    description: "I'll specify the path"
  - label: "Specific concept/feature"
    description: "e.g., 'authentication', 'API routes'"

If "Specific directory" or "Specific concept" → ask follow-up for the path/keyword.

Phase 3: Output Format

question: "What should I produce?"
header: "Output"
options:
  - label: "Just tell me what you find"
    description: "Interactive summary in chat"
  - label: "Create a documentation file"
    description: "Write to thoughts/shared/docs/"
  - label: "Create handoff for implementation"
    description: "Prepare context for coding agent"

**Mapping:**

• "Documentation file" → --output doc
• "Handoff for implementation" → --output handoff

Phase 4: Entry Point (Architecture only)

If architecture depth selected:

question: "Where should I start the analysis?"
header: "Entry point"
options:
  - label: "Auto-detect (main, cli, app)"
    description: "Find common entry points"
  - label: "Specific function/file"
    description: "I'll specify the entry point"

Summary Before Execution

Based on your answers, I'll run:

**Depth:** deep
**Focus:** "authentication"
**Output:** handoff
**Path:** src/

Proceed? [Yes / Adjust settings]

Depths

| Depth | Time | What it does | |-------|------|--------------| | `quick` | ~1 min | tldr-explorer only - fast structure overview | | `deep` | ~5 min | onboard + tldr-explorer + research-codebase + write doc | | `architecture` | ~3 min | tldr arch + call graph + layer mapping + circular dep detection |

Options

| Option | Description | Example | |--------|-------------|---------| | `--focus "area"` | Focus on specific area | `--focus "auth"`, `--focus "api"` | | `--output handoff` | Create handoff for next agent | `--output handoff` | | `--output doc` | Create documentation file | `--output doc` | | `--entry "func"` | Start from specific entry point | `--entry "main"`, `--entry "process_request"` |

Examples

# Quick structure overview
/explore quick

# Deep exploration focused on auth
/explore deep --focus "auth" --output doc

# Architecture analysis from specific entry
/explore architecture --entry "cli" --output handoff

# Quick focused exploration
/explore quick --focus "hooks"

Workflow Details

Quick Depth

Fast structure overview using tldr-explorer. Best for:

• Initial orientation
• Quick questions about structure
• Finding where things are

**Steps:** 1. Run `tldr tree` for file structure 2. Run `tldr structure` for codemaps 3. If `--focus` provided, run `tldr search` for targeted results 4. Return summary

**Commands:**

# 1. File tree
tldr tree ${PATH:-src/} --ext .py

# 2. Code structure
tldr structure ${PATH:-src/} --lang python

# 3. Focused search (if --focus provided)
tldr search "${FOCUS}" ${PATH:-src/}

Deep Depth

Comprehensive exploration with documentation output. Best for:

• First time in a codebase
• Preparing for major work
• Creating reference documentation

**Steps:** 1. Check if onboarded (look for `.claude/cache/tldr/`), if not run onboard 2. Run tldr-explorer for structure 3. Spawn research-codebase agent for patterns 4. Write findings to doc or handoff

**Subproce