Code Semantic Search

---
name: code-semantic-search
description: Semantic code search using Phase 1 vector embeddings and Phase 2 hybrid search.
version: 1.1.0
model: sonnet
invoked_by: user
user_invocable: true
tools: [Read, Write, Edit]
verified: true
lastVerifiedAt: 2026-02-22T00:00:00.000Z
source: builtin
trust_score: 100
provenance_sha: d746c795259650f7
---

# Code Semantic Search

## Overview

Semantic code search using Phase 1 vector embeddings and Phase 2
hybrid search (semantic + structural). Find code by meaning, not
just keywords.

**Core principle:** Search code by what it does, not what it's called.

## Phase 2: Hybrid Search

This skill now supports three search modes:

1. **Hybrid (Default)**:
   - Combines semantic + structural search
   - Best accuracy (95%+)
   - Slightly slower but still <150ms
   - Recommended for all searches

2. **Semantic-Only**:
   - Uses only Phase 1 semantic vectors
   - Fastest (<50ms)
   - Good for conceptual searches
   - Use when structure doesn't matter

3. **Structural-Only**:
   - Uses only ast-grep patterns
   - Precise for exact matches
   - Best for finding function/class definitions
   - Use when you need exact structural patterns

### Performance Comparison

| Mode            | Speed  | Accuracy | Best For          |
| --------------- | ------ | -------- | ----------------- |
| Hybrid          | <150ms | 95%      | General search    |
| Semantic-only   | <50ms  | 85%      | Concepts          |
| Structural-only | <50ms  | 100%     | Exact patterns    |
| Phase 1 only    | <50ms  | 80%      | Legacy (fallback) |

## When to Use

**Always:**

- Finding authentication logic without knowing function names
- Searching for error handling patterns
- Locating database queries
- Finding similar code to a concept
- Discovering implementation patterns

**Don't Use:**

- Exact text matching (use Grep instead)
- File name searches (use Glob instead)
- Simple keyword searches (use ripgrep instead)

## Usage Examples

### Hybrid Search (Recommended)

```javascript
// Basic hybrid search
Skill({ skill: 'code-semantic-search', args: 'find authentication logic' });

// With options
Skill({
  skill: 'code-semantic-search',
  args: 'database queries',
  options: {
    mode: 'hybrid',
    language: 'javascript',
    limit: 10,
  },
});
```

### Semantic-Only Search

```javascript
// Fast conceptual search
Skill({
  skill: 'code-semantic-search',
  args: 'find authentication',
  options: { mode: 'semantic-only' },
});
```

### Structural-Only Search

```javascript
// Exact pattern matching
Skill({
  skill: 'code-semantic-search',
  args: 'find function authenticate',
  options: { mode: 'structural-only' },
});
```

## Implementation Reference

**Hybrid Search:** `.claude/lib/code-indexing/hybrid-search.cjs`

**Query Analysis:** `.claude/lib/code-indexing/query-analyzer.cjs`

**Result Ranking:** `.claude/lib/code-indexing/result-ranker.cjs`

## Integration Points

- **developer**: Code exploration, implementation discovery
- **architect**: System understanding, pattern analysis
- **code-reviewer**: Finding similar patterns, consistency checks
- **reverse-engineer**: Understanding unfamiliar codebases
- **researcher**: Research existing implementations

## Iron Laws

1. **ALWAYS use hybrid mode (semantic + structural) for general searches** — semantic-only misses exact matches; structural-only misses conceptual variants; hybrid provides 95% accuracy vs 85% for single mode.
2. **ALWAYS use ripgrep/keyword search first for fast keyword discovery** — semantic search is for meaning-based queries; exact strings, function names, and filenames are found faster with ripgrep.
3. **NEVER use semantic search without a meaningful natural-language query** — single-word or code-syntax queries produce poor semantic results; describe what the code does, not what it's called.
4. **ALWAYS combine with code-structural-search for precision refinement** — start broad with semantic discovery, then use ast-grep patterns to find exact structural matches from the semantic results.
5. **NEVER ignore low-similarity results without checking them** — similarity scores are approximations; a 0.7 score result may be more relevant than a 0.9 score result for uncommon patterns.

## Anti-Patterns

| Anti-Pattern                                          | Why It Fails                                       | Correct Approach                                                            |
| ----------------------------------------------------- | -------------------------------------------------- | --------------------------------------------------------------------------- |
| Semantic search for exact string matching             | Slower and less accurate than text search          | Use ripgrep/Grep for exact keyword matching                                 |
| Single-word queries ("auth")                          | Too vague for semantic matching; returns noise     | Use natural-language descriptions ("authentication token validation logic") |
| Using semantic-only mode for general searches         | Misses structural variants; 85% vs 95% accuracy    | Use hybrid mode (default) for general queries                               |
| Ignoring search results that don't match expectations | Semantic results find surprising-but-relevant code | Read all results; unexpected matches are often the most valuable            |
| Not combining with structural search                  | Finds concepts but not exact patterns              | Use semantic for discovery → structural for precision                       |

## Memory Protocol (MANDATORY)

**Before starting:**
Read `.claude/context/memory/learnings.md`

**After completing:**

- New pattern -> `.claude/context/memory/learnings.md`
- Issue found -> `.claude/context/memory/issues.md`
- Decision made -> `.claude/context/memory/decisions.md`

> ASSUME INTERRUPTION: If it's not in memory, it didn't happen.