smart-explore

name	smart-explore
description	Token-efficient code exploration — view file structure, search symbols, and read specific implementations without loading full files. Reduces token usage by 4-18x compared to reading entire files.
projectType	all

Smart Explore Skill

Purpose

Enable AI agents to explore codebases efficiently by viewing structural outlines, searching for symbols, and extracting specific implementations — without reading entire files. This dramatically reduces token consumption when navigating large projects.

When to Use

• Understanding a new file: Use outline instead of reading the full file
• Finding where something is defined: Use search to locate symbols across the project
• Reading a specific function: Use unfold to extract just that function's code

Token Savings

Method	Typical Token Cost	Notes
Read full file	~12,000+	All content, most irrelevant
Outline	~1,000-2,000	Structural skeleton only
Search	~2,000-6,000	Symbol locations across codebase
Unfold	~400-2,100	Exact function/class source

Savings: 4-18x compared to reading full files.

Available Commands

1. Outline — Structural Skeleton

View all symbols (functions, classes, interfaces, exports) in a file without reading the full source:

heraspec explore outline src/core/memory/memory-store.ts

Output example:

## 📄 src/core/memory/memory-store.ts
*typescript | 285 lines | ~71250 tokens*

🏛️ export class MemoryStore (L20-285)
  ↳ open() (L32-58)
  ↳ close() (L63-68)
  ↳ addObservation(input) (L88-120)
  ↳ getObservationById(id) (L125-132)
  ↳ getRecentObservations(project, limit) (L140-160)
  ↳ addSummary(input) (L165-195)
  ↳ getStatus(project) (L200-260)

2. Search — Find Symbols Across Codebase

Search for functions, classes, interfaces by name across the project:

heraspec explore search "MemoryStore" src/
heraspec explore search "addObservation" src/ --limit 10

Output example:

## Symbol Search: "MemoryStore" (3 results)

| Rel | Type | Name | File | Lines |
|-----|------|------|------|-------|
| 100% | 🏛️ class | MemoryStore | src/core/memory/memory-store.ts | L20-285 |
| 60% | ⚡ function | MemoryStoreFactory | src/core/memory/index.ts | L10-15 |
| 40% | 📌 variable | memoryStore | src/commands/memory.ts | L25-25 |

3. Unfold — Extract Specific Symbol Source

Read just the implementation of a specific function or class:

heraspec explore unfold src/core/memory/memory-store.ts addObservation

Output example:

## method: addObservation
*src/core/memory/memory-store.ts:L88-120 | ~800 tokens (vs ~71250 full file)*

  addObservation(input: ObservationInput): Observation {
    this.ensureOpen();
    // ... full implementation
  }

Supported Languages

Language	Extensions	Symbols Detected
TypeScript	.ts, .tsx	class, interface, type, enum, function, method, variable
JavaScript	.js, .jsx, .mjs	class, function, method, variable
Python	.py	class, function, method, variable
PHP	.php	class, interface, function
Go	.go	struct, interface, func
Rust	.rs	struct, trait, enum, fn
Java	.java	class, interface, method
C#	.cs	class, interface, method
Vue	.vue	Same as TypeScript
Svelte	.svelte	Same as TypeScript

Workflow for AI Agents

Exploration Strategy

Need to understand a file?
├── Step 1: heraspec explore outline <file>
│   → See all functions, classes, interfaces (~1K tokens)
├── Step 2: Identify relevant symbols from outline
├── Step 3: heraspec explore unfold <file> <symbol>
│   → Read just the relevant function (~400-2K tokens)
└── Only read full file if you need comprehensive understanding

Need to find where something is?
├── heraspec explore search "<name>" <path>
│   → Find symbol locations across codebase
├── Then use unfold to read specific implementations
└── Avoid grep-like full-text search when possible

Key Principles

1. Outline first, read later: Always check the outline before reading full files
2. Unfold specific symbols: Don't read entire files when you only need one function
3. Search before browsing: Find what you need by name rather than scanning directories
4. Skip node_modules, dist, .git: Automatically excluded from search

Limitations

• Uses regex-based parsing (not AST) — may miss some complex patterns
• Symbol end-line detection is approximate (brace/indent counting)
• Method detection within classes requires proper indentation
• Does not handle dynamically generated code or macros