memtrace-skills 1.2.7 → 1.2.8

package/plugins/memtrace-skills/skills/memtrace-first/SKILL.md

@@ -1,41 +1,88 @@
 ---
 name: memtrace-first
-description: "Route code discovery, debugging, flow tracing, how-code-works questions, and pre-edit rationale checks in indexed source-code repos to Memtrace graph plus Cortex decision tools. Use first before searching/reading code, and before editing, refactoring, deleting, or re-picking an approach that may have a recorded decision, ban, convention, or contract. Do not use Grep, Glob, rg, find, or manual file browsing for code discovery when Memtrace is indexed. Zero results are not permission to grep; diagnose/reindex with Memtrace. A `repo_not_in_store` refusal means a different store holds the repository: route to that store, never grep and never re-index here."
+description: "Route code discovery, debugging, flow tracing, how-code-works questions, and pre-edit rationale checks in indexed source-code repos to Memtrace graph plus Cortex decision tools. Use first before searching/reading code, and before editing, refactoring, deleting, or re-picking an approach that may have a recorded decision, ban, convention, or contract. Do not use Grep, Glob, rg, find, or manual file browsing for code discovery when Memtrace is indexed. Zero results are not permission to grep: diagnose the miss first, then allow one targeted reformulation and bounded source verification or fallback, and reindex only on evidence of stale or incomplete coverage — never in a loop. A `repo_not_in_store` refusal means a different store holds the repository: route to that store, never grep and never re-index here."
 ---
-
 # Memtrace First
 
-## The Iron Law
-
-```
-IF THE REPO IS INDEXED IN MEMTRACE → USE MEMTRACE TOOLS FIRST.
-After a search hit, route to GRAPH tools (get_symbol_context, get_impact,
-analyze_relationships) — that's what Memtrace uniquely provides. Read source
-ONLY when you're about to edit or quote, and read only the bounded span
-returned by Memtrace (start_line .. end_line + small context). Do not
-Grep/Glob/Find to "locate" anything already in the graph, and do not read
-the whole file when Memtrace has given you exact lines.
-
-BEFORE you edit/refactor/delete existing code or choose/re-pick a pattern,
-call Cortex decision memory: recall_decision for the symbol/subsystem/approach,
-and use provenance/contracts when a symbol_id is available. Use Memtrace's graph
-tools for structure and blast radius; use Cortex for rationale, bans, and
-contracts.
-```
-
-Memtrace is the **memory layer** of the codebase, not a search engine that returns code. It has the full knowledge graph — every symbol, call, import, community, process, and API — with a time dimension. The point is to navigate that graph: who calls this, what's the blast radius, when did this change, what community is it part of. File tools are blind to all of that.
+Use Memtrace first for code discovery in indexed repositories. Use its graph to
+understand relationships, processes and impact; verify source when exact behavior
+matters. Retrieval is evidence, not a guarantee of complete coverage.
 
-**No exceptions for what's in the graph.**
+## Establish scope
 
-## Value Tracking
+Call `list_indexed_repositories` once per session. Select the actual repository
+and branch; pass `repo_id` explicitly when possible. It lists this session's
+store only, so a repository missing from it may still be indexed and live in
+another store. Do not index a parent containing unrelated repositories. For a
+deliberately shared workspace, verify its workspace marker and scope before
+indexing. If tools are unavailable, state that limitation and use bounded source
+inspection rather than blocking the task.
 
-Do not print usage receipts in normal answers. Memtrace records tool usage, graph facts, file references, and estimated context avoided internally. Users can inspect that in the local UI's Value panel.
+### Workspace boundary check
 
-## What Memtrace actually indexes
+Before indexing or reindexing, make sure the target path is the repo the user
+asked about. If the current folder is only a parent that contains multiple
+independent git repos, do **not** index the parent just because it is the open
+editor folder. That creates or reuses a shared `.memdb` and can make agents
+answer from stale repos.
 
