Search Hierarchy

by parcadeid07ff4b06b62No license3.9K starsListed Oct 8, 2026Updated Oct 8, 2026Repository updated 8 months ago

Search Tool Hierarchy

Instructions onlySoftware Development AI & Agents

AI-generated overview

Guides agents to pick the most token-efficient code search tool: AST-grep, LEANN, Grep, or Read.

What it does: This skill provides a decision tree and token-efficiency comparison for choosing among four code search tools: AST-grep for structural patterns, LEANN for semantic questions, Grep for literal identifiers, and Read for full context. It lists do's and don'ts, example commands, and an optimal flow that starts with AST-grep and reads only the top match. It also describes a hook, grep-to-leann.sh, that detects query type and blocks or redirects queries to the suggested tool.
When to use it: Use it when searching a codebase and deciding which search tool to run for a given query type. It is meant for agents that want to reduce token usage by avoiding broad Grep or premature file reads.
Requirements: No scripts ship with the skill; it is instructions only. It references external tools (AST-grep, LEANN, Grep, Read) and a hook named grep-to-leann.sh, which are not included.

Search Tool Hierarchy

Use the most token-efficient search tool for each query type.

Decision Tree

Query Type?├── STRUCTURAL (code patterns)│   → AST-grep (~50 tokens output)│   Examples: "def foo", "class Bar", "import X", "@decorator"│├── SEMANTIC (conceptual questions)│   → LEANN (~100 tokens if path-only)│   Examples: "how does auth work", "find error handling patterns"│├── LITERAL (exact identifiers)│   → Grep (variable output)│   Examples: "TemporalMemory", "check_evocation", regex patterns│└── FULL CONTEXT (need complete understanding)    → Read (1500+ tokens)    Last resort after finding the right file

Query Type?├── STRUCTURAL (code patterns)│   → AST-grep (~50 tokens output)│   Examples: "def foo", "class Bar", "import X", "@decorator"│├── SEMANTIC (conceptual questions)│   → LEANN (~100 tokens if path-only)│   Examples: "how does auth work", "find error handling patterns"│├── LITERAL (exact identifiers)│   → Grep (variable output)│   Examples: "TemporalMemory", "check_evocation", regex patterns│└── FULL CONTEXT (need complete understanding)    → Read (1500+ tokens)    Last resort after finding the right file

Token Efficiency Comparison

Tool	Output Size	Best For
AST-grep	~50 tokens	Function/class definitions, imports, decorators
LEANN	~100 tokens	Conceptual questions, architecture, patterns
Grep	~200-2000	Exact identifiers, regex, file paths
Read	~1500+	Full understanding after finding the file

Hook Enforcement

The grep-to-leann.sh hook automatically:

Detects query type (structural/semantic/literal)
Blocks and suggests AST-grep for structural queries
Blocks and suggests LEANN for semantic queries
Allows literal patterns through to Grep

DO

Start with AST-grep for code structure questions
Use LEANN for "how does X work" questions
Use Grep only for exact identifier matches
Read files only after finding them via search

DON'T

Use Grep for conceptual questions (returns nothing)
Read files before knowing which ones are relevant
Use Read when AST-grep would give file:line
Ignore hook suggestions

Examples

bash

# STRUCTURAL → AST-grepast-grep --pattern "async def $FUNC($$$):" --lang python
# SEMANTIC → LEANNleann search opc-dev "how does authentication work" --top-k 3
# LITERAL → GrepGrep pattern="check_evocation" path=opc/scripts
# FULL CONTEXT → Read (after finding file)Read file_path=opc/scripts/z3_erotetic.py

# STRUCTURAL → AST-grepast-grep --pattern "async def $FUNC($$$):" --lang python
# SEMANTIC → LEANNleann search opc-dev "how does authentication work" --top-k 3
# LITERAL → GrepGrep pattern="check_evocation" path=opc/scripts
# FULL CONTEXT → Read (after finding file)Read file_path=opc/scripts/z3_erotetic.py

Optimal Flow

1. AST-grep: "Find async functions" → 3 file:line matches2. Read: Top match only → Full understanding3. Skip: 4 irrelevant files → 6000 tokens saved

1. AST-grep: "Find async functions" → 3 file:line matches2. Read: Top match only → Full understanding3. Skip: 4 irrelevant files → 6000 tokens saved

Source and attribution

Source:parcadei/continuous-claude-v3in.claude/skills/archive/search-hierarchyat commitd07ff4b

License: No license

Content belongs to its original authors. SourceWeft indexes it from a public repository.

Report or request removal

Search Hierarchy

Search Tool Hierarchy

Decision Tree

Token Efficiency Comparison

Hook Enforcement

DO

DON'T

Examples

Optimal Flow

Source and attribution

More from parcadei/continuous-claude-v3

Tldr Stats

Wiring

Workflow Router

Validate Agent

Tour

Tldr Overview

More in Software Development

Playground

M5 Onboard

Cardputer Buddy

Web Design Guidelines

Vercel React Native Skills

Vercel React Best Practices