explore · diff

git:20260808.3b763b1 to git:20261104.1844d11

18 added, 466 removed. Audit A to A.

What this update changes in the checks

No check changed: every fixed check gives the same answer before and after this update.

A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.

- ---
- 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
-
- ```yaml
- 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"):**
- ```yaml
- 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
-
- ```yaml
- 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
-
- ```yaml
- 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
-
- ```yaml
- 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:
-
- ```yaml
- 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
-
- ```bash
- # 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:**
- ```bash
- # 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
-
- **Subprocess:**
- ```
- # 1. Onboard check
- if [ ! -f .claude/cache/tldr/arch.json ]; then
- # Spawn onboard agent
- fi
-
- # 2. Structure analysis
- tldr structure src/ --lang python
- tldr calls src/
-
- # 3. Research patterns (via scout agent)
- Task: research-codebase → "Document existing patterns in ${FOCUS:-codebase}"
-
- # 4. Write output
- → thoughts/shared/research/YYYY-MM-DD-explore-{focus}.md
- → OR thoughts/shared/handoffs/{session}/explore-{focus}.yaml
- ```
-
- ### Architecture Depth
-
- Architecture-focused analysis with layer detection. Best for:
- - Understanding system boundaries
- - Preparing for refactoring
- - Identifying coupling issues
-
- **Steps:**
- 1. Run `tldr arch` for layer detection
- 2. Run `tldr calls` for cross-file call graph
- 3. Analyze entry/middle/leaf layers
- 4. Detect circular dependencies
- 5. Map architectural boundaries
-
- **Commands:**
- ```bash
- # 1. Architecture detection
- tldr arch ${PATH:-src/}
- # Returns: entry_layer, middle_layer, leaf_layer, circular_deps
-
- # 2. Call graph
- tldr calls ${PATH:-src/}
- # Returns: edges, nodes
-
- # 3. Impact analysis from entry point (if --entry provided)
- tldr impact ${ENTRY} ${PATH:-src/} --depth 3
- ```
-
- **Output Structure:**
- ```yaml
- layers:
- entry: [routes.py, cli.py, main.py] # Controllers/handlers
- middle: [services.py, auth.py] # Business logic
- leaf: [utils.py, helpers.py] # Utilities
-
- call_graph:
- total_edges: 142
- hot_paths: [process_request → validate → authorize]
-
- circular_deps:
- - [module_a, module_b] # A imports B, B imports A
-
- boundaries:
- - name: API layer
- files: [src/api/*]
- calls_to: [src/services/*]
- ```
-
- ## Output Formats
-
- ### --output doc
-
- Creates: `thoughts/shared/research/YYYY-MM-DD-explore-{focus}.md`
-
- ```markdown
- ---
- date: {ISO timestamp}
- type: exploration
- depth: {quick|deep|architecture}
- focus: {focus area or "full"}
- commit: {git hash}
- ---
-
- # Codebase Exploration: {focus}
-
- ## Summary
- {High-level findings}
-
- ## Structure
- {File tree / codemaps}
-
- ## Architecture
- {Layer analysis - for architecture depth}
-
- ## Key Components
- {Important files and their roles}
-
- ## Patterns Found
- {Existing patterns - for deep depth}
-
- ## References
- - `path/to/file.py:line` - Description
- ```
-
- ### --output handoff
-
- Creates: `thoughts/shared/handoffs/{session}/explore-{focus}.yaml`
-
- ```yaml
- ---
- type: exploration
- ts: {ISO timestamp}
- depth: {quick|deep|architecture}
- focus: {focus area}
- commit: {git hash}
- ---
-
- summary: {One-line summary of findings}
-
- structure:
- entry_points: [{main.py}, {cli.py}]
- key_modules: [{auth.py}, {routes.py}]
- test_coverage: [{tests/}]
-
- architecture:
- layers:
- entry: [{files}]
- middle: [{files}]
- leaf: [{files}]
- circular_deps: [{pairs}]
-
- findings:
- - {key finding with file:line}
-
- next_steps:
- - {Recommended action based on exploration}
-
- refs:
- - path: {file.py}
- role: {what it does}
- ```
-
- ## Integration with /build
-
- The explore skill is designed to feed into `/build brownfield`:
-
- ```bash
- # Step 1: Explore to understand
- /explore architecture --output handoff
-
- # Step 2: Build with context from exploration
- /build brownfield --from-handoff thoughts/shared/handoffs/session/explore-full.yaml
- ```
-
- ## Implementation
-
- When user invokes `/explore <depth> [options]`:
-
- ### Parse Arguments
- ```python
- depth = args[0] # quick | deep | architecture
- focus = extract_option(args, "--focus")
- output = extract_option(args, "--output") # handoff | doc
- entry = extract_option(args, "--entry")
- ```
-
- ### Execute Based on Depth
-
- **Quick:**
- ```bash
- # Just tldr commands, no agents
- tldr tree ${src_dir} --ext .py
- tldr structure ${src_dir} --lang python
- if [ -n "$focus" ]; then
- tldr search "$focus" ${src_dir}
- fi
- ```
-
- **Deep:**
- ```bash
- # 1. Check/run onboard
- if [ ! -f .claude/cache/tldr/meta.json ]; then
- # Spawn onboard agent via Task tool
- fi
-
- # 2. Structure
- tldr structure src/ --lang python
-
- # 3. Research (spawn scout agent)
- # Task tool with subagent_type: "scout"
- # Prompt: "Research patterns in ${focus:-codebase}"
-
- # 4. Write output
- # → doc or handoff based on --output
- ```
-
- **Architecture:**
- ```bash
- # 1. Arch detection
- arch_output=$(tldr arch ${src_dir})
-
- # 2. Call graph
- calls_output=$(tldr calls ${src_dir})
-
- # 3. Impact from entry (if provided)
- if [ -n "$entry" ]; then
- impact_output=$(tldr impact $entry ${src_dir} --depth 3)
- fi
-
- # 4. Synthesize and write output
- ```
-
- ## Key Principles
-
- 1. **READ-ONLY** - This skill never modifies code
- 2. **Uses bounded delegation** - Claude may use `scout`; Codex keeps the parent `luna_worker` model and does not route to Sonnet/Haiku tiers
- 3. **Token-efficient** - Uses tldr commands (95% savings over raw reads)
- 4. **Outputs to shared locations** - `thoughts/shared/research/` or handoff directory
- 5. **Entry point to /build** - Exploration handoffs feed into brownfield builds
-
- ## Related Skills
-
- | Skill | When to Use |
- |-------|-------------|
- | **tldr-explorer** | Direct tldr commands (used internally by explore) |
- | **tldr-code** | Specific analysis commands (cfg, dfg, slice) |
- | **onboard** | First-time project setup (used by deep depth) |
- | **research-codebase** | Pattern documentation (used by deep depth) |
- | **create_handoff** | Handoff format (used by --output handoff) |
-
- ## Troubleshooting
-
- **tldr not found:**
- ```bash
- # Check if installed
- which tldr
- # Install if missing
- uv tool install llm-tldr
- # or: pip install llm-tldr
- ```
-
- **No Python files found:**
- ```bash
- # Check language, adjust --lang
- tldr structure src/ --lang typescript # or go, rust
- ```
-
- **Empty architecture output:**
- ```bash
- # May need to specify src directory
- tldr arch ./ # Current directory
- tldr arch src/ # Explicit src
- ```
+ ---
+ name: explore
+ description: Map an unfamiliar codebase or trace a focused behavior without editing the project.
+ ---
+
+ # Explore
+
+ Use `/explore [quick|deep|architecture] [--focus <area>] [--entry <symbol>] [--output doc|handoff]`. Default to a quick map and honor a deeper requested scope.
+
+ Begin with instructions, manifests, README and filenames. Use `rg --files` and scoped symbol searches, then read entry points and callers. Fall back to available file/search tools if ripgrep is absent.
+
+ - **Quick:** Identify stack, entry points, key directories, test commands and main files for the requested area.
+ - **Deep:** Trace input, state changes, output, errors, dependencies, tests and configuration.
+ - **Architecture:** Map boundaries, import directions, shared state and external integrations. Confirm cycles from code.
+
+ Optional AST, `tldr` or semantic tools can help when installed and current. Raw code is the source of truth. Do not install tools, build indexes or read the entire repository by default. An installed Claude `scout` can answer an independent question; Codex keeps parent settings.
+
+ Return a concise map with locations, verified facts, uncertainties and next steps. Write an artifact only when requested, using the supplied destination or repository convention. Exploration is read-only; do not start memory, learning or swarm automation.