unified-search-discover

Purpose

Provide progressive search and discovery workflows with structured refinement patterns that assess scope before execution. Enable safe, efficient file discovery, content searching, and code refactoring through COUNT → PREVIEW → EXECUTE methodology.

Quick Decision Guide

File Discovery: fd vs find

Use fd when:

• Need gitignore-aware file discovery (default preference)
• Performance is critical (5-10x faster than find)
• Working with modern development environments

Use find when:

• Need to discover hidden/ignored files
• System lacks fd installation
• Require POSIX compatibility

Text Search: ast-grep vs rg vs grep

Use ast-grep when:

• Structural code analysis required
• Refactoring with language awareness
• Need AST pattern matching

Use rg when:

• Fast text search across many files
• Regex pattern matching needed
• Performance-critical searches

Use grep when:

• Maximum compatibility required
• Minimal system environments
• Simple text patterns

Progressive Refinement Pattern

ALWAYS follow this 3-step pattern for search operations:

Step 1: COUNT - Assess Scope

Count results before displaying to prevent overwhelming output:

# File discovery scope
fd --type ts | wc -l
find . -name "*.ts" | wc -l

# Text search scope
rg "function" --count --type ts
grep -r "function" --include="*.ts" | wc -l

# Structural analysis scope
ast-grep --pattern 'function $NAME()' --dry-run --json | jq '.matches | length'

Step 2: PREVIEW - Validate with Limited Results

Show representative samples to confirm pattern accuracy:

# File discovery preview
fd --type ts | head -10
find . -name "*.ts" | head -10

# Text search preview with context
rg "function" --type ts -A 2 -B 2 | head -20

# Structural analysis preview
ast-grep --pattern 'function $NAME()' --dry-run -A 1 -B 1

Step 3: EXECUTE - Apply with Full Awareness

Execute full search only after scope validation:

# Full file discovery
fd --type ts -x rg "pattern"

# Full text search
rg "function" --type ts -A 2 -B 2

# Full structural analysis
ast-grep --pattern 'function $NAME()' -A 2 -B 2

Tool-Specific Guidelines

File Discovery with fd/find

Preferred: fd (gitignore-aware, fast)

# COUNT: Assess TypeScript file scope
fd --type ts | wc -l

# PREVIEW: Show sample files
fd --type ts | head -10

# EXECUTE: Full discovery with execution
fd --type ts -x rg "import.*React"

# Advanced patterns
fd --type ts --exclude "node_modules"  # Additional exclusions
fd --type ts --hidden                  # Include hidden files

Fallback: find (maximum compatibility)

# COUNT: Assess file scope
find . -name "*.ts" -not -path "*/node_modules/*" | wc -l

# PREVIEW: Sample files
find . -name "*.ts" -not -path "*/node_modules/*" | head -10

# EXECUTE: Full discovery
find . -name "*.ts" -not -path "*/node_modules/*" -exec grep "pattern" {} +

Text Search with rg/grep

Preferred: rg (fast, modern)

# COUNT: Scope assessment
rg "console\.log" --count --type ts

# PREVIEW: Context samples
rg "console\.log" --type ts -A 1 -B 1 | head -20

# EXECUTE: Full search with context
rg "console\.log" --type ts -A 2 -B 2 --line-number

# Advanced patterns
rg "function" --type ts --word-boundary    # Whole words only
rg "import.*React" --type ts --context 3  # 3 lines context

Fallback: grep (maximum compatibility)

# COUNT: Scope assessment
grep -r "console\.log" --include="*.ts" | wc -l

# PREVIEW: Context samples
grep -r -n -A 1 -B 1 "console\.log" --include="*.ts" | head -20

# EXECUTE: Full search
grep -r -n -A 2 -B 2 "console\.log" --include="*.ts"

Structural Analysis with ast-grep

Language-aware pattern matching for refactoring:

# COUNT: Assess refactoring impact
ast-grep --pattern 'import $NAME from "./old-path"' --dry-run --json | jq '.matches | length'

# PREVIEW: Show sample changes
ast-grep --pattern 'import $NAME from "./old-path"' --dry-run -A 1 -B 1

# EXECUTE: Safe refactoring with backup
cp -r src/ src-backup-$(date +%s)/
ast-grep --pattern 'import $NAME from "./old-path"' --rewrite 'import $NAME from "./new-path"'

# Common refactoring patterns
ast-grep --pattern 'console.log($MSG)' --rewrite ''  # Remove console logs
ast-grep --pattern 'var $NAME = $VALUE' --rewrite 'let $NAME = $VALUE'  # var to let

Refactoring Workflows

Discovery → Search → Analyze → Refactor Pipeline

Phase 1: Discovery

# Find all relevant files
fd --type ts src/ | wc -l  # COUNT
fd --type ts src/ | head -10  # PREVIEW

Phase 2: Search

# Locate patterns in discovered files
fd --type ts src/ -x rg "console\.log" --count-matches  # COUNT
fd --type ts src/ -x rg "console\.log" -A 1 -B 1 | head -20  # PREVIEW

Phase 3: Analysis

# Structural verification
ast-grep --pattern 'console.log($MSG)' --dry-run --json | jq '.matches | length'  # COUNT
ast-grep --pattern 'console.log($MSG)' --dry-run -A 1 -B 1  # PREVIEW

Phase 4: Refactor

# Safe execution with backup
cp -r src/ src-backup-$(date +%s)/  # Backup
ast-grep --pattern 'console.log($MSG)' --rewrite ''  # EXECUTE

Safety Protocols for Refactoring

Before any refactoring:

1. COUNT - Always assess impact scope first
2. PREVIEW - Review sample changes before execution
3. BACKUP - Create timestamped backups
4. DRY-RUN - Use --dry-run with ast-grep for verification
5. TEST - Apply changes to small subset first

After refactoring:

1. VERIFY - Confirm changes applied correctly
2. TEST - Run tests to ensure functionality preserved
3. CLEANUP - Remove backups after verification

Performance Optimization

Large Codebase Strategies

# Parallel execution with xargs
fd --type ts | xargs -P 4 -I {} rg "pattern" {}

# Memory-efficient searches
rg --max-filesize 1M "pattern"  # Skip large files
find . -name "*.log" -prune -o -name "*.ts" -print  # Exclude logs

# Incremental searches
rg --type ts "pattern" | head -100  # Limit initial results

Platform Considerations

• macOS: Use gnu-sed, gnu-find for consistency
• Linux: Standard GNU tools typically available
• Windows: Use WSL or Git Bash for Unix tooling

Integration Points

Environment Validation

Always couple with skill:environment-validation to check tool availability:

# Tool availability check
fd --version && rg --version && ast-grep --version

Language-Specific Integration

• TypeScript: --type ts, .ts/.tsx patterns
• Python: --type py, .py patterns
• JavaScript: --type js, .js/.jsx patterns
• Go: --type go, .go patterns

Agent Workflow Integration

• Discovery Phase: File enumeration with fd/find
• Analysis Phase: Content searching with rg/grep
• Refactoring Phase: Structural changes with ast-grep
• Verification Phase: Pattern validation across all tools