Overview Exploration

Overview Exploration Skill

Quick project overview exploration executed directly without agent spawn.

When to Use

• At the start of ultrawork sessions (exploration phase)
• When project structure understanding is needed
• Context collection before targeted exploration

Execution Steps

Step 1: Detect Project Type

Check for language/framework config files:

Glob(pattern="package.json")      # Node.js/JS
Glob(pattern="go.mod")            # Go
Glob(pattern="requirements.txt")  # Python
Glob(pattern="Cargo.toml")        # Rust
Glob(pattern="pom.xml")           # Java/Maven

Read discovered files to understand dependencies and framework.

Step 2: Explore Directory Structure

# Top-level structure
Glob(pattern="*", path=".")

# Main source directories
Glob(pattern="src/*")
Glob(pattern="app/*")
Glob(pattern="lib/*")

Step 3: Identify Entry Points and Patterns

# Find entry points (language-specific)
Grep(pattern="export default|module.exports", type="ts")
Grep(pattern="def main|if __name__", type="py")
Grep(pattern="func main", type="go")

# Check for existing patterns
Grep(pattern="auth|login|session", output_mode="files_with_matches")

Step 4: Quantitative Data Collection

Beyond descriptive findings, collect measurable data that enables informed planning decisions.

Test file count:

# Count test files in project
find . -name "*.test.*" -o -name "*.spec.*" | wc -l

# Check for test configuration
ls jest.config* vitest.config* .bun* 2>/dev/null

Key interface signatures:

# Extract exported interfaces and types
grep -A3 "export.*interface\|export.*type\|export.*function" src/ --include="*.ts" -rn | head -20

File line counts for main source files:

# Line counts for relevant source files
wc -l src/**/*.ts 2>/dev/null | tail -5

Include these metrics in your exploration output under a "Quantitative Data" subsection (see Output Format below).

Step 5: Read Documentation

Read(file_path="README.md")
Read(file_path="CLAUDE.md")

Goal-Aligned Exploration Priority

Exploration must be driven by the session goal. Breadth-first scanning wastes time when the goal points to a specific domain.

Keyword Extraction

Parse the session goal for domain keywords to prioritize exploration:

Example: goal = "add authentication" → prioritize exploring auth/, login/, session/, middleware/ patterns first.

Exploration Priority Order

1. Files directly named in or implied by the goal
2. Files that import/depend on those files (consumers)
3. Test files for the above
4. Configuration files (if goal involves infra changes)
5. Everything else (surface scan only)

Relevance Annotation

Every finding should connect back to the goal. Annotate findings with relevance:

### src/middleware/auth.ts
**Relevance**: Direct target for modification (goal: "add role-based access")
- Uses JWT validation with `jsonwebtoken` library
- 12 route files import this middleware

Output Format

Summarize findings in structured format:

## Overview Exploration Results

**Project Type**: {framework/language}

**Tech Stack**:
- Language: {language and version}
- Framework: {framework}
- Database: {if found}
- Test: {test framework}

**Directory Structure**:
{tree representation}

**Key Entry Points**:
- {main files}

**Existing Patterns**:
- {auth, database, api patterns found}

**Quantitative Data**:

| Metric | Value |
|--------|-------|
| Test files | {count} |
| Test runner | {runner} |
| Lines in {key file} | {count} |
| Exported interfaces | {count} |

**Relevant to Goal**:
- {files directly related to the session goal, with relevance annotation}

See references/templates.md for complete template.

Session Integration

When running within an ultrawork session:

1. Update exploration stage to overview
2. Write findings to $SESSION_DIR/exploration/overview.md
3. Add summary to context.json
4. Advance stage to analyzing

Note: SESSION_DIR is the session metadata directory (e.g., ~/.claude/ultrawork/sessions/${CLAUDE_SESSION_ID}), not the project working directory. All exploration artifacts are stored in the session directory to maintain session isolation.

# For ultrawork, use scripts written in Javascript/Bun
SCRIPTS="${CLAUDE_PLUGIN_ROOT}/src/scripts"

# Update stage
bun $SCRIPTS/session-update.js --session ${CLAUDE_SESSION_ID} --exploration-stage overview

# Get session directory and write findings
SESSION_DIR=~/.claude/ultrawork/sessions/${CLAUDE_SESSION_ID}
mkdir -p "$SESSION_DIR/exploration"
# Write findings to $SESSION_DIR/exploration/overview.md using Write tool

# Add to context (file path is relative to SESSION_DIR)
bun $SCRIPTS/context-add.js --session ${CLAUDE_SESSION_ID} \
  --explorer-id "overview" \
  --file "exploration/overview.md" \
  --summary "{summary}" \
  --key-files "{files}" \
  --patterns "{patterns}"

# Advance stage
bun $SCRIPTS/session-update.js --session ${CLAUDE_SESSION_ID} --exploration-stage analyzing

Time Budget

• Target: Complete within 30 seconds
• Max Read: 5-7 files
• Max Glob: 10 patterns

No excessive exploration - overview aims for quick understanding. Targeted exploration handles detailed investigation.

Next Steps

After overview completion:

1. Analyze Goal + Overview → Generate targeted exploration hints
2. Detailed exploration via Task(subagent_type="ultrawork:explorer")
3. All exploration complete → Proceed to Planning phase

Additional Resources

Reference Files

• references/examples.md - Complete exploration examples for different project types
• references/templates.md - Output templates and session integration commands

Converted and distributed by TomeVault — claim your Tome and manage your conversions.