# Grep Pattern Reference for Documentation Skills

This guide teaches how to create effective grep patterns for documentation discovery without loading entire files into context.

## Core Principles

**1. Specificity vs Generality**
- Too specific: `rg "function createDatabaseConnection() {"` - won't match variations
- Too general: `rg "function"` - returns thousands of useless matches
- Just right: `rg "createDatabaseConnection"` - finds all references

**2. Case Sensitivity**
- Default `rg` is case-sensitive
- Use `-i` for case-insensitive searches
- Example: `rg -i "transaction"` finds "Transaction", "TRANSACTION", "transaction"

**3. Result Limiting**
- Use `-l` to list files only (faster, less context usage)
- Use `head -N` to limit results
- Example: `rg "pattern" -l | head -5` - first 5 matching files

**4. Context Lines**
- `-A N` shows N lines after match
- `-B N` shows N lines before match
- `-C N` shows N lines before and after
- Example: `rg "error handling" -A5` - shows 5 lines after each match

## Pattern Categories

### 1. Concept Discovery

Find conceptual documentation:

```bash
# Getting started guides
rg "getting started\\|quickstart\\|introduction" references/guides/ -i -l | head -5

# Best practices
rg "best practice\\|recommended\\|should\\|avoid" references/guides/ -i -l

# Common pitfalls
rg "gotcha\\|pitfall\\|common mistake\\|avoid" references/guides/ -i -l

# Architecture concepts
rg "architecture\\|design pattern\\|structure" references/guides/ -i -l
```

**Pattern notes:**
- Use `\\|` for OR logic (finds "this" OR "that")
- `-i` for case-insensitive matching
- `-l` to list files only (context-efficient)
- `head -5` limits to first 5 results

### 2. Function/API Discovery

Find specific functions or APIs:

```bash
# Exact function name
rg "functionName" references/api-reference/

# Function definition patterns (language-specific)
rg "function\\s+\\w+" references/samples/     # JavaScript/TypeScript
rg "def\\s+\\w+" references/samples/          # Python
rg "public\\s+\\w+\\s+\\w+\\(" references/samples/  # Java

# Method calls
rg "\\.methodName\\(" references/samples/

# Class definitions
rg "class ClassName" references/api-reference/
```

**Pattern notes:**
- `\\s+` matches whitespace (one or more)
- `\\w+` matches word characters (alphanumeric + underscore)
- `\\.` escapes the period for method calls
- `\\(` escapes parentheses for function signatures

### 3. Code Example Discovery

Find working code samples:

```bash
# Import/require statements (language-specific)
rg "^import\\s+" references/samples/ -l | head -10         # ES6 imports
rg "^const.*=.*require" references/samples/ -l | head -10  # CommonJS
rg "^from.*import" references/samples/ -l | head -10       # Python

# Specific pattern examples
rg "async function" references/samples/ -A10    # Async patterns
rg "try.*catch" references/samples/ -A5         # Error handling
rg "for.*of" references/samples/ -A3            # Iteration patterns

# Framework-specific patterns
rg "Effect\\.gen" references/samples/ -A15      # Effect.ts patterns
rg "React\\.useState" references/samples/ -A8   # React hooks
```

**Pattern notes:**
- `^` anchors to start of line
- `-A N` shows N lines of context (actual code)
- Use specific enough patterns to find relevant examples

### 4. Error Message Discovery

Find error handling and troubleshooting:

```bash
# Error messages
rg "Error:\\|Exception:\\|Failed to" references/guides/ -i -A3

# Troubleshooting sections
rg "troubleshoot\\|debug\\|diagnose" references/guides/ -i -l

# Common errors
rg "ECONNREFUSED\\|404\\|500\\|timeout" references/guides/ -A5

# Error codes
rg "E[0-9]{4}" references/guides/ -A3   # e.g., E1234
```

**Pattern notes:**
- `-A3` shows error context (usually the solution)
- `[0-9]{4}` matches exactly 4 digits
- `-i` catches different error format variations

### 5. Configuration Discovery

Find configuration examples:

```bash
# Config files
rg "config\\|configuration\\|settings" references/guides/ -i -l

# Environment variables
rg "[A-Z_]+=" references/samples/ -l    # e.g., DATABASE_URL=

# JSON config patterns
rg '\\{[\\s\\S]*?"[a-z]+":' references/samples/ -A10

# YAML config patterns
rg "^[a-z]+:" references/samples/ -l
```

**Pattern notes:**
- `[A-Z_]+` matches uppercase with underscores (env vars)
- `[\\s\\S]*?` matches any character including newlines (non-greedy)
- `^[a-z]+:` matches YAML keys at start of line

## Advanced Techniques

### Regex Alternation (OR Logic)

Find multiple related terms:

```bash
# Multiple function names
rg "connect\\|disconnect\\|reconnect" references/api-reference/

# Multiple concepts
rg "cache\\|caching\\|cached" references/guides/ -i -l

# Multiple error types
rg "timeout\\|ETIMEDOUT\\|deadline exceeded" references/guides/ -i
```

### Negative Filtering

Exclude unwanted results:

```bash
# Find all .md files except test files
rg "pattern" references/ -l | grep -v "test"

# Find function definitions but not in comments
rg "^function" references/samples/ | grep -v "^//"

# Find imports but not from test utilities
rg "^import" references/samples/ | grep -v "from.*test"
```

### File Type Filtering

Search specific file types only:

```bash
# Search only TypeScript files
rg "pattern" -t ts references/samples/

# Search only markdown files
rg "pattern" -t md references/guides/

# Search multiple file types
rg "pattern" -t ts -t js references/samples/
```

**Common type flags:**
- `-t ts` - TypeScript
- `-t js` - JavaScript
- `-t py` - Python
- `-t md` - Markdown
- `-t json` - JSON

