Selective Grep Filtering

Surgical Grep Filtering & Glob Targeting Protocol

Overview

When searching a repository for a specific method or constant ("handlePaymentCallback"), naive agents execute broad, unconstrained searches across the entire workspace directory.

Unfiltered searches return hundreds of false-positive matches:

1. Test Snapshots & Fixtures: Matches in 50 Jest/Vitest snapshots that aren't part of production logic.
2. Minified Bundles & Source Maps: Matches in .map or dist/ files that dump unreadable minified code into context.
3. Markdown Documentation: Matches in changelogs, READMEs, and tutorials.

The Surgical Grep Filtering Protocol constrains the search space using strict file extension globs, target directory scopes, and exact literal matching (IsRegex: false), returning strictly the 1 to 3 production source matches.

Unconstrained Search vs. Surgical Glob Filtering

┌─────────────────────────────────────────────────────────────┐
│                 Search Precision Comparison                 │
│                                                             │
│  Unconstrained Workspace Search (140 Matches / 6,200 Toks): │
│  • 80 matches in `tests/__snapshots__/`                     │
│  • 45 matches in `dist/bundle.js`                           │
│  • 12 matches in `docs/architecture.md`                     │
│  • 3 matches in `src/services/`                             │
│  ↳ 6,200 tokens billed, agent gets lost in snapshots        │
│                                                             │
│  Surgical Glob Filtering (3 Matches / 85 Tokens - 98.6% Cut):│
│  • Includes: `["src/**/*.ts", "!**/*.spec.ts"]`             │
│  • Match: `src/services/billing.ts:42`                      │
│  • Match: `src/routes/payment.ts:18`                        │
│  ↳ 85 clean tokens, 100% production source hits             │
└─────────────────────────────────────────────────────────────┘

The 3 Pillars of Surgical Search

┌───────────────────────────────────────────────────────────────────────────┐
│ 1. TARGET DIRECTORY ONLY: Confine `SearchPath` to `src/` or `pkg/`        │
│ 2. EXCLUDE TESTS & SPECS: Add `!**/*.test.ts`, `!**/*.spec.py`            │
│ 3. LITERAL MATCHING BY DEFAULT: Set `IsRegex: false` (Prevents regex bugs)│
└───────────────────────────────────────────────────────────────────────────┘

Production Tool Invocation Standards

When invoking grep_search in Antigravity IDE / Claude Code:

{
  "Query": "handlePaymentCallback",
  "SearchPath": "c:/Users/ASUS/Documents/Newfolder/Antigravity/Major AI Skills/src",
  "CaseInsensitive": false,
  "IsRegex": false,
  "MatchPerLine": true,
  "Includes": [
    "**/*.ts",
    "!**/*.test.ts",
    "!**/*.spec.ts",
    "!**/__mocks__/**"
  ],
  "toolAction": "Searching for payment callback in production TS sources",
  "toolSummary": "Surgical Grep Search"
}

CLI Ripgrep Equivalent Commands

When running ripgrep directly via terminal:

# Surgical search: TypeScript production files only (excluding tests and mocks)
rg "handlePaymentCallback" src/ -t ts --glob '!**/*.test.ts' --glob '!**/__mocks__/**'

# Search Python source files only
rg "def authenticate_user" src/ -t py --glob '!tests/**'

Benchmark Comparison

Searching for a common error handler across a 1,500-file repository:

Agent Operational Directive

MANDATORY: Agents executing code searches must scope SearchPath to active source directories (src/, app/, pkg/) and populate the Includes array with specific filetype globs and test exclusion filters (!**/*.test.*).