{"manifest":{"name":"Search Before Read","version":"1.0.0","description":"A context-efficiency protocol that cuts token usage by 60-70% when navigating large codebases by searching for specific symbols before loading files.","tags":["productivity","tokens","context","search","efficiency"],"standard":"agentskills.io","standard_version":"1.0","content_checksum":"1de539a98cc145f7564f7f10b2797d2fa1411544bdb0a02f0443c172b9a379bf","bundle_checksum":null,"metadata":{},"files":[]},"files":{"SKILL.md":"# Search Before Read\n\nA context-efficiency protocol that cuts token usage by 60–70% when navigating large codebases by searching for specific symbols before loading files.\n\n## Overview\n\nThe default pattern — \"read the file to understand what's happening\" — is the most expensive mistake in AI-assisted code navigation. A 500-line file loaded to find one function wastes 490 lines of context. This skill teaches a systematic alternative: search first, read targeted ranges only.\n\n**Inspired by the QMD (Query-Map-Dive) pattern from community codebase efficiency research.**\n\n## Core Protocol\n\n### Rule 1: Never Read a File Over 200 Lines Without Searching First\n\nIf you don't know where in a file the relevant code lives, searching is always cheaper than reading.\n\n```\n# Instead of:\nRead(file_path=\"/src/auth/middleware.ts\")  # 847 lines loaded\n\n# Do this:\nGrep(pattern=\"validateToken\", path=\"/src/auth/middleware.ts\", output_mode=\"content\")\n# Returns: lines 147-163 — now read only those\nRead(file_path=\"/src/auth/middleware.ts\", offset=145, limit=25)\n```\n\nToken cost comparison:\n- Read entire file: ~2,000 tokens\n- Grep + targeted Read: ~150 tokens\n- Savings: ~1,850 tokens per lookup\n\n### Rule 2: Search for Specific Symbols, Not Understanding\n\n\"Understanding the codebase\" is not a search goal. Specific symbols are.\n\n```\n# Vague (leads to over-reading):\n\"Let me understand how authentication works\"\n→ Reading 5 files × 300 lines = 1,500 lines loaded\n\n# Specific (targeted search):\n\"Find where verifyJWT is called\"\nGrep(pattern=\"verifyJWT\", output_mode=\"files_with_matches\")\n→ Returns 2 files → read only the relevant function in each\n```\n\n**Before starting any task, identify the specific symbol, function name, or error message you need to locate.**\n\n### Rule 3: Build a Symbol Map Before Implementation\n\nFor any task touching more than one file, spend 5 searches building a mental map before touching any code.\n\n**Symbol map protocol:**\n1. Find the entry point (route handler, component, or function the task relates to)\n2. Find the data types it uses\n3. Find where those types are defined\n4. Find the test file for the target\n5. Grep for any existing similar implementation\n\nTotal: 5 targeted searches, ~200 tokens. Far cheaper than reading 3–5 files in full.\n\n### Rule 4: Use Glob to Find Files First\n\nWhen you don't know which file contains what you need, glob before grepping.\n\n```\n# Step 1: Find candidate files\nGlob(pattern=\"**/auth*.ts\")\n# Returns: auth.ts, auth-helpers.ts, auth-middleware.ts\n\n# Step 2: Grep the specific symbol in candidates only\nGrep(pattern=\"refreshToken\", path=\"/src/lib/supabase/auth-helpers.ts\")\n# Returns: exact line range\n\n# Step 3: Read only that range\n```\n\n### Rule 5: Read Targeted Line Ranges When Structure is Known\n\nOnce you know approximately where something is, use offset+limit to load only what you need.\n\n```\n# Good pattern:\n# You know the function starts around line 80 from the Grep result\nRead(file_path=\"route.ts\", offset=78, limit=40)\n\n# Bad pattern (same file, 350 lines long):\nRead(file_path=\"route.ts\")  # loads 310 unnecessary lines\n```\n\n**Heuristics for range sizing:**\n- A typical function: 20–50 lines → limit=60 to be safe\n- A route handler: 50–100 lines → limit=120\n- A class: varies — Grep for method names first, then read each\n\n### Rule 6: Token Budget Awareness\n\nBefore loading any file, estimate context cost:\n\n| File size | Token cost | Load it? |\n|---|---|---|\n| < 50 lines | ~200 tokens | Yes, always |\n| 50–200 lines | 200–800 tokens | Yes if relevant |\n| 200–500 lines | 800–2,000 tokens | Only targeted range |\n| 500–2,000 lines | 2,000–8,000 tokens | Grep first, always |\n| > 2,000 lines | > 8,000 tokens | Never load in full |\n\nFor files > 500 lines, full reads are almost never justified. There is always a more targeted search.\n\n## Search Patterns Reference\n\n### Finding a function definition\n```\nGrep(pattern=\"function getUserById|getUserById = |getUserById:\", type=\"ts\")\n```\n\n### Finding all callers of a function\n```\nGrep(pattern=\"getUserById\\(\", output_mode=\"files_with_matches\")\n```\n\n### Finding a type/interface\n```\nGrep(pattern=\"^(export )?(interface|type) UserProfile\", type=\"ts\")\n```\n\n### Finding all usages of a constant\n```\nGrep(pattern=\"SKILLS_COLUMNS\", output_mode=\"content\", -C=2)\n```\n\n### Finding a test for a specific route\n```\nGlob(pattern=\"tests/**/*tips*.test.ts\")\n```\n\n### Finding where an error is thrown\n```\nGrep(pattern=\"'Skill not found'\", output_mode=\"content\")\n```\n\n## Anti-Patterns to Avoid\n\n**\"Let me read the whole project structure first\"**\n→ Waste. Read structure only for the specific area you're modifying.\n\n**Reading a file \"to understand\" then not using 80% of it**\n→ Stop. Define what you need before you load anything.\n\n**Re-reading files you already searched**\n→ Keep a mental or written note of what each file contains. Don't reload.\n\n**Grepping for a concept, not a symbol**\n→ `Grep(pattern=\"authentication\")` returns 200 hits. `Grep(pattern=\"verifyJWT\\(\")` returns 3.\n\n**Loading test files to understand production code**\n→ Test files describe behavior but are noisy for understanding structure. Use production code + types first.\n\n## Session Start Ritual\n\nFor any non-trivial coding task, before writing code:\n\n```\n1. State the specific goal in one sentence\n2. Identify the 1–3 files most likely affected\n3. Grep for the specific entry point or function\n4. Read only the relevant range\n5. Identify any types or helpers needed (glob/grep those too)\n6. Now write code\n```\n\nTotal search investment: 5–10 targeted operations, ~300–500 tokens.\nThis prevents the 3,000-token \"read everything first\" approach.\n"}}