search-interceptor

# Search Interceptor

This skill helps optimize bulk file operations by suggesting semantic search alternatives when they would be more efficient.

## When Semantic Search is More Efficient

| Scenario | Token Cost | Alternative |
|----------|------------|-------------|
| Read 5+ files | ~5000 tokens | `claudemem search` (~500 tokens) |
| Glob all *.ts files | ~3000+ tokens | `claudemem --agent map` |
| Sequential reads to understand | Variable | One semantic query |

## When to Consider Alternatives

### Multiple File Reads

If planning to read several files, consider:
```bash
# Instead of reading 5 files individually
claudemem search "concept from those files" -n 15
# Gets ranked results with context
```

### Broad Glob Patterns

If using patterns like `src/**/*.ts`:
```bash
# Instead of globbing and reading all matches
claudemem --agent map "what you're looking for"
# Gets structural overview with PageRank ranking
```

### File Paths Mentioned in Task

Even when specific paths are mentioned, semantic search often finds additional relevant code:
```bash
claudemem search "concept related to mentioned files"
```

---

## Interception Protocol

### Step 1: Pause Before Execution

When you're about to execute bulk file operations, STOP and run:

```bash
claudemem status
```

### Step 2: Evaluate

**If claudemem is indexed:**

| Your Plan | Better Alternative |
|-----------|-------------------|
| Read 5 auth files | `claudemem search "authentication login session"` |
| Glob all services | `claudemem search "service layer business logic"` |
| Read mentioned paths | `claudemem search "[concept from those paths]"` |

**If claudemem is NOT indexed:**

```bash
claudemem index -y
```
Then proceed with semantic search.

### Step 3: Execute Better Alternative

```bash
# Instead of reading N files, run ONE semantic query
claudemem search "concept describing what you need" -n 15

# ONLY THEN read specific lines from results
```

---

## Interception Decision Matrix

| Situation | Intercept? | Action |
|-----------|-----------|--------|
| Read 1-2 specific files | No | Proceed with Read |
| Read 3+ files in investigation | **YES** | Convert to claudemem search |
| Glob for exact filename | No | Proceed with Glob |
| Glob for pattern discovery | **YES** | Convert to claudemem search |
| Grep for exact string | No | Proceed with Grep |
| Grep for semantic concept | **YES** | Convert to claudemem search |
| Files mentioned in prompt | **YES** | Search semantically first |

---

## Examples of Interception

### Example 1: Auth Investigation

**❌ Original plan:**
```
I see the task mentions auth, let me read:
- src/services/auth/login.ts
- src/services/auth/session.ts
- src/services/auth/jwt.ts
- src/services/auth/middleware.ts
- src/services/auth/utils.ts
```

**✅ After interception:**
```bash
claudemem status  # Check if indexed
claudemem search "authentication login session JWT token validation" -n 15
# Now I have ranked, relevant chunks instead of 5 full files
```

### Example 2: API Integration Audit

**❌ Original plan:**
```
Audit mentions Prime API files:
- src/services/prime/internal_api/client.ts
- src/services/prime/api.ts
Let me just Read these directly...
```

**✅ After interception:**
```bash
claudemem search "Prime API integration endpoints HTTP client" -n 20
# This finds ALL Prime-related code, ranked by relevance
# Not just the 2 files mentioned
```

### Example 3: Pattern Discovery

**❌ Original plan:**
```
Glob("src/**/*.controller.ts")
Then read all 15 controllers to understand routing
```

**✅ After interception:**
```bash
claudemem search "HTTP controller endpoint route handler" -n 20
# Gets the most relevant routing code, not all controllers
```

---

## Why Semantic Search Often Works Better

| Native Tools | Semantic Search |
|--------------|-----------------|
| No ranking | Ranked by relevance + PageRank |
| No relationships | Shows code connections |
| ~5000 tokens for 5 files | ~500 tokens for ranked results |
| Only explicitly requested code | Discovers related code |

**Tip:** For investigation tasks, try `claudemem search` first to get a ranked view of relevant code.

---

## Integration with Other Skills

This skill works with:

| Skill | Relationship |
|-------|-------------|
| `code-search-selector` | Selector determines WHAT tool; Interceptor validates BEFORE execution |
| `claudemem-search` | Interceptor redirects to claudemem; this skill shows HOW to search |
| `deep-analysis` | Interceptor prevents bad patterns; deep-analysis uses good patterns |
| Detective skills | Interceptor prevents duplicate work by trusting detective agents |

---

## Hook System Integration

The hook system may provide claudemem results proactively when the index is available:

- **Grep queries** → May receive claudemem search results instead
- **Bulk reads** → May receive suggestion to use semantic search
- **Broad globs** → May receive map results

### Using the Bypass Flag

When you specifically need native tool behavior:
```json
{ "pattern": "exact string", "_bypass_claudemem": true }
```

This tells hooks you intentionally want native tool output.

---

## Quick Reference

Before bulk Read/Glob operations, consider:

1. **Is claudemem indexed?** → `claudemem status`
2. **Can this be one semantic query?** → Often yes
3. **Do you need exact matches?** → Use native tools with bypass flag

**General guideline:** For understanding/investigation, try semantic search first. For exact matches, use native tools.

---

**Maintained by:** MadAppGang
**Plugin:** code-analysis v2.16.0
**Purpose:** Help optimize bulk file operations with semantic search alternatives