deepsearch

name	deepsearch
description	Use when simple grep/glob is insufficient and you need comprehensive, multi-pass codebase understanding
user-invocable	false
allowed-tools	Read, Grep, Glob, Bash

Deep Search

Overview

Single-pass searches miss connections. Grep finds strings, not understanding.

Core principle: ALWAYS search in multiple passes with increasing precision. A single query never gives the full picture.

Violating the letter of this process is violating the spirit of thorough search.

The Iron Law

NO CONCLUSIONS WITHOUT CROSS-REFERENCED EVIDENCE FROM MULTIPLE PASSES

If you haven't completed at least Phases 1-3, your understanding is incomplete.

When to Use

Use when simple grep/glob is insufficient:

• Understanding how a feature works end-to-end
• Tracing data flow across multiple files/modules
• Finding all usages and side effects before refactoring
• Detecting dead code or unused exports
• Mapping dependency chains
• Understanding implicit relationships (event emitters, dynamic imports, reflection)
• Auditing a pattern's usage across the codebase

Use this ESPECIALLY when:

• Initial search returns too many or too few results
• You need to understand "everything that touches X"
• The codebase uses indirection (dependency injection, plugins, event systems)
• You're about to make a breaking change
• You need confidence that nothing was missed

Don't use when:

• You know the exact file and symbol (use direct read)
• A single grep gives you the complete answer
• You're looking up a specific API signature

The Four Phases

You MUST complete each phase before drawing conclusions.

Phase 1: Broad Search — Cast a Wide Net

Goal: Discover all potentially relevant files and symbols.

1. Start with Multiple Search Strategies

   • Search by name: function names, class names, variable names
   • Search by pattern: string literals, error messages, log statements
   • Search by structure: file naming conventions, directory patterns
   • Search by type: imports, exports, type definitions

2. Use Varied Query Terms

   • Don't stop at the first query term
   • Try synonyms, abbreviations, related concepts
   • Search for both the interface and the implementation
   • Include test files — they reveal intended usage

3. Record Everything

   • Note every file that appears relevant
   • Note unexpected hits — they often reveal hidden connections
   • Note files that should have matched but didn't

Output: A list of all candidate files and symbols to investigate.

Phase 2: Narrow Focus — Understand Each Hit

Goal: Read and understand each candidate in context.

1. Classify Each Result

   • Definition vs. usage vs. re-export
   • Direct dependency vs. indirect dependency
   • Active code vs. dead code vs. test code

2. Read Surrounding Context

   • Don't just read the matching line — read the function/class
   • Check imports at the top of the file
   • Check exports at the bottom
   • Read adjacent functions for related logic

3. Build a Symbol Map

   • Where is it defined?
   • Where is it imported?
   • Where is it called/used?
   • What calls it? (reverse dependency)

4. Identify Indirection

   • Dynamic imports (import(), require())
   • String-based lookups (registries, plugin systems)
   • Event-driven connections (emit/on patterns)
   • Dependency injection (constructor injection, providers)
   • Configuration-driven behavior (feature flags, env vars)

Phase 3: Cross-Reference — Connect the Dots

Goal: Map relationships between all discovered symbols and files.

1. Trace Data Flow

   • Follow data from source to sink
   • Input → transform → output for each function in the chain
   • Note where data shape changes (serialization, mapping)

2. Trace Control Flow

   • What triggers this code path?
   • What conditions must be true?
   • What error paths exist?
   • What happens on failure?

3. Identify Dependency Chains

   • A imports B imports C — trace the full chain
   • Circular dependencies — note them explicitly
   • Shared dependencies — what else depends on the same module?

4. Check for Side Effects

   • Global state mutations
   • File system operations
   • Database writes
   • External API calls
   • Cache invalidation

5. Verify Completeness

   • For every "used by" reference, verify the reverse "depends on"
   • Look for orphaned code that nothing references
   • Check for dynamic/runtime references that static search misses

Phase 4: Validate — Confirm Your Understanding

Goal: Prove your mental model is correct.

1. Test Your Hypothesis

   • "If I change X, these files should be affected: [list]"
   • "This function is called in these scenarios: [list]"
   • "This code path is triggered by: [list]"
   • Verify each claim with evidence from the code

2. Check for Gaps

   • Are there files you expected to find but didn't?
   • Are there connections that seem missing?
   • Does the architecture diagram match the actual code?

3. Look for Dead Code

   • Exported but never imported
   • Defined but never called
   • Imported but never used
   • Behind feature flags that are always off

4. Verify with Tests

   • Do existing tests confirm your understanding?
   • Do test descriptions match your mental model?
   • Are there test cases for edge cases you identified?

5. Summarize Findings

   • List all files involved and their roles
   • Draw the dependency graph (text or description)
   • Note any risks, dead code, or inconsistencies found
   • Provide confidence level: high / medium / low

Red Flags — STOP and Search Deeper

If you catch yourself thinking:

• "This is probably the only place it's used"
• "I found one result, that must be it"
• "The naming convention tells me everything"
• "I don't need to check test files"
• "Dynamic imports won't matter here"
• "This module is self-contained"
• "I can skip Phase 3, the connections are obvious"

ALL of these mean: STOP. You're making assumptions. Return to Phase 1.

Common Rationalizations

Excuse	Reality
"Grep found it, I'm done"	Grep finds strings, not relationships. Continue to Phase 2.
"Only one file imports this"	Check for dynamic imports, re-exports, and test files.
"The naming is clear enough"	Names lie. Read the implementation.
"Tests aren't relevant"	Tests reveal intended behavior and edge cases. Always check.
"This is a small codebase"	Small codebases have hidden complexity too. Follow the process.
"I'll trace the rest later"	Incomplete understanding leads to broken refactors. Trace now.

Quick Reference

Phase	Key Activities	Success Criteria
1. Broad Search	Multiple strategies, varied terms, record all	Complete candidate list
2. Narrow Focus	Classify, read context, build symbol map	Understand each hit
3. Cross-Reference	Trace data/control flow, find dependencies	Map all relationships
4. Validate	Test hypothesis, check gaps, verify with tests	Confirmed mental model

Search Strategy Checklist

Use this checklist to ensure thorough coverage:

• Searched by symbol name (exact and substring)
• Searched by string literals and error messages
• Searched by file/directory naming patterns
• Checked imports and exports
• Checked test files for usage examples
• Checked configuration files
• Traced dynamic/runtime references
• Verified reverse dependencies
• Looked for event-driven connections
• Checked for dead/unused code