semantic-search

What this skill does

## Quick Example

```bash
odino query -q "error handling exceptions"
# Output shows files ranked by relevance:
# knowledge/Error Handling.md (0.876)
# middleware/errorHandler.js (0.745)
# schemas/validation.js (0.689)
```

# Semantic Search

## Overview

Enable natural language semantic search across codebases and notes using odino CLI with BGE embeddings. Unlike grep (exact text matching) or glob (filename patterns), semantic search finds code by what it does, not what it's called.

## When to Use This Skill

Automatically invoke semantic search when the user:
- Asks "where is [concept]" or "how does [feature] work"
- Wants to find implementation of a concept/pattern
- Needs to understand codebase structure around a topic
- Searches for patterns by meaning, not exact text
- Asks exploratory questions like "show me authentication logic"

**Do not use** for:
- Exact string matching (use grep)
- Filename patterns (use glob)
- Known file paths (use read)
- When the user explicitly requests grep/glob

## Directory Traversal Logic

Odino requires running commands from the directory containing `.odino/` config. To make this transparent (like git), use this helper function:

```bash
# Function to find .odino directory by traversing up the directory tree
find_odino_root() {
    local dir="$PWD"
    while [[ "$dir" != "/" ]]; do
        if [[ -d "$dir/.odino" ]]; then
            echo "$dir"
            return 0
        fi
        dir="$(dirname "$dir")"
    done
    return 1
}

# Usage in commands
if ODINO_ROOT=$(find_odino_root); then
    echo "Found index at: $ODINO_ROOT"
    (cd "$ODINO_ROOT" && odino query -q "$QUERY")
else
    echo "No .odino index found in current path"
    echo "Suggestion: Run /semq:index to create an index"
fi
```

**Why this matters:**
- User can be in any subdirectory of their project
- Commands automatically find the project root (where `.odino/` lives)
- Mirrors git behavior (works from anywhere in the tree)

## Quick Start

### Check if Directory is Indexed

Before searching, verify an index exists:

```bash
if ODINO_ROOT=$(find_odino_root); then
    (cd "$ODINO_ROOT" && odino status)
else
    echo "No index found. Suggest running /semq:index"
fi
```

### Search Indexed Codebase

```bash
# Basic search
odino query -q "authentication logic"

# With directory traversal
if ODINO_ROOT=$(find_odino_root); then
    (cd "$ODINO_ROOT" && odino query -q "$QUERY")
fi
```

### Parse and Present Results

Odino returns results in a formatted table:
```
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ File                            ┃ Score    ┃ Content                         ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ knowledge/Search Algorithms.md  │ 0.361    │    1 ---                        │
│                                 │          │    2 tags: [todo/stub]          │
│                                 │          │    3 module: CMPU 4010          │
│                                 │          │   ...                           │
│                                 │          │    7 # Search Algorithms in AI  │
│                                 │          │   ...                           │
└─────────────────────────────────┴──────────┴─────────────────────────────────┘
Found 2 results
```

**Enhanced workflow:**
1. Parse table to extract file paths, scores, and content previews
2. Read top 2-3 results (score > 0.3) for full context
3. Summarize findings with explanations
4. Use code-pointer to open most relevant file
5. Suggest follow-up queries or related concepts

## Query Inference

Transform user requests into better semantic queries with realistic output examples.

### Example 1: Conceptual Query

**User asks:** "error handling"
**Inferred query:** `error handling exception management try catch validation`
**Sample odino output:**
```
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ File                            ┃ Score    ┃ Content                         ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ knowledge/Error Handling.md     │ 0.876    │    1 ---                        │
│                                 │          │    2 tags: [software-eng, best- │
│                                 │          │    3 ---                        │
│                                 │          │    4 # Error Handling           │
│                                 │          │    5                            │
│                                 │          │    6 Error handling is the proc │
│                                 │          │    7 runtime errors gracefully  │
│                                 │          │    8 system stability.          │
│                                 │          │    9                            │
│                                 │          │   10 ## Key Concepts            │
│                                 │          │   11 - Try-catch blocks for syn │
│                                 │          │   12 - Promise rejection handli │
│                                 │          │   13 - Input validation to prev │
│                                 │          │   14 - Logging errors for debug │
│                                 │          │   15 - User-friendly error mess │
│                                 │          │   16                            │
│                                 │          │   17 ## Best Practices          │
│                                 │          │   18 1. Fail fast - validate ea │
│                                 │          │   19 2. Log with context - incl │
│                                 │          │   20 3. Don't swallow errors -  │
└─────────────────────────────────┴──────────┴─────────────────────────────────┘
```

### Example 2: Code Query

**User asks:** "DB connection code"
**Inferred query:**
```
database connection pooling setup
import mysql.connector
pool = mysql.connector.pooling.MySQLConnectionPool(
    pool_name="mypool",
    pool_size=5,
    host="localhost",
    database="mydb"
)
connection = pool.get_connection()
```
**Sample odino output:**
```
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ File                            ┃ Score    ┃ Content                         ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ src/db/connection.js            │ 0.924    │    1 const mysql = require('mys │
│                                 │          │    2                            │
│                                 │          │    3 // Create connection pool  │
│                                 │          │    4 const pool = mysql.createP │
│                                 │          │    5   host: process.env.DB_HOS │
│                                 │          │    6   user: process.env.DB_USE │
│                                 │          │    7   password: process.env.DB │
│                                 │          │    8   database: process.env.DB │
│                                 │          │    9   waitForConnections: true │
│                                 │          │   10   connectionLimit: 10,     │
│                                 │          │   11   queueLimit: 0            │
│                                 │          │   12 });                        │
│                                 │          │   13                            │
│                                 │          │   14 // Test connection         │
│                                 │          │   15 pool.getConnection((err, c │
│                                 │          │   16   if (err) {               │
│                                 │          │   17     console.error('DB conn │
│                                 │          │   18     process.exit(1);       │
│                                 │          │   19   }                        │
│