-Memtrace's hybrid search = **BM25 over symbol metadata** (name, signature, file_path, kind) **+ semantic vector search over embedded code bodies** (first ~1500 chars of every Function / Method / Class / Struct / Interface body), fused via Reciprocal Rank Fusion.
+- For separate repos: use the actual git repo root as the `index_directory`
+  path, or ask the user to open/run the agent from that repo root.
+- For an intentional shared workspace: a portable manifest is the durable
+  form — `memtrace start --workspace-file <manifest>` declares the members and
+  records the manifest as the owner of the store's membership. The Folder
+  Group flow still works and the CLI now calls it legacy: the user blesses the
+  parent with `memtrace start --bless-workspace`, then verifies it with
+  `memtrace workspace status <path>`; the workspace marker should be present.
+- A store whose membership is already owned by a manifest or a Named Workspace
+  cannot be widened by a plain `memtrace start` from a parent folder. That
+  start is refused with "a folder-walked start cannot widen it. Run
+  `<command>`", and the refusal names the exact command to run instead. Run
+  it. Do not route around the refusal by indexing elsewhere. A folder-sourced
+  store has no owning definition, so that refusal does not apply to it. A
+  `memtrace mcp` session can never widen an existing store under any flag,
+  including `--workspace-file`: adding a repository is always a `memtrace
+  start` for that store, carrying the manifest or the workspace name when one
+  owns its members.
+- If `list_indexed_repositories` returns empty or its metadata says the MCP
+  child resolved a data dir from cwd because no workspace marker/git root was
+  found, surface the workspace mismatch. Do not "fix" it by indexing the broad
+  parent folder.
 
-The semantic side means **string literals, error messages, magic constants, log strings, and any text inside an indexed symbol's body are findable through `find_code`**. The body got embedded; the embedding catches it. You do NOT need `Grep` to hunt for `STRIPE_KEY_FOO_BAR` if it lives inside a function in your indexed codebase.
+## Search, then investigate
+
+- Exact symbol: `find_symbol(name=..., repo_id=...)`.
+- Behavior or concept: `find_code(query=..., repo_id=...)`.
+- Relationships: `get_symbol_context` or `analyze_relationships` on the useful hit.
+- Change impact: `get_impact`; confirm relevant callers against source.
+- Execution path: `get_process_flow`; follow its `next_offset` for further steps.
+- Architecture: `list_communities`, `find_central_symbols` and process tools.
+- Historical coupling or changes: `get_cochange_context`, `get_evolution`,
+  `get_changes_since` or `get_episode_replay` as appropriate.
+
+Inspect `find_code.context` first: concept queries include query-matched processes,
+communities and selected callers/callees, referencing primary results by one-based
+number. Set `include_context: true` for identifier searches or `false` for flat
+results. Expand a graph tool only when this context does not answer the question.
+Treat partial context, truncation and unavailable overlay context as incomplete
+evidence; selected static flows are not complete runtime traces.
+
+`context.next_calls` provides scoped follow-up arguments for the useful symbol
+and process. Before changing shared behavior, inspect relevant callers and
+callees to identify contracts the patch must preserve. Use process IDs for
+flow navigation. No sampled flow is not proof that no call path exists.
+
+Turn the requested behavior into observable tests, including failure and
+boundary cases. Check that tests exercise the failure condition itself;
+manual cleanup must not make a broken asynchronous operation appear correct.
+Run related existing tests to detect regressions before claiming completion.
+
+Read the bounded source span when verifying behavior, editing or quoting. Do not
+fetch whole files or entire process traces when a local span answers the question.
+`get_symbol_context` omits source bodies by default; use `include_content: true`
+for explicit expansion, and `limit`/`offset` for relationship pages. An omitted
+risk diagnostic means unknown, not zero callers or low risk. Check truncation and
+pagination metadata before describing a neighborhood as complete.
 
 ## Read the envelope before you diagnose anything
 
@@ -105,249 +152,82 @@ A forwarded read can also come back as a bounded `busy` answer with
 the graph lane and for how long. That is a wait, not an absence — retry, or
 narrow the call.
 
