madappgang/code-search-selector

Code Search Tool Selector

This skill helps choose the most effective search tool for your task.

When Semantic Search Works Better

Claudemem provides better results for conceptual queries:

| Query Type | Example | Recommended Tool | |------------|---------|------------------| | "How does X work?" | "How does authentication work?" | claudemem search | | Find implementations | "Find all API endpoints" | claudemem search | | Architecture questions | "Map the service layer" | claudemem --agent map | | Trace data flow | "How does user data flow?" | claudemem search | | Audit integrations | "Audit Prime API usage" | claudemem search |

When Native Tools Work Better

| Query Type | Example | Recommended Tool | |------------|---------|------------------| | Exact string match | "Find 'DEPRECATED_FLAG'" | Grep | | Count occurrences | "How many TODO comments?" | Grep -c | | Specific symbol | "Find class UserService" | Grep | | File patterns | "Find all *.config.ts" | Glob |

Why Semantic Search is Often More Efficient

Token Efficiency: Reading 5 files costs ~5000 tokens; claudemem search costs ~500 tokens with ranked results.

Context Discovery: Claudemem finds related code you didn't know to ask for.

Ranking: Results sorted by relevance and PageRank, so important code comes first.

Example: Semantic Query

User asks: "How does authentication work?"

Less effective approach:

grep -r "auth" src/
# Result: 500 lines of noise, hard to understand

More effective approach:

claudemem status  # Check if indexed
claudemem search "authentication login flow JWT"
# Result: Top 10 semantically relevant code chunks, ranked

Quick Decision Guide

Classify the Task

| User Request | Category | Recommended Tool | |--------------|----------|------------------| | "Find all X", "How does X work" | Semantic | claudemem search | | "Audit X integration", "Map data flow" | Semantic | claudemem search | | "Understand architecture", "Trace X" | Semantic | claudemem map | | "Find exact string 'foo'" | Exact Match | Grep | | "Count occurrences of X" | Exact Match | Grep | | "Find symbol UserService" | Exact Match | Grep |

Step 2: Check claudemem Status (MANDATORY for Semantic)

# ALWAYS run this before semantic search
claudemem status

Interpret the output:

| Status | What It Means | Next Action | |--------|---------------|-------------| | Shows chunk count (e.g., "938 chunks") | ✅ Indexed | USE CLAUDEMEM (Step 3) | | "No index found" | ❌ Not indexed | Offer to index (Step 2b) | | "command not found" | ❌ Not installed | Fall back to Detective agent |

Step 2b: If Not Indexed, Offer to Index

AskUserQuestion({
  questions: [{
    question: "Claudemem is not indexed. Index now for better semantic search results?",
    header: "Index?",
    multiSelect: false,
    options: [
      { label: "Yes, index now (Recommended)", description: "Takes 1-2 minutes, enables semantic search" },
      { label: "No, use grep instead", description: "Faster but less accurate for semantic queries" }
    ]
  }]
})

If user says yes:

claudemem index -y

Step 3: Execute the Search

IF CLAUDEMEM IS INDEXED (from Step 2):

# Get role-specific guidance first
claudemem ai developer  # or architect, tester, debugger

# Then search semantically
claudemem search "authentication login JWT token validation" -n 15

IF CLAUDEMEM IS NOT AVAILABLE:

Use the detective agent:

Task({
  subagent_type: "code-analysis:detective",
  description: "Investigate [topic]",
  prompt: "Use semantic search to find..."
})

Tool Recommendations by Use Case

| Use Case | Less Efficient | More Efficient | |----------|----------------|----------------| | Semantic queries | grep -r "pattern" src/ | claudemem search "concept" | | Find implementations | Glob → Read all | claudemem search "feature" | | Understand flow | find . -name "*.ts" \| xargs... | claudemem --agent map |

Native tools (Grep, Glob, find) work well for exact matches but provide no semantic ranking.

---

When Hooks Redirect to Claudemem

If a hook provides claudemem results instead of native tool output:

1. Use the provided results - They're ranked by relevance
2. For more data - Run additional claudemem queries
3. Bypass available - Use _bypass_claudemem: true for native tools when needed

The hook system provides claudemem results proactively when the index is available.

---

Task-to-Tool Mapping Reference

