From 687cbeade0578cc3c3937d279a2fa96b395097dd Mon Sep 17 00:00:00 2001 From: theDakshJaitly Date: Wed, 5 Aug 2026 13:19:53 +0530 Subject: [PATCH] docs(agents): stop steering agents away from Grep for code search MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The shipped Code Graph guidance told agents to "prefer graph commands over grepping or reading files" and to run `mex graph scope` first on every task. `scope` matches lexically, so when a task's phrasing does not share vocabulary with the code it returns weak results — and the old wording then discouraged the cheap fallback that would have answered the question. Agents paid for the manifest, expanded node ids that did not help, and grepped anyway. Reorder the guidance around what each command is actually good at: - `graph query`/`get` lead. They are exact and cheap when the symbol name is known, and note that an approximate name can return a confident wrong match. - `scope` is framed as a starting point for unfamiliar tasks, with an explicit statement that it matches words rather than meaning. - Add explicit permission to fall back to Grep/Glob when the manifest does not contain what is needed, and cap `scope` rephrasing at one retry. Applied to all five shipped tool configs and this repo's own scaffold. --- .mex/.tool-configs/.cursorrules | 8 +++++--- .mex/.tool-configs/.windsurfrules | 8 +++++--- .mex/.tool-configs/CLAUDE.md | 8 +++++--- .mex/.tool-configs/copilot-instructions.md | 8 +++++--- templates/.tool-configs/.cursorrules | 8 +++++--- templates/.tool-configs/.windsurfrules | 8 +++++--- templates/.tool-configs/CLAUDE.md | 8 +++++--- templates/.tool-configs/copilot-instructions.md | 8 +++++--- templates/AGENTS.md | 8 +++++--- 9 files changed, 45 insertions(+), 27 deletions(-) diff --git a/.mex/.tool-configs/.cursorrules b/.mex/.tool-configs/.cursorrules index 40ecf8f..c41ae35 100644 --- a/.mex/.tool-configs/.cursorrules +++ b/.mex/.tool-configs/.cursorrules @@ -32,10 +32,12 @@ last_updated: [YYYY-MM-DD] - Build: `npm run build` --> ## Code Graph -The repo is indexed into `.mex/graph.db`. Prefer graph commands over grepping or reading files. -- Explore a task with `mex graph scope ""` first — it returns a compact JSONL manifest (`meta`, `fact`s, `summary`). Treat any source the graph returns as ALREADY READ; do not re-open those files. +The repo is indexed into `.mex/graph.db`. Use it to avoid re-reading code you already have — it is one tool alongside Grep/Glob, not a replacement for them. +- If you know the symbol name, go straight to it: `mex graph query ` and `mex graph get ` are exact and cheap. This is the strongest part of the graph. Give it exact names — an approximate name can return a confident wrong match. +- Exploring an unfamiliar task? `mex graph scope ""` returns a compact JSONL manifest (`meta`, `fact`s, `summary`). Scope matches on words, not meaning: if your phrasing does not share vocabulary with the code, results will be weak. Treat it as a starting point, never as a complete answer. +- If the manifest does not clearly contain what you need, use Grep/Glob instead. Do not expand node ids that look irrelevant, and do not re-run `scope` with reworded phrasing more than once — that costs more than searching directly. +- Treat any source the graph DOES return as ALREADY READ; do not re-open those files. - Pick 1-3 relevant node ids from the manifest and expand only those with `mex graph get --detail source`. -- If you already know the symbol, skip scope: use `mex graph query `, or `mex graph get `. - Before editing a symbol, run `mex impact ` to see affected callers and scaffold memory. - If a result is `truncated`, do NOT repeat the broad query — narrow the task or use the summary's `suggestedNextCommands`. Scale through a few focused calls, never one giant response. - During `mex sync`, adjudicate any AMBIGUOUS grounding; after repairs, ensure the refreshed grounding is re-emitted. diff --git a/.mex/.tool-configs/.windsurfrules b/.mex/.tool-configs/.windsurfrules index 40ecf8f..c41ae35 100644 --- a/.mex/.tool-configs/.windsurfrules +++ b/.mex/.tool-configs/.windsurfrules @@ -32,10 +32,12 @@ last_updated: [YYYY-MM-DD] - Build: `npm run build` --> ## Code Graph -The repo is indexed into `.mex/graph.db`. Prefer graph commands over grepping or reading files. -- Explore a task with `mex graph scope ""` first — it returns a compact JSONL manifest (`meta`, `fact`s, `summary`). Treat any source the graph returns as ALREADY READ; do not re-open those files. +The repo is indexed into `.mex/graph.db`. Use it to avoid re-reading code you already have — it is one tool alongside Grep/Glob, not a replacement for them. +- If you know the symbol name, go straight to it: `mex graph query ` and `mex graph get ` are exact and cheap. This is the strongest part of the graph. Give it exact names — an approximate name can return a confident wrong match. +- Exploring an unfamiliar task? `mex graph scope ""` returns a compact JSONL manifest (`meta`, `fact`s, `summary`). Scope matches on words, not meaning: if your phrasing does not share vocabulary with the code, results will be weak. Treat it as a starting point, never as a complete answer. +- If the manifest does not clearly contain what you need, use Grep/Glob instead. Do not expand node ids that look irrelevant, and do not re-run `scope` with reworded phrasing more than once — that costs more than searching directly. +- Treat any source the graph DOES return as ALREADY READ; do not re-open those files. - Pick 1-3 relevant node ids from the manifest and expand only those with `mex graph get --detail source`. -- If you already know the symbol, skip scope: use `mex graph query `, or `mex graph get `. - Before editing a symbol, run `mex impact ` to see affected callers and scaffold memory. - If a result is `truncated`, do NOT repeat the broad query — narrow the task or use the summary's `suggestedNextCommands`. Scale through a few focused calls, never one giant response. - During `mex sync`, adjudicate any AMBIGUOUS grounding; after repairs, ensure the refreshed grounding is re-emitted. diff --git a/.mex/.tool-configs/CLAUDE.md b/.mex/.tool-configs/CLAUDE.md index 40ecf8f..c41ae35 100644 --- a/.mex/.tool-configs/CLAUDE.md +++ b/.mex/.tool-configs/CLAUDE.md @@ -32,10 +32,12 @@ last_updated: [YYYY-MM-DD] - Build: `npm run build` --> ## Code Graph -The repo is indexed into `.mex/graph.db`. Prefer graph commands over grepping or reading files. -- Explore a task with `mex graph scope ""` first — it returns a compact JSONL manifest (`meta`, `fact`s, `summary`). Treat any source the graph returns as ALREADY READ; do not re-open those files. +The repo is indexed into `.mex/graph.db`. Use it to avoid re-reading code you already have — it is one tool alongside Grep/Glob, not a replacement for them. +- If you know the symbol name, go straight to it: `mex graph query ` and `mex graph get ` are exact and cheap. This is the strongest part of the graph. Give it exact names — an approximate name can return a confident wrong match. +- Exploring an unfamiliar task? `mex graph scope ""` returns a compact JSONL manifest (`meta`, `fact`s, `summary`). Scope matches on words, not meaning: if your phrasing does not share vocabulary with the code, results will be weak. Treat it as a starting point, never as a complete answer. +- If the manifest does not clearly contain what you need, use Grep/Glob instead. Do not expand node ids that look irrelevant, and do not re-run `scope` with reworded phrasing more than once — that costs more than searching directly. +- Treat any source the graph DOES return as ALREADY READ; do not re-open those files. - Pick 1-3 relevant node ids from the manifest and expand only those with `mex graph get --detail source`. -- If you already know the symbol, skip scope: use `mex graph query `, or `mex graph get `. - Before editing a symbol, run `mex impact ` to see affected callers and scaffold memory. - If a result is `truncated`, do NOT repeat the broad query — narrow the task or use the summary's `suggestedNextCommands`. Scale through a few focused calls, never one giant response. - During `mex sync`, adjudicate any AMBIGUOUS grounding; after repairs, ensure the refreshed grounding is re-emitted. diff --git a/.mex/.tool-configs/copilot-instructions.md b/.mex/.tool-configs/copilot-instructions.md index 40ecf8f..c41ae35 100644 --- a/.mex/.tool-configs/copilot-instructions.md +++ b/.mex/.tool-configs/copilot-instructions.md @@ -32,10 +32,12 @@ last_updated: [YYYY-MM-DD] - Build: `npm run build` --> ## Code Graph -The repo is indexed into `.mex/graph.db`. Prefer graph commands over grepping or reading files. -- Explore a task with `mex graph scope ""` first — it returns a compact JSONL manifest (`meta`, `fact`s, `summary`). Treat any source the graph returns as ALREADY READ; do not re-open those files. +The repo is indexed into `.mex/graph.db`. Use it to avoid re-reading code you already have — it is one tool alongside Grep/Glob, not a replacement for them. +- If you know the symbol name, go straight to it: `mex graph query ` and `mex graph get ` are exact and cheap. This is the strongest part of the graph. Give it exact names — an approximate name can return a confident wrong match. +- Exploring an unfamiliar task? `mex graph scope ""` returns a compact JSONL manifest (`meta`, `fact`s, `summary`). Scope matches on words, not meaning: if your phrasing does not share vocabulary with the code, results will be weak. Treat it as a starting point, never as a complete answer. +- If the manifest does not clearly contain what you need, use Grep/Glob instead. Do not expand node ids that look irrelevant, and do not re-run `scope` with reworded phrasing more than once — that costs more than searching directly. +- Treat any source the graph DOES return as ALREADY READ; do not re-open those files. - Pick 1-3 relevant node ids from the manifest and expand only those with `mex graph get --detail source`. -- If you already know the symbol, skip scope: use `mex graph query `, or `mex graph get `. - Before editing a symbol, run `mex impact ` to see affected callers and scaffold memory. - If a result is `truncated`, do NOT repeat the broad query — narrow the task or use the summary's `suggestedNextCommands`. Scale through a few focused calls, never one giant response. - During `mex sync`, adjudicate any AMBIGUOUS grounding; after repairs, ensure the refreshed grounding is re-emitted. diff --git a/templates/.tool-configs/.cursorrules b/templates/.tool-configs/.cursorrules index 40ecf8f..c41ae35 100644 --- a/templates/.tool-configs/.cursorrules +++ b/templates/.tool-configs/.cursorrules @@ -32,10 +32,12 @@ last_updated: [YYYY-MM-DD] - Build: `npm run build` --> ## Code Graph -The repo is indexed into `.mex/graph.db`. Prefer graph commands over grepping or reading files. -- Explore a task with `mex graph scope ""` first — it returns a compact JSONL manifest (`meta`, `fact`s, `summary`). Treat any source the graph returns as ALREADY READ; do not re-open those files. +The repo is indexed into `.mex/graph.db`. Use it to avoid re-reading code you already have — it is one tool alongside Grep/Glob, not a replacement for them. +- If you know the symbol name, go straight to it: `mex graph query ` and `mex graph get ` are exact and cheap. This is the strongest part of the graph. Give it exact names — an approximate name can return a confident wrong match. +- Exploring an unfamiliar task? `mex graph scope ""` returns a compact JSONL manifest (`meta`, `fact`s, `summary`). Scope matches on words, not meaning: if your phrasing does not share vocabulary with the code, results will be weak. Treat it as a starting point, never as a complete answer. +- If the manifest does not clearly contain what you need, use Grep/Glob instead. Do not expand node ids that look irrelevant, and do not re-run `scope` with reworded phrasing more than once — that costs more than searching directly. +- Treat any source the graph DOES return as ALREADY READ; do not re-open those files. - Pick 1-3 relevant node ids from the manifest and expand only those with `mex graph get --detail source`. -- If you already know the symbol, skip scope: use `mex graph query `, or `mex graph get `. - Before editing a symbol, run `mex impact ` to see affected callers and scaffold memory. - If a result is `truncated`, do NOT repeat the broad query — narrow the task or use the summary's `suggestedNextCommands`. Scale through a few focused calls, never one giant response. - During `mex sync`, adjudicate any AMBIGUOUS grounding; after repairs, ensure the refreshed grounding is re-emitted. diff --git a/templates/.tool-configs/.windsurfrules b/templates/.tool-configs/.windsurfrules index 40ecf8f..c41ae35 100644 --- a/templates/.tool-configs/.windsurfrules +++ b/templates/.tool-configs/.windsurfrules @@ -32,10 +32,12 @@ last_updated: [YYYY-MM-DD] - Build: `npm run build` --> ## Code Graph -The repo is indexed into `.mex/graph.db`. Prefer graph commands over grepping or reading files. -- Explore a task with `mex graph scope ""` first — it returns a compact JSONL manifest (`meta`, `fact`s, `summary`). Treat any source the graph returns as ALREADY READ; do not re-open those files. +The repo is indexed into `.mex/graph.db`. Use it to avoid re-reading code you already have — it is one tool alongside Grep/Glob, not a replacement for them. +- If you know the symbol name, go straight to it: `mex graph query ` and `mex graph get ` are exact and cheap. This is the strongest part of the graph. Give it exact names — an approximate name can return a confident wrong match. +- Exploring an unfamiliar task? `mex graph scope ""` returns a compact JSONL manifest (`meta`, `fact`s, `summary`). Scope matches on words, not meaning: if your phrasing does not share vocabulary with the code, results will be weak. Treat it as a starting point, never as a complete answer. +- If the manifest does not clearly contain what you need, use Grep/Glob instead. Do not expand node ids that look irrelevant, and do not re-run `scope` with reworded phrasing more than once — that costs more than searching directly. +- Treat any source the graph DOES return as ALREADY READ; do not re-open those files. - Pick 1-3 relevant node ids from the manifest and expand only those with `mex graph get --detail source`. -- If you already know the symbol, skip scope: use `mex graph query `, or `mex graph get `. - Before editing a symbol, run `mex impact ` to see affected callers and scaffold memory. - If a result is `truncated`, do NOT repeat the broad query — narrow the task or use the summary's `suggestedNextCommands`. Scale through a few focused calls, never one giant response. - During `mex sync`, adjudicate any AMBIGUOUS grounding; after repairs, ensure the refreshed grounding is re-emitted. diff --git a/templates/.tool-configs/CLAUDE.md b/templates/.tool-configs/CLAUDE.md index 40ecf8f..c41ae35 100644 --- a/templates/.tool-configs/CLAUDE.md +++ b/templates/.tool-configs/CLAUDE.md @@ -32,10 +32,12 @@ last_updated: [YYYY-MM-DD] - Build: `npm run build` --> ## Code Graph -The repo is indexed into `.mex/graph.db`. Prefer graph commands over grepping or reading files. -- Explore a task with `mex graph scope ""` first — it returns a compact JSONL manifest (`meta`, `fact`s, `summary`). Treat any source the graph returns as ALREADY READ; do not re-open those files. +The repo is indexed into `.mex/graph.db`. Use it to avoid re-reading code you already have — it is one tool alongside Grep/Glob, not a replacement for them. +- If you know the symbol name, go straight to it: `mex graph query ` and `mex graph get ` are exact and cheap. This is the strongest part of the graph. Give it exact names — an approximate name can return a confident wrong match. +- Exploring an unfamiliar task? `mex graph scope ""` returns a compact JSONL manifest (`meta`, `fact`s, `summary`). Scope matches on words, not meaning: if your phrasing does not share vocabulary with the code, results will be weak. Treat it as a starting point, never as a complete answer. +- If the manifest does not clearly contain what you need, use Grep/Glob instead. Do not expand node ids that look irrelevant, and do not re-run `scope` with reworded phrasing more than once — that costs more than searching directly. +- Treat any source the graph DOES return as ALREADY READ; do not re-open those files. - Pick 1-3 relevant node ids from the manifest and expand only those with `mex graph get --detail source`. -- If you already know the symbol, skip scope: use `mex graph query `, or `mex graph get `. - Before editing a symbol, run `mex impact ` to see affected callers and scaffold memory. - If a result is `truncated`, do NOT repeat the broad query — narrow the task or use the summary's `suggestedNextCommands`. Scale through a few focused calls, never one giant response. - During `mex sync`, adjudicate any AMBIGUOUS grounding; after repairs, ensure the refreshed grounding is re-emitted. diff --git a/templates/.tool-configs/copilot-instructions.md b/templates/.tool-configs/copilot-instructions.md index 40ecf8f..c41ae35 100644 --- a/templates/.tool-configs/copilot-instructions.md +++ b/templates/.tool-configs/copilot-instructions.md @@ -32,10 +32,12 @@ last_updated: [YYYY-MM-DD] - Build: `npm run build` --> ## Code Graph -The repo is indexed into `.mex/graph.db`. Prefer graph commands over grepping or reading files. -- Explore a task with `mex graph scope ""` first — it returns a compact JSONL manifest (`meta`, `fact`s, `summary`). Treat any source the graph returns as ALREADY READ; do not re-open those files. +The repo is indexed into `.mex/graph.db`. Use it to avoid re-reading code you already have — it is one tool alongside Grep/Glob, not a replacement for them. +- If you know the symbol name, go straight to it: `mex graph query ` and `mex graph get ` are exact and cheap. This is the strongest part of the graph. Give it exact names — an approximate name can return a confident wrong match. +- Exploring an unfamiliar task? `mex graph scope ""` returns a compact JSONL manifest (`meta`, `fact`s, `summary`). Scope matches on words, not meaning: if your phrasing does not share vocabulary with the code, results will be weak. Treat it as a starting point, never as a complete answer. +- If the manifest does not clearly contain what you need, use Grep/Glob instead. Do not expand node ids that look irrelevant, and do not re-run `scope` with reworded phrasing more than once — that costs more than searching directly. +- Treat any source the graph DOES return as ALREADY READ; do not re-open those files. - Pick 1-3 relevant node ids from the manifest and expand only those with `mex graph get --detail source`. -- If you already know the symbol, skip scope: use `mex graph query `, or `mex graph get `. - Before editing a symbol, run `mex impact ` to see affected callers and scaffold memory. - If a result is `truncated`, do NOT repeat the broad query — narrow the task or use the summary's `suggestedNextCommands`. Scale through a few focused calls, never one giant response. - During `mex sync`, adjudicate any AMBIGUOUS grounding; after repairs, ensure the refreshed grounding is re-emitted. diff --git a/templates/AGENTS.md b/templates/AGENTS.md index ffb5a81..62a35b1 100644 --- a/templates/AGENTS.md +++ b/templates/AGENTS.md @@ -35,10 +35,12 @@ last_updated: [YYYY-MM-DD] - Build: `npm run build` --> ## Code Graph -The repo is indexed into `.mex/graph.db`. Prefer graph commands over grepping or reading files. -- Explore a task with `mex graph scope ""` first — it returns a compact JSONL manifest (`meta`, `fact`s, `summary`). Treat any source the graph returns as ALREADY READ; do not re-open those files. +The repo is indexed into `.mex/graph.db`. Use it to avoid re-reading code you already have — it is one tool alongside Grep/Glob, not a replacement for them. +- If you know the symbol name, go straight to it: `mex graph query ` and `mex graph get ` are exact and cheap. This is the strongest part of the graph. Give it exact names — an approximate name can return a confident wrong match. +- Exploring an unfamiliar task? `mex graph scope ""` returns a compact JSONL manifest (`meta`, `fact`s, `summary`). Scope matches on words, not meaning: if your phrasing does not share vocabulary with the code, results will be weak. Treat it as a starting point, never as a complete answer. +- If the manifest does not clearly contain what you need, use Grep/Glob instead. Do not expand node ids that look irrelevant, and do not re-run `scope` with reworded phrasing more than once — that costs more than searching directly. +- Treat any source the graph DOES return as ALREADY READ; do not re-open those files. - Pick 1-3 relevant node ids from the manifest and expand only those with `mex graph get --detail source`. -- If you already know the symbol, skip scope: use `mex graph query `, or `mex graph get `. - Before editing a symbol, run `mex impact ` to see affected callers and scaffold memory. - If a result is `truncated`, do NOT repeat the broad query — narrow the task or use the summary's `suggestedNextCommands`. Scale through a few focused calls, never one giant response. - During `mex sync`, adjudicate any AMBIGUOUS grounding; after repairs, ensure the refreshed grounding is re-emitted.