---
name: scorpio-explore
description: A read-only assistant for exploring, explaining, and discussing code. Use when you want to understand how something works, trace a flow, review architecture, or ask questions about the codebase — without making any changes.
---

# Codebase Analyze Read-Only (alias: Discuss the Code)

A read-only skill for code exploration and discussion. This skill never modifies files — it reads, analyzes, and explains. Use it to understand unfamiliar code, trace execution flows, review architecture decisions, or prepare for an edit.

## When to Use

- Understanding how a feature or module works
- Tracing an execution flow end-to-end
- Reviewing code before deciding what to change
- Answering "how does X work?" or "where does Y happen?" questions
- Comparing approaches or evaluating trade-offs
- Onboarding to a new area of the codebase

## Prerequisites

- A question or topic to explore
- The target project directory must be accessible

## Read-Only Constraint

**This skill MUST NOT modify any files.** It may only use read-oriented tools:
- **Read** — View file contents
- **Glob** — Find files by pattern
- **Grep** — Search file contents
- **Bash** — Only for read-only commands (`git log`, `git diff`, `wc`, `ls`, etc.)

If the discussion reveals something that should be changed, suggest it to the user — do not make the change. Recommend using `scorpio-edit` for the actual modification.

## Workflow

### Phase 1: Scope

1. Read the user's question or topic
2. If `{docs.planning}/` exists, scan it for relevant context (PRD, MVP scope, architecture docs)
3. Determine what area of the codebase to explore
4. If the question is too broad, ask one focusing question — then proceed

### Phase 2: Explore

1. Use Glob to find relevant files
2. Use Grep to locate specific patterns, functions, or references
3. Read the relevant code sections (use line offsets for large files)
4. Trace connections: callers, callees, imports, exports, types

### Phase 3: Explain

1. Provide a clear, structured explanation
2. Reference specific files and line numbers
3. Use code snippets where they clarify the explanation
4. Call out important patterns, edge cases, or potential issues
5. If the user asked about a flow, walk through it step by step

### Phase 4: Suggest (Optional)

If the discussion reveals actionable items:
- Suggest improvements but do not implement them
- Recommend `scorpio-edit` for targeted changes
- Recommend `scorpio-feature-plan` (`scorpio-feature-plan`) for larger refactors
- Recommend `scorpio-bug-investigate` (`scorpio-bug-investigate`) for suspected bugs

## Scope Rules

- **Read-only.** Never use Edit, Write, or NotebookEdit tools.
- **No broad dumps.** Don't paste entire files — show relevant excerpts with context.
- **Stay focused.** Answer the question asked, don't explore tangential areas.
- **Cite sources.** Always reference file paths and line numbers.

## Output

Return a structured explanation:
- Summary of what was found
- Key files and line numbers referenced
- Code flow or architecture diagram (if applicable)
- Suggested next steps (if any)

## Integration

- Routable from the Layer 2 AI router via chat commands
- Can load project planning context from `{docs.planning}/` when present
- Pairs with `scorpio-edit` for read-then-write workflows
- Concurrency: `read` — can run in parallel with other read-only sessions