---
name: grepai-first
description: Wiki first for known-entity facts; then search with GrepAI/Grep before opening any file for code/discovery; Read only when full content is needed
applies-to: all
---

# Context Lookup — search before reading (wiki first for known entities)

Two-part rule:

1. **Known-entity facts** (a specific client/project/system — its IPs, creds paths, architecture):
   check the **wiki** (`wiki/`) FIRST. It is the synthesized truth layer and is already distilled —
   cheaper than re-deriving from raw logs/code.
2. **Everything else** (code, discovery, un-compiled detail): search with **GrepAI or Grep before
   opening any file**. Only open a file when you need its full content for editing or line-by-line
   review.

GrepAI's irreplaceable value is **code** (call-graph tracing over the Rust+TS corpus the wiki can't
see). Do NOT GrepAI something the wiki already answers — that's redundant overlap.

## Lookup table

| Goal | Tool |
|------|------|
| Find where a function is defined | `grepai_search` or `Grep` |
| Understand how a feature works | `grepai_search` |
| Find all callers of a function | `grepai_trace_callers` |
| Find what a function calls | `grepai_trace_callees` |
| Full file content needed (edit, review) | `Read` |
| Recent changes to a file | `git log`, then `Read` specific file |
| "What did we do with client/system X?" | **wiki article first**, then `grepai_search` over session logs for detail below the wiki's summary |
| "How is Y configured?" (known entity) | **wiki first**, then `grepai_search` / the specific file |
| "How is Y configured?" (code/unknown) | `grepai_search` before opening any file |

## Token cost rationale

Reading a 500-line file to find one function costs approximately 3,000 tokens. A targeted GrepAI or Grep search costs approximately 100 tokens and returns only the relevant lines. At scale, reading files for context without searching first wastes context window and increases latency.

Never open a large file to scan for context. Search first; read only if the search result is insufficient or if you need to edit the file.

## GrepAI specifics

- CLI: `D:/claudetools/grepai.exe search "query" --json -c -n 5`
- MCP tools: `grepai_search` (primary), `grepai_trace_callers`, `grepai_trace_callees`
- The GrepAI index covers session logs, skill files, and project docs with boosted relevance for `.claude/` content
- The watcher (scheduled task "GrepAI Watcher - claudetools") keeps the index current automatically

## Common search queries

```bash
# Find where a setting is configured
grepai_search "vault_path"

# Understand how the Syncro skill handles billing
grepai_search "timer_entry charge_timer"

# Find what we did with a specific client or feature
grepai_search "Cascades DMARC"

# Locate a function definition
Grep --pattern "fn collect_temps" --type rust
```