### Path-Based Filtering

Search specific subdirectories:

```bash
# Only in guides subdirectory
rg "pattern" references/guides/

# Only in api-reference
rg "pattern" references/api-reference/

# Specific category
rg "pattern" references/guides/getting-started/
```

## Performance Optimization

### 1. Use File Listing First

Don't load content if you just need filenames:

```bash
# ✅ FAST - list files only
rg "pattern" references/ -l | head -10

# ❌ SLOW - loads all content
rg "pattern" references/ | head -10
```

### 2. Limit Result Count

Always limit large result sets:

```bash
# ✅ CONTROLLED - stops after 10 files
rg "common pattern" references/ -l | head -10

# ❌ UNCONTROLLED - could return thousands
rg "common pattern" references/ -l
```

### 3. Be Specific with Paths

Search narrower paths when possible:

```bash
# ✅ TARGETED - searches 50 files
rg "pattern" references/guides/getting-started/

# ❌ BROAD - searches 500 files
rg "pattern" references/
```

### 4. Use Context Lines Sparingly

Only request context when needed:

```bash
# ✅ EFFICIENT - just find the files
rg "error handling" references/guides/ -l

# ❌ VERBOSE - loads lots of context
rg "error handling" references/guides/ -C20
```

## Common Patterns by Technology

### JavaScript/TypeScript

```bash
# Find async/await patterns
rg "async.*=>\\|async function" references/samples/ -A5

# Find Promise chains
rg "\\.then\\(\\|\\.catch\\(" references/samples/ -A3

# Find import statements
rg "^import.*from" references/samples/ -l
```

### Python

```bash
# Find class definitions
rg "^class \\w+" references/samples/ -A10

# Find decorators
rg "^@\\w+" references/samples/ -A2

# Find imports
rg "^from.*import\\|^import" references/samples/ -l
```

### SQL/Database

```bash
# Find SELECT queries
rg "SELECT.*FROM" references/samples/ -A5

# Find transaction patterns
rg "BEGIN TRANSACTION\\|COMMIT\\|ROLLBACK" references/samples/ -A3

# Find index hints
rg "CREATE INDEX\\|DROP INDEX" references/guides/ -A5
```

### Effect.ts Patterns

```bash
# Find Effect.gen usage
rg "Effect\\.gen\\(function\\*" references/samples/ -A15

# Find Layer definitions
rg "Layer\\.\\w+\\(" references/samples/ -A10

# Find Service tags
rg "Context\\.Tag\\(" references/samples/ -A5
```

## Examples from Spanner Documentation

### Finding GQL Syntax

```bash
# MATCH patterns
rg "MATCH.*WHERE.*RETURN" references/guides/ -A5

# JSON functions
rg "JSON_VALUE\\|SAFE_TO_JSON" references/guides/ -A3

# Graph traversal
rg "MATCH.*->.*RETURN" references/samples/ -A10
```

### Finding SQL Functions

```bash
# Aggregate functions
rg "COUNT\\|SUM\\|AVG\\|MIN\\|MAX" references/api-reference/ -A3

# String functions
rg "CONCAT\\|SUBSTRING\\|REPLACE" references/api-reference/ -A3

# Date functions
rg "TIMESTAMP\\|DATE\\|DATETIME" references/api-reference/ -A3
```

### Finding Best Practices

```bash
# Schema design
rg "primary key\\|index\\|hotspot" references/guides/ -i -l

# Query optimization
rg "query plan\\|optimizer\\|performance" references/guides/ -i -l

# Transaction patterns
rg "read-write\\|read-only\\|snapshot" references/guides/ -i -l
```

## Pattern Testing Workflow

**1. Start broad, then narrow:**

```bash
# Step 1: Find relevant files
rg "transaction" references/ -i -l | head -10

# Step 2: Add specificity
rg "transaction isolation" references/guides/ -i -l

# Step 3: Get context
rg "transaction isolation" references/guides/ -i -A5
```

**2. Verify results:**

```bash
# Count matches
rg "pattern" references/ -c

# Preview first match
rg "pattern" references/ -l | head -1 | xargs cat

# Check if pattern is too broad
rg "pattern" references/ | wc -l
```

**3. Document winning patterns:**

Add effective patterns to your docs skill's SKILL.md for reuse.

## Anti-Patterns to Avoid

### ❌ Don't: Load entire files into context

```bash
# WRONG - loads 1000s of lines
cat references/guides/*.md | grep "pattern"
```

### ❌ Don't: Use overly broad patterns

```bash
# WRONG - returns 10,000+ matches
rg "the" references/
```

### ❌ Don't: Forget to limit results

```bash
# WRONG - could hang or OOM
rg "common word" references/
```

### ❌ Don't: Ignore file extensions

```bash
# WRONG - searches binary files too
rg "pattern" references/

# RIGHT - only text files
rg "pattern" references/ -t md -t ts
```

### ✅ Do: Combine patterns for precision

```bash
# GOOD - specific and targeted
rg "Effect\\.gen" references/samples/ -t ts -l | head -5
```

### ✅ Do: Use incremental refinement

```bash
# GOOD - progressively narrow search
rg "error" references/ -l | grep "handling" | head -5
```

## Summary

**Key principles for effective grep patterns:**
1. Start specific, broaden only if needed
2. Use `-i` for case-insensitive searches
3. Use `-l` for file listing (context-efficient)
4. Always limit results with `head -N`
5. Add context lines (`-A`, `-B`, `-C`) only when needed
6. Use regex OR (`\\|`) for multiple terms
7. Filter by file type (`-t`) and path
8. Test patterns before documenting them

**Remember:** The goal is discovery without context explosion. Good grep patterns help users find exactly what they need in 1-2 searches, without loading hundreds of files.