| User Request | Native Approach | Semantic Approach (Recommended) | |--------------|-----------------|--------------------------------| | "Audit all API endpoints" | grep -r "router\|endpoint" | claudemem search "API endpoint route handler" | | "How does auth work?" | grep -r "auth\|login" | claudemem search "authentication login flow" | | "Find all database queries" | grep -r "prisma\|query" | claudemem search "database query SQL prisma" | | "Map the data flow" | grep -r "transform\|map" | claudemem search "data transformation pipeline" | | "What's the architecture?" | ls -la src/ | claudemem --agent map "architecture" | | "Find error handling" | grep -r "catch\|error" | claudemem search "error handling exception" | | "Trace user creation" | grep -r "createUser" | claudemem search "user creation registration" |

When Grep IS Appropriate

✅ Use Grep for:

• Finding exact string: grep -r "DEPRECATED_FLAG" src/
• Counting occurrences: grep -c "import React" src/**/*.tsx
• Finding specific symbol: grep -r "class UserService" src/
• Regex patterns: grep -r "TODO:\|FIXME:" src/

❌ Never use Grep for:

• Understanding how something works
• Finding implementations by concept
• Architecture analysis
• Tracing data flow
• Auditing integrations

Integration with Detective Skills

After using this skill's decision tree, invoke the appropriate detective:

| Investigation Type | Detective Skill | |-------------------|-----------------| | Architecture patterns | code-analysis:architect-detective | | Implementation details | code-analysis:developer-detective | | Test coverage | code-analysis:tester-detective | | Bug root cause | code-analysis:debugger-detective | | Comprehensive audit | code-analysis:ultrathink-detective |

Quick Reference Card

┌─────────────────────────────────────────────────────────────────┐
│                    CODE SEARCH QUICK REFERENCE                   │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  1. ALWAYS check first:  claudemem status                       │
│                                                                  │
│  2. If indexed:          claudemem search "semantic query"       │
│                                                                  │
│  3. For exact matches:   Grep tool (only this case!)            │
│                                                                  │
│  4. For deep analysis:   Task(code-analysis:detective)          │
│                                                                  │
│  ⚠️ GREP IS FOR EXACT MATCHES, NOT SEMANTIC UNDERSTANDING       │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Pre-Investigation Checklist

Before ANY code investigation task, verify:

• [ ] Ran claudemem status to check index
• [ ] Classified task as SEMANTIC or EXACT MATCH
• [ ] Selected appropriate tool based on classification
• [ ] NOT using grep for semantic queries when claudemem is indexed

---

Multi-File Read Optimization

When reading multiple files, consider if a semantic search would be more efficient:

| Scenario | Optimization | |----------|-------------| | Read 3+ files in same directory | Try claudemem search first | | Glob with broad patterns | Try claudemem --agent map | | Sequential reads to "understand" | One semantic query may suffice |

Quick check before bulk reads:

1. Is claudemem indexed? (claudemem status)
2. Can this be one semantic query instead of N file reads?

Interception Examples

❌ About to do:

Read src/services/auth/login.ts
Read src/services/auth/session.ts
Read src/services/auth/jwt.ts
Read src/services/auth/middleware.ts
Read src/services/auth/types.ts
Read src/services/auth/utils.ts

✅ Do instead:

claudemem search "authentication login session JWT middleware" -n 15

❌ About to do:

Glob pattern: src/services/prime/**/*.ts
Then read all 12 matches sequentially

✅ Do instead:

claudemem search "Prime API integration service endpoints" -n 20

❌ Parallelization trap:

"Let me Read these 5 files while the detective agent works..."

✅ Do instead:

Trust the detective agent to use claudemem.
Don't duplicate work with inferior Read/Glob.

---

Efficiency Comparison

| Approach | Token Cost | Result Quality | |----------|------------|----------------| | Read 5+ files sequentially | ~5000 tokens | No ranking | | Glob → Read all matches | ~3000+ tokens | No semantic understanding | | claudemem search once | ~500 tokens | Ranked by relevance |

Tip: Claudemem results include context around matches, so you often don't need to read full files.

---

Recommended Workflow

1. Check index: claudemem status
2. Search semantically: claudemem search "concept query" -n 15
3. Read specific code: Use results to target file:line reads

This workflow finds relevant code faster than reading files sequentially.

---

Maintained by: MadAppGang Plugin: code-analysis v2.16.0 Purpose: Help choose the most efficient search tool for each task