search-ladder

name	search-ladder
description	Offload code search to deterministic tools instead of hand-grepping or reading whole files (P1). Climb the ladder lexical → structural → semantic, stopping at the first rung that answers. Use whenever locating symbols, call sites, definitions, or concepts in a repo.

Search Ladder Skill (P1)

Purpose

Never hand-grep, never read a whole file to "look around." Each search is one offloaded call whose result is file:line + ~2 lines (P0/P8). Climb only as far as needed.

The ladder (stop at first rung that answers)

1. Lexical — ripgrep (default). Exact strings, identifiers, regex.

   rg -n "createSession" --type ts | head -50
   rg -n "TODO|FIXME" -g '!*.test.*' | head -50
   

2. Structural — Probe (when code structure matters more than exact text).

   probe search "auth middleware" ./src
   

3. Semantic — mgrep — concept queries only, last resort (cost + noise).

   mgrep "where is rate limiting enforced" src/
   

Rules

• Pipe high-frequency searches to | head — bounded output (P0).
• Prefer structural search over regex when text is too brittle.
• Drop to semantic only when you cannot name the token — never as rung 1.
• Optional tools may be absent; fall back down the ladder (probe missing → rg).

Need concrete recipes for a rung (regex flags, Probe queries, mgrep phrasing)? Read references/ladder.md.