GrepAI Search Tips
This skill provides tips and best practices for writing effective semantic search queries.
When to Use This Skill
- Improving search result quality
- Learning semantic search techniques
- Understanding how to phrase queries
- Troubleshooting poor search results
Semantic Search Mindset
Think differently from text search:
| Text Search (grep) |
Semantic Search (GrepAI) |
| Search for exact text |
Search for meaning/intent |
| "getUserById" |
"retrieve user from database by ID" |
| Literal match |
Conceptual match |
Query Writing Principles
1. Describe Intent, Not Implementation
❌ Bad: getUserById
✅ Good: fetch user record from database using ID
❌ Bad: handleError
✅ Good: error handling and response to client
❌ Bad: validateInput
✅ Good: check if user input is valid and safe
2. Use Descriptive Language
❌ Bad: auth
✅ Good: user authentication and authorization
❌ Bad: db
✅ Good: database connection and queries
❌ Bad: config
✅ Good: application configuration loading
3. Be Specific About Context
❌ Bad: validation
✅ Good: validate email address format
❌ Bad: parse
✅ Good: parse JSON request body
❌ Bad: send
✅ Good: send email notification to user
4. Use 3-7 Words
| Length |
Example |
Quality |
| Too short |
"auth" |
⚠️ Vague |
| Good |
"user authentication middleware" |
✅ Specific |
| Too long |
"the code that handles user authentication and validates JWT tokens in the middleware layer" |
⚠️ Verbose |
5. Use English
Embedding models are trained primarily on English:
❌ authentification utilisateur (French)
✅ user authentication
Even if your code comments are in another language, English queries work best.
Query Patterns
Finding Code by Behavior
grepai search "validate user credentials before login"
grepai search "send notification when order is placed"
grepai search "calculate total price with discounts"
grepai search "retry failed HTTP requests"
Finding Code by Purpose
grepai search "middleware that checks authentication"
grepai search "function that formats dates"
grepai search "service that sends emails"
grepai search "handler for payment processing"
Finding Error Handling
grepai search "handle errors from API calls"
grepai search "catch and log exceptions"
grepai search "error response to client"
grepai search "validation error messages"
Finding Data Operations
grepai search "save user to database"
grepai search "query products by category"
grepai search "cache frequently accessed data"
grepai search "transform data before storage"
Finding Configuration
grepai search "load configuration from environment"
grepai search "database connection settings"
grepai search "API keys and secrets management"
grepai search "feature flags and toggles"
Finding Security Code
grepai search "password hashing and verification"
grepai search "input sanitization to prevent injection"
grepai search "rate limiting for API endpoints"
grepai search "CORS configuration"
Iterative Refinement
If results aren't good, iterate:
Start Broad
grepai search "authentication"
Add Context
grepai search "JWT authentication"
Be Specific
grepai search "JWT token validation middleware"
Using Synonyms
Semantic search understands synonyms. Try different phrasings:
grepai search "user authentication"
grepai search "user login verification"
grepai search "credential validation"
grepai search "identity verification"
Domain-Specific Terms
Use your domain vocabulary:
grepai search "shopping cart checkout process"
grepai search "inventory stock management"
grepai search "transaction processing"
grepai search "payment reconciliation"
grepai search "patient record retrieval"
grepai search "appointment scheduling"
Question-Style Queries
Natural questions work well:
grepai search "how are users authenticated"
grepai search "where is the database connection configured"
grepai search "what happens when a request fails"
grepai search "how are errors logged"
Avoiding Common Mistakes
❌ Don't Use Exact Function Names
If you know the exact name, use grep:
grep -r "getUserById" .
GrepAI is for when you don't know the exact name:
grepai search "retrieve user from database"
❌ Don't Be Too Abstract
grepai search "business logic"
grepai search "calculate order total with tax"
❌ Don't Use Code Syntax
grepai search "function() { return }"
grepai search "function that returns early"
❌ Don't Over-Specify
grepai search "async function in TypeScript file that uses axios to fetch"
grepai search "fetch data from external API"
Interpreting Results
High Scores (0.85+)
Strong match. The code likely does what you described.
Medium Scores (0.70-0.84)
Related code. May be what you want, or adjacent functionality.
Low Scores (0.60-0.69)
Loosely related. Consider refining your query.
Very Low Scores (<0.60)
Weak match. The concept may not exist in the codebase, or query needs rework.
When GrepAI Doesn't Find Results
- Check the index:
grepai status
- Verify files are indexed: Not in ignore patterns?
- Try simpler query: Remove specificity
- Try different words: Use synonyms
- Check if code exists: Maybe it doesn't yet!
Quick Reference Card
| Situation |
Query Style |
| Know the behavior |
"validates email format" |
| Know the domain |
"payment processing flow" |
| Exploring |
"how errors are handled" |
| Finding entry points |
"main application startup" |
| Finding dependencies |
"where database is connected" |
Output Format
Tips summary:
📝 GrepAI Search Tips
✅ DO:
- Describe intent, not implementation
- Use 3-7 descriptive words
- Use English queries
- Iterate and refine
❌ DON'T:
- Use exact function names (use grep)
- Write too short queries ("auth")
- Write too long queries
- Use code syntax in queries
Example transformations:
"auth" → "user authentication and login"
"getUserById" → "fetch user by ID from database"
"handleError" → "error handling and logging"