-## Zero results are not a grep license
-
-A genuine zero — `count: 0` from a tool that reported `repo_in_store: true` —
-is a coverage question. Do **not** infer that a source subdirectory is outside
-the index. Diagnose through Memtrace:
-
-1. Call `list_indexed_repositories` and identify the repo root/repo_id. It
-   lists this session's store only, so a repository missing from it may still
-   be indexed and live in another store.
-2. If the zero came from a tool that sets no `repo_in_store` key, re-ask about
-   the same repository through `find_code` or `find_symbol` before reading
-   anything into it. Those check membership; the first tool did not.
-3. If the path is under that indexed repo root, keep using Memtrace.
-4. Retry with broader `find_code` terms and, when available, `file_path` filters
-   such as `ui/`, `memtrace-ui/`, `src/`, or the framework directory.
-5. If the language/path still appears missing, run `index_directory` on the repo
-   root with `incremental: true` (or ask before `clear_existing: true`). Do
-   this only after steps 1 and 2 show the repository is a member of this store.
-6. Report the indexing coverage problem instead of silently switching to grep.
-
-### Workspace Boundary Check
-
-Before indexing or reindexing, make sure the target path is the repo the user
-asked about. If the current folder is only a parent that contains multiple
-independent git repos, do **not** index the parent just because it is the open
-editor folder. That creates or reuses a shared `.memdb` and can make agents
-answer from stale repos.
-
-- For separate repos: use the actual git repo root as the `index_directory`
-  path, or ask the user to open/run the agent from that repo root.
-- For an intentional shared workspace: a portable manifest is the durable
-  form — `memtrace start --workspace-file <manifest>` declares the members and
-  records the manifest as the owner of the store's membership. The Folder
-  Group flow still works and the CLI now calls it legacy: the user blesses the
-  parent with `memtrace start --bless-workspace`, then verifies it with
-  `memtrace workspace status <path>`; the workspace marker should be present.
-- A store whose membership is already owned by a manifest or a Named Workspace
-  cannot be widened by a plain `memtrace start` from a parent folder. That
-  start is refused with "a folder-walked start cannot widen it. Run
-  `<command>`", and the refusal names the exact command to run instead. Run
-  it. Do not route around the refusal by indexing elsewhere. A folder-sourced
-  store has no owning definition, so that refusal does not apply to it. A
-  `memtrace mcp` session can never widen an existing store under any flag,
-  including `--workspace-file`: adding a repository is always a `memtrace
-  start` for that store, carrying the manifest or the workspace name when one
-  owns its members.
-- If `list_indexed_repositories` returns empty or its metadata says the MCP
-  child resolved a data dir from cwd because no workspace marker/git root was
-  found, surface the workspace mismatch. Do not "fix" it by indexing the broad
-  parent folder.
-
-**Never say "the index only covers X, so grep is right" when the target path is
-inside the indexed repository.** That is an indexing freshness/coverage issue,
-not permission to abandon Memtrace.
-
-## The narrow exceptions where grep/glob are still right
-
-These are the ONLY cases where file tools beat memtrace:
-
-- **Files outside every indexed repo root.** Confirm this with
-  `list_indexed_repositories`; 0 search results or missing language stats do not
-  prove it, and neither does a `repo_not_in_store` refusal — that list covers
-  this session's store only, and the refusal's `diagnostic.repo_lives_in`
-  names the store that does hold the repository. Vendored deps, system
-  headers, and excluded dirs (`.git`, `node_modules`, `target`, `dist`) are
-  examples Memtrace cannot see.
-- **Non-source artifacts.** `.env`, `package.json`, build scripts, top-level `README.md`, raw config files. Memtrace indexes parseable code, not configuration text.
-- **Pure file-inventory questions.** "How many `*.test.ts` files exist", "list every Markdown file in `docs/`". You're asking for a file count, not a symbol search.
-- **Reading at a known path outside Memtrace.** For configs, docs, or non-source artifacts that Memtrace cannot index, file `Read` is fine. For source-code spans returned by Memtrace, read the precise line range (your harness's `Read` with offset/limit, or `get_source_window` if your harness lacks bounded reads). Do not whole-file Read when you have a span.
-
-For everything else inside the indexed repo, memtrace is the right tool.
-
-## The decision rule
-
-| Question Claude is asking | Right tool |
-|---|---|
-| "Where is symbol `foo` defined?" | `find_symbol(name="foo")` → then `get_symbol_context` for callers/callees/community, NOT a source read unless you're editing. |
-| "What calls `foo`?" | `get_symbol_context(repo_id, symbol="foo")` → callers with file:line. |
-| "How does authentication work?" | `find_code(query="authentication")` → `get_symbol_context` on the top hit, NOT a source read. |
-| "Find behavior X" with multi-word phrase (3+ words) | `find_code(verbatim)` first; if low confidence, fan out with identifier-shaped reshapes (camelCase / snake_case). |
-| "Find the function that uses `STRIPE_KEY_FOO_BAR`" | `find_code(query="STRIPE_KEY_FOO_BAR")` → semantic finds it inside any embedded body. |
-| "Where's that error message `'connection refused for tenant'`?" | `find_code(query="connection refused for tenant")` → semantic catches it. |
-| "What breaks if I change `foo`?" | `get_impact(repo_id, target="foo")` → blast radius. |
-| "Should I change/delete/refactor `foo`?" | `find_symbol`/`get_symbol_context` → `recall_decision("foo / subsystem / approach")`; if a symbol id is available, `why_is_this_here` + `governing_contracts`; then `get_impact`. |
-| "Can I use/switch to pattern or library X?" | `recall_decision("X")` FIRST; bans and conventions are decisions. Verify a matching decision with `verify_intent(decision_id)` before relying on it. |
-| "What changed in `auth.ts` last week?" | `get_evolution(repo_id, from="7d ago", mode="recent", file_path="auth.ts")`. |
-| The answer carries `error_code: "repo_not_in_store"` | Read `diagnostic.reason`. On `ambiguous_repo_id`, pass the exact id. Otherwise read `diagnostic.repo_lives_in` and route the question to the session attached to that store. Never grep, never `index_directory`. |
-| A `repo_id` tool answered zero with no `repo_in_store` key | It never checked membership. Re-ask through `find_code` or `find_symbol` before treating the zero as an absence. |
-| "List all `*.test.ts` files." | `Glob` (file inventory, not symbol search). |
-| "Find this string in my `.env`." | `Grep` (non-source artifact). |
-| "I'm about to edit `foo` — show me its source." | Bounded `Read(file_path, offset=start_line, limit=end_line-start_line+8)`, or `get_source_window` if your harness lacks bounded reads. Never whole-file. |
-| "Read config/doc file I already have the path of." | `Read` (non-source artifact, path is known). |
-
-## Parameter Types — Read This Before Calling Any Tool
-
-All memtrace MCP tools are **strictly typed**. Pass JSON numbers (not strings) for integer parameters.
-
-| Parameter | Correct | WRONG (fails with MCP error -32602) |
-|---|---|---|
-| `limit`, `min_size`, `depth`, `max_depth`, `last_n` | `limit: 20` | `limit: "20"` |
-| `repo_id`, `branch`, `name`, `symbol_name`, `query` | `repo_id: "my-repo"` | `repo_id: my-repo` (unquoted) |
-| `fuzzy`, `include_tests`, `invalidate` | `fuzzy: true` | `fuzzy: "true"` |
-| `get_evolution.from` | `from: "90d ago"` | `days: 90` (wrong param — use `from`, not `days`) |
-| `get_changes_since.since` | `since: "2026-04-13T10:43:00Z"` | `last_episode_id: "..."` (wrong param) |
-| `get_impact.target` / `get_symbol_context.symbol` | `target: "foo"` / `symbol: "foo"` | `symbol_id: "..."` (wrong — use name) |
-| `find_most_complex_functions` | `top_n: 10` | `limit: 10` (wrong param name) |
-| `get_cochange_context` | `target: "execute"` | `symbol: "execute"` (wrong param name) |
-
-If you see `failed to deserialize parameters: invalid type: string "N", expected usize`, remove the quotes from the number and retry.
-
-If you see `missing field 'from'`, you called `get_evolution` without `from` — pass e.g. `"90d ago"`, never `days`.
-
-Full parameter spec for every Memtrace tool: `references/mcp-parameters.md` (bundled at the memtrace-skills plugin root).
-
-## Check Indexing First (Once Per Session)
-
-```
-mcp__memtrace__list_indexed_repositories
-```
-
-If the current repo appears → Memtrace is active. Follow this skill for ALL code tasks.
-If not indexed → offer to index with `mcp__memtrace__index_directory`, then follow this skill.
-
-## Task → Tool Map
-
-| What you need | Use instead of Grep/Glob/Read |
-|---|---|
-| Find a function / class / symbol | `find_symbol` or `find_code` |
-| Understand how something works | `get_symbol_context` (the default next step) |
-| Find all callers of a function | `get_symbol_context` (callers field) |
-| Find all callees / dependencies | `get_symbol_context` (callees field) |
-| Trace a request / execution path | `get_process_flow` |
-| Understand module structure | `list_communities` |
-| Find the most important symbols | `find_central_symbols` |
-| Find API endpoints | `find_api_endpoints` |
-| Find where an API is called | `find_api_calls` |
-| Debug a problem | `get_symbol_context` → `get_impact` → `get_evolution` |
-| What changed recently? | `get_changes_since` or `get_evolution` |
-| What breaks if I change X? | `get_impact` |
-| Cross-service / cross-repo calls | `get_service_diagram` or `get_api_topology` |
-| Dependency between two symbols | `find_dependency_path` |
-| What files change together? | `get_cochange_context` |
-| Architecture overview | `list_communities` + `find_central_symbols` |
-| About to edit / quote — need exact lines | Bounded `Read(file, offset=start_line, limit=N)` (preferred), or `get_source_window` for path-resolution parity |
-| About to edit/refactor/delete existing code | `recall_decision` for the intent + `why_is_this_here`/`governing_contracts` when a symbol id is available, then `get_impact` |
-| About to choose or replace a library/pattern/architecture | `recall_decision` first; use `verify_intent` on any matching decision before contradicting it |
-| About to choose between competing idioms (ternary vs if-else, arrow vs fn-decl, const vs let, await vs `.then`) | `get_style_fingerprint(repo_id, file_path)` — empirical codebase norm; see `memtrace-style-fingerprint` workflow |
-
-## Standard Workflows
-
-### "How does X work?" / "Explain X"
-1. `find_symbol` or `find_code` → locate the symbol
-2. `get_symbol_context` → callers, callees, community, processes (this usually answers "how it works")
-3. `get_process_flow` (if it's a process/request path)
-4. Only if you need to quote source: bounded `Read` at start_line..end_line, or `get_source_window`
-
-### Debugging "X is broken"
-1. `find_symbol` → locate the broken thing
-2. `get_symbol_context` → understand its role
-3. `get_impact` → blast radius (what else breaks)
-4. `get_evolution(from=<lookback>, mode: recent)` → per-episode changelog near the incident
-5. `get_changes_since(since=<anchor>)` → catch-up since last session (requires stored `since` timestamp)
-
-### "Where is X defined / called?"
-1. `find_symbol` with `fuzzy: true`
-2. `get_symbol_context` for full caller/callee map
-3. Only if you need source text: bounded `Read` at start_line..end_line, or `get_source_window`
-
-### Before any code modification
-1. `find_symbol` → confirm you have the right target
-2. `get_symbol_context` → understand full context
-3. `recall_decision("<symbol/subsystem/approach>")` → surface recorded choices, bans, and conventions before deciding what to do
-4. If a `symbol_id` is available, `why_is_this_here(symbol_id)` + `governing_contracts(symbol_id)` before deleting, rewriting, or "cleaning up" odd code
-5. `get_impact` → know blast radius before touching anything
-6. `get_style_fingerprint(repo_id, file_path=<file>)` → match the codebase's empirical idiom (ternary vs if-else, arrow vs fn-decl, etc.) — see `memtrace-style-fingerprint` workflow for the full decision rule
-
-## Red Flags — STOP, Use Memtrace Instead
-
-You are violating this skill if you think:
-
-| Thought | Reality |
-|---|---|
-| "Let me grep for this" | `find_code` or `find_symbol` is faster and structurally aware |
-| "Let me glob for the file" | `find_symbol` returns exact location with context |
-| "Let me read the whole file" | `get_symbol_context` for the WHY (callers/callees/community); a bounded source read at start_line..end_line for the WHAT |
-| "I know why this is written this way" | Check Cortex first. Use `recall_decision`; use `why_is_this_here`/`governing_contracts` when you have a symbol id. |
-| "This looks unused/weird; I'll remove it" | `why_is_this_here` + `governing_contracts` first, then blast radius. CannotProve is unknown, not permission. |
-| "I'll just switch to library/pattern X" | `recall_decision("X")` first — you may be reintroducing a banned approach. |
-| "It's just a quick search" | Grep has no understanding of call graphs, communities, or time |
-| "I don't know if it's indexed" | Check with `list_indexed_repositories` first — takes 1 second |
-| "Memtrace returned 0 results" | Check `repo_in_store` first. If it is true, broaden the query, check repo_id/path coverage, then reindex if needed |
-| "The zero had no `repo_in_store`, so the repo is not indexed" | Only ten tools set that key. A zero from the others says nothing about membership — re-ask through `find_code` or `find_symbol` |
-| "It said `repo_not_in_store`, so I'll index it here" | The repository is already indexed in the store `diagnostic.repo_lives_in` names. Indexing here makes a second copy in the wrong store |
-| "Stats only show Rust, but I need `ui/` or `memtrace-ui/`" | That is a coverage diagnostic. Reindex the repo root; do not grep source code. |
-| "The user didn't say to use Memtrace" | User asked about the code. Repo is indexed. Use Memtrace. |
-| "This is a simple question" | Simple questions benefit most — one `find_symbol` vs 20 file reads |
-
-## When File Tools Are Still Correct
-
-Use Grep/Glob/Read ONLY for:
-- Non-source files or paths outside every indexed source repo
-- Files that are config, data, or docs (not source code symbols)
-- Repos or paths confirmed outside every Memtrace indexed root
-- **Official Memtrace product documentation** — use `memtrace-docs` (`ask_docs` / `search_docs` / `read_doc`), not file tools or web search
-
-For source-code spans already located by Memtrace, use a **bounded** read —
-your harness's `Read(file, offset, limit)` with the returned `start_line` /
-`end_line`, or `get_source_window` if your harness lacks bounded reads. Do
-not read the whole file.
-
-Never use file tools as a **discovery** mechanism when Memtrace is available.
-
-## Skill Priority
-
-This skill is a **process skill** — it runs BEFORE any implementation or search skill.
-
-When this skill applies, it overrides default file-search behavior. Use the specific Memtrace sub-skills for deep detail on each tool:
-
-- Discovery → `memtrace-search`
-- Impact analysis → `memtrace-impact`
-- Temporal / change analysis → `memtrace-evolution`
-- Rationale / prior decisions / bans / contracts → `memtrace-decision-memory`
-- Incident investigation → `memtrace-incident-investigation`
-- Architecture overview → `memtrace-codebase-exploration`
-- Refactoring → `memtrace-refactoring-guide`
-- Memtrace **product docs** (install, CLI, MCP, enterprise) → `memtrace-docs`
-
-## Output
-
-`find_symbol` / `find_code` return ranked symbol entries (`score` only with `include_diagnostics: true`):
-
-```json
-{ "name": "handleAuth", "kind": "Function", "file_path": "src/auth.ts",
-  "start_line": 42, "end_line": 87 }
-```
-
-`get_symbol_context` returns the graph neighborhood: `symbol`, `callers`, `callees`, `type_references`, `community`, `processes`, `api_callers_cross_repo`. Feed `start_line`/`end_line` into a bounded `Read` or `get_source_window` — never a whole-file read.
+A `repo_not_in_store` refusal is also not evidence that a path lies outside
+every indexed root: `list_indexed_repositories` covers this session's store
+only, and the refusal's `diagnostic.repo_lives_in` names the store that does
+hold the repository.
+
+## Handle misses without loops
+
+This ladder applies to a genuine zero — an empty or irrelevant result from a
+tool that reported `repo_in_store: true`. A refusal, or a zero from a tool
+that sets no `repo_in_store` key, is handled in the section above, not here.
+
+1. Distinguish a tool error, a refusal (`repo_in_store: false`), a zero from a
+   tool that sets no `repo_in_store` key, missing scope, wrong branch, pending
+   index/embedding job, stale index and a valid empty result. Do not treat an
+   error as a clean miss, and do not treat a refusal or a keyless zero as one
+   either — re-ask through `find_code` or `find_symbol` before reading
+   anything into a keyless zero.
+2. For an ambiguous query, make at most one targeted reformulation, using an
+   identifier or path hint where available, and a `file_path` filter such as
+   `ui/`, `memtrace-ui/`, `src/` or the framework directory when one applies.
+3. If the result remains empty or irrelevant, use a bounded filesystem search
+   (`rg`, Grep or Glob) and verify the matching source. A returned hit that does
+   not answer the question is also a retrieval miss. Do **not** infer from a
+   zero that a source subdirectory is outside the index.
+4. Record the original miss and fallback in diagnostic/benchmark evidence. Do
+   not count filesystem recovery as successful Memtrace retrieval, and report
+   the indexing coverage problem rather than silently switching to grep.
+5. Reindex only when there is evidence of stale or incomplete coverage, at the
+   correct repository root, and only once steps 1 and 2 show the repository is
+   a member of this store. Prefer incremental repair (`index_directory` with
+   `incremental: true`; ask before `clear_existing: true`). Never repeat
+   indexing merely because a semantic query did not retrieve a target, and
+   never reindex in response to a `repo_not_in_store` refusal.
+
+Memtrace combines full-text retrieval, vectors and graph expansion. Embedding
+eligibility, language support, source limits and ranking affect recall. Literal
+strings, short helpers and arbitrary body text are not guaranteed to appear in
+semantic results. Use source search to establish exhaustive literal occurrences.
+Configuration files, documentation, file inventories and excluded dependencies
+are also appropriate uses of file tools.
+
+## Check rationale before changing code
+
+BEFORE you edit/refactor/delete existing code or choose another pattern, call
+Cortex `recall_decision("<symbol/subsystem/approach>")` when available. If a symbol
+ID is available, consult `why_is_this_here(symbol_id)` and
+`governing_contracts(symbol_id)`. Verify a
+matching decision with `verify_intent` before relying on it. Unknown rationale
+is not evidence that there is no contract. Use graph impact for structure and
+Cortex for recorded choices, conventions and bans. Use `get_style_fingerprint`
+when choosing among competing local idioms.
+
+## Tool arguments
+
+Use JSON numbers for limits/depths and booleans for switches. Use symbol names
+for `get_symbol_context.symbol`, `get_impact.target` and relationship targets;
+use IDs only where the specific schema asks for one. Prefer the live schema over
+remembered parameters. `find_code` has no `kind` filter; use `find_symbol` for it.
+Search without an explicit repository uses safe scope inference, not an implicit
+search of every repository. `get_evolution` uses `from`, not `days`.
+
+For product setup or usage documentation, use `memtrace-docs`. Full tool parameter
+references are bundled with the skills package. Do not print routine tool usage
+receipts; preserve evidence internally and report meaningful findings and limits.
 
 ## Success criteria
 
-- The answer is grounded in Memtrace graph results (search hit → `get_symbol_context` / `get_impact`), not file-tool discovery.
-- Grep/Glob/Read appear only via the documented narrow exceptions (non-source artifacts, paths outside every indexed root, file inventory, bounded span reads).
-- A `repo_not_in_store` refusal was routed on `diagnostic.repo_lives_in`, not answered by grep and not answered by indexing the repository into this store.
-- Genuine zero-result queries (`repo_in_store: true`) were diagnosed (`list_indexed_repositories` → broaden → reindex), not bypassed to grep.
-- A zero from a tool that sets no `repo_in_store` key was re-checked through a membership-checking tool before it was called an absence.
+- The right repository and branch were used.
+- Graph claims are supported by retrieved edges, with missing/truncated data
+  made explicit, and exact behavioral claims are checked against source.
+- A `repo_not_in_store` refusal was routed on `diagnostic.repo_lives_in`, not
+  answered by grep and not answered by indexing the repository into this store.
+- A zero from a tool that sets no `repo_in_store` key was re-checked through a
+  membership-checking tool before it was called an absence.
+- Failed retrieval on a genuine zero (`repo_in_store: true`) is diagnosed and
+  bounded; it does not trigger query or reindex loops, and fallbacks remain
+  distinguishable from retrieval successes.
 - Any source read was bounded to the span Memtrace returned.
+- Existing rationale and contracts were checked when the tools were available.

package/plugins/memtrace-skills/skills/memtrace-search/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: memtrace-search
-description: "Find source code with Memtrace hybrid BM25+semantic search: symbols, functions, classes, types, constants, definitions, implementations, logic, or error strings inside code. Use when the user wants to find, search, locate, or look up code or asks where code lives. Do not use Grep, Glob, rg, find, or manual file search for code discovery. If Memtrace returns 0 results, broaden the Memtrace query and diagnose/reindex; do not switch to grep."
+description: "Find source code with Memtrace hybrid BM25+semantic search: symbols, functions, classes, types, constants, definitions, implementations, logic, or error strings inside code. Use when the user wants to find, search, locate, or look up code or asks where code lives. Use Memtrace first; after a diagnosed miss and one targeted retry, allow bounded source verification or fallback. Reindex only for evidence of stale or incomplete coverage."
 ---
 
 ## Overview
@@ -22,11 +22,13 @@ Find code using hybrid BM25 + semantic search (RRF). Primary discovery tool —
 | Param | Required | Default | Notes |
 |---|---|---|---|
 | `query` | yes | — | Natural language or symbol text |
-| `repo_id` | no | this store's members | Omitted, an unambiguous session resolves to its own repository; a multi-repo store fans out across its discovered members |
+| `repo_id` | no | this store's members | Safe scope inference: omitted, an unambiguous session resolves to its own repository; a multi-repo store fans out across its discovered members |
 | `limit` | no | 20 | Max 100 |
 | `file_path` | no | — | Path/directory substring filter |
 | `as_of` | no | now | ISO-8601 time-travel |
 | `include_diagnostics` | no | false | Set true for `id`, `score` in results |
+| `include_dependency_checks` | no | true | With diagnostics, set false for scores without pre-edit risk checks |
+| `include_context` | no | auto | Query-matched processes, communities and selected callers/callees; auto on for concept queries, off for identifiers |
 
 **No `kind` param on `find_code`** — use `find_symbol(kind=...)` to filter by symbol type.
 
@@ -39,7 +41,7 @@ Find code using hybrid BM25 + semantic search (RRF). Primary discovery tool —
 | Param | Required | Default | Notes |
 |---|---|---|---|
 | `name` | yes | — | Symbol name to search |
-| `repo_id` | no | inferred | One repository is inferred only when that is unambiguous; otherwise the call returns `repo_scope_required` |
+| `repo_id` | no | inferred | Safe scope inference: one repository is inferred only when that is unambiguous; otherwise the call returns `repo_scope_required` |
 | `fuzzy` | no | false | API field exists; currently exact-match in backend |
 | `edit_distance` | no | 2 | Only when fuzzy enabled |
 | `kind` | no | — | `Function`, `Class`, `Method`, etc. |
@@ -64,9 +66,27 @@ Full parameter spec for every Memtrace tool: `references/mcp-parameters.md` (bun
 
 Result shape: see [Output](#output) below.
 
-### 3. Hand off to graph tools
+### 3. Inspect query context, then expand if needed
 
-Save **`name`**, **`scope_path`**, and **`file_path`** — **not** internal IDs:
+Concept searches include a bounded `context` object. Its process matches and
+community members reference the primary `results` by one-based number. Inspect
+these and the selected callers/callees before making another graph call.
+Use `include_context: true` for identifier context, or `false` for flat results.
+Check `status`, `incomplete_reasons`, `coverage` and `payload_truncated`: omitted
+relationships are not proof of absence. The context contains selected matches,
+not a complete process trace. Worktree overlays report context unavailable until
+their graph is refreshed.
+
+For a code change, inspect the relevant caller/callee contracts before editing.
+`context.next_calls` supplies valid tool names and arguments for the selected
+symbol and flow; use these directly when they address the investigation.
+They preserve repository, branch and file disambiguation. Process navigation
+uses the returned process UUID. Symbol navigation uses name plus file path.
+Expand only the evidence needed; an empty sampled process list does not mean
+the symbol has no callers or callees.
+
+For symbol navigation, save **`name`**, **`scope_path`**, and **`file_path`**.
+For process navigation, retain its **process `id`**:
 
 ```json
 { "repo_id": "memdb", "symbol": "validateToken" }
@@ -74,12 +94,12 @@ Save **`name`**, **`scope_path`**, and **`file_path`** — **not** internal IDs:
 { "repo_id": "memdb", "target": "validateToken", "query_type": "find_callers" }
 ```
 
-Read source only when editing — bounded `Read(offset, limit)` at returned lines.
+Read source when verifying behavior, editing or quoting — bounded `Read(offset, limit)` at returned lines.
 
 ### Multi-word queries
 
 1. Try verbatim `find_code` query.
-2. If weak, fan out: camelCase, snake_case, domain identifiers.
+2. If weak, make one targeted reformulation with an identifier or path hint.
 3. Dedupe top hits by `file_path:start_line`.
 
 ## Output
@@ -124,3 +144,7 @@ names.
 | Assuming `fuzzy: true` always works | Backend is exact-match today — try spelling variants |
 | Skipping `list_indexed_repositories` | Verify repo is indexed first — it lists this session's store only |
 | Reading `repo_not_in_store` as an empty index | Nothing was searched; the repository lives in the store `diagnostic.repo_lives_in` names |
+
+## Retrieval limits and fallback
+
+A valid empty or irrelevant result is not a guarantee that the code is absent. Check scope, branch and indexing/embedding readiness; retry once with a targeted query. Then permit bounded source search and verification. Record the original miss and do not count fallback recovery as Memtrace retrieval success. Reindex only for demonstrated stale or incomplete coverage. Embeddings cannot guarantee literal-string or short-symbol recall. A `repo_not_in_store` refusal is not such a miss: nothing was searched, so route it to the store `diagnostic.repo_lives_in` names rather than falling back to source search or reindexing here.