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 d