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:**
```bash
grep -r "auth" src/
# Result: 500 lines of noise, hard to understand
```

**More effective approach:**
```bash
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)

```bash
# 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

```typescript
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:
```bash
claudemem index -y
```

### Step 3: Execute the Search

**IF CLAUDEMEM IS INDEXED (from Step 2):**

```bash
# 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:
```typescript
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:**
```bash
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:**
```bash
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