gh-cadrianmae-claude-marketplace-plugins-semantic-search/skills/semantic-search/references/search_patterns.md

Effective Semantic Search Patterns

Guide to crafting effective semantic search queries and interpreting results.

Query Design Principles

Be Conceptual, Not Literal

Semantic search works best with conceptual queries that describe what the code does, not what it's named.

❌ Poor queries (too literal):

• "validateEmail" → Use grep instead
• "config.js" → Use glob instead
• "class AuthService" → Use grep instead
• "TODO" → Use grep instead

✅ Good queries (conceptual):

• "email validation logic"
• "configuration loading and parsing"
• "authentication service implementation"
• "incomplete features or pending work"

Use Natural Language

Write queries as you would explain the concept to a colleague.

❌ Keyword stuffing:

• "db connect pool config"

✅ Natural language:

• "database connection pooling configuration"

Be Specific When Needed

Balance specificity with generality based on what you're looking for.

Too general:

• "functions" → Will match everything
• "code" → Will match everything

Too specific:

• "JWT token validation using bcrypt with salt rounds set to 10" → Too narrow

Just right:

• "JWT token validation"
• "password hashing and verification"

Common Query Patterns

Finding Implementation

Pattern: "[concept] implementation" or "how [feature] works"

odino query -q "authentication implementation"
odino query -q "how caching works"
odino query -q "error handling implementation"

Finding Configuration

Pattern: "[system/feature] configuration" or "[thing] setup"

odino query -q "database configuration"
odino query -q "API endpoint setup"
odino query -q "logging configuration"

Finding Patterns

Pattern: "[pattern/technique] usage" or "examples of [pattern]"

odino query -q "middleware usage patterns"
odino query -q "dependency injection examples"
odino query -q "async/await error handling"

Finding by Purpose

Pattern: "code that [does something]" or "[action] logic"

odino query -q "code that validates user input"
odino query -q "file upload logic"
odino query -q "payment processing"

Finding Documentation

Pattern: "[topic] documentation" or "how to [task]"

odino query -q "API documentation"
odino query -q "how to deploy the application"
odino query -q "setup instructions"

Result Interpretation

Understanding Scores

Odino returns results with similarity scores (0.0 to 1.0):

• 0.85-1.0: Highly relevant, almost certainly what you're looking for
• 0.70-0.84: Likely relevant, worth checking
• 0.60-0.69: Possibly relevant, may contain related concepts
• <0.60: Weakly related, probably not useful

Example output:

Score: 0.92 | Path: src/auth/jwt.js          # Definitely check this
Score: 0.78 | Path: src/middleware/auth.js   # Likely relevant
Score: 0.64 | Path: src/utils/crypto.js      # Maybe related
Score: 0.51 | Path: src/config/index.js      # Probably not it

When to Read Files

Always read: Top 1-2 results (score > 0.80) Sometimes read: Next 2-3 results (score 0.65-0.80) for context Rarely read: Results with score < 0.65

Combining Results

Often the answer spans multiple files:

odino query -q "user authentication flow"

# Results might include:
# - Login endpoint (score: 0.89)
# - JWT generation (score: 0.85)
# - Password verification (score: 0.82)
# - Session management (score: 0.76)

Read top results to understand the complete picture.

Refinement Strategies

Too Many Results

Make query more specific:

# Too broad
odino query -q "validation"

# Better
odino query -q "email format validation"

Too Few Results

Make query more general:

# Too narrow
odino query -q "SHA256 password hashing with bcrypt"

# Better
odino query -q "password hashing"

Wrong Results

Try different phrasing:

# If "API endpoint handlers" doesn't work well
odino query -q "route definitions"
odino query -q "HTTP request handlers"
odino query -q "REST API implementation"

Advanced Patterns

Multi-Concept Queries

Combine related concepts for broader coverage:

odino query -q "authentication and authorization logic"
odino query -q "database queries and ORM usage"
odino query -q "error handling and logging"

Feature-Specific Queries

Target specific features or subsystems:

odino query -q "user registration feature"
odino query -q "shopping cart functionality"
odino query -q "notification system"

Cross-Cutting Concerns

Find patterns that span the codebase:

odino query -q "error handling patterns"
odino query -q "input validation across endpoints"
odino query -q "database transaction usage"

Query Examples by Use Case

Code Exploration

"I'm new to this codebase, where do I start?"

odino query -q "main application entry point"
odino query -q "core business logic"
odino query -q "primary data models"

Bug Hunting

"There's a bug in feature X, where's the code?"

odino query -q "user login functionality"
odino query -q "payment processing logic"
odino query -q "email sending implementation"

Refactoring

"I need to change how we do X across the codebase"

odino query -q "database connection creation"
odino query -q "API key validation"
odino query -q "date formatting and parsing"

Learning Patterns

"How does this codebase handle X?"

odino query -q "dependency injection patterns"
odino query -q "testing approach and examples"
odino query -q "configuration management"

When Semantic Search Doesn't Help

Use other tools when:

1. Exact string needed - Use grep

   grep -r "validateEmail" .
   

2. Filename patterns - Use glob or find

   find . -name "*config*.js"
   

3. Known file location - Use read directly

   # Just read the file
   cat src/config/database.js
   

4. Symbol definitions - Use language-specific tools

   # For Python
   grep -r "class AuthService" .
   
   # For JavaScript
   grep -r "export.*AuthService" .
   

Combining Tools Workflow

Best practice: Start semantic, narrow with grep/glob

# 1. Find the general area with semantic search
odino query -q "database migrations"
# → Found: migrations/2024-01-15-add-users.sql

# 2. Narrow to specific files/patterns
find migrations/ -name "*users*"

# 3. Search for exact strings in those files
grep -n "CREATE TABLE" migrations/*users*.sql

Tips for Better Results

1. Use verbs and nouns - "validates user input" not just "validation"
2. Include context - "email validation in registration" not just "email"
3. Think about purpose - What does the code do, not what it's called
4. Try synonyms - "authentication" vs "login" vs "sign in"
5. Be patient - Try 2-3 query variations if first doesn't work
6. Check top 3-5 results - Sometimes #3 is the best match
7. Combine with file reading - Read top results to confirm relevance

Anti-Patterns to Avoid

❌ Searching for variable names:

odino query -q "userEmail" # Use grep instead

❌ Searching for exact error messages:

odino query -q "Error: Connection refused" # Use grep instead

❌ Searching for file paths:

odino query -q "src/utils/validation.js" # Use find/glob instead

❌ Searching for TODOs/comments:

odino query -q "TODO fix this" # Use grep instead

❌ Overly generic queries:

odino query -q "code" # Way too broad

Summary

Good semantic queries are:

• Conceptual, not literal
• Natural language, not keywords
• Focused on purpose/behavior
• Appropriately specific

After getting results:

• Check scores (> 0.70 is good)
• Read top 2-3 files for context
• Combine with grep/glob for precision
• Iterate query if needed