memtrace-skills 1.2.10 → 1.2.13

package/skills/workflows/memtrace-first.md

@@ -1,6 +1,6 @@
 ---
 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 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."
+description: "Use indexed graph and decision context for nontrivial code discovery, debugging, caller or consumer analysis, cross-file changes, impact, history, and recorded contracts. Follow useful retrieval with relevant relationships and current-source verification. Ordinary tools remain available; explicit user and project workflows take precedence."
 allowed-tools:
   - mcp__memtrace__list_indexed_repositories
   - mcp__memtrace__index_directory
@@ -37,9 +37,22 @@ metadata:
 ---
 # Memtrace First
 
-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.
+Use Memtrace when indexed context helps resolve a concrete question about code,
+relationships, processes, change impact or recorded decisions. Retrieval is
+evidence, not a guarantee of complete coverage or correct behavior.
+
+## Respect the chosen workflow
+
+This is the managed contextual default. Explicit user and project instructions,
+including custom strict workflows and opt-outs, take precedence. Keep the existing
+Rail setting: `off`, `observe`, `nudge`, `rail` or `strict`. Do not change a user's
+mode or treat this default as authorization for indexing or other external actions.
+
+Ordinary source search, reads, edits and tests remain available. Use them directly
+for small, known local changes, exact text searches, or questions the graph cannot
+answer. There is no mandatory first call, query quota or minimum tool count. For
+nontrivial discovery or shared behavior, prefer Memtrace's indexed context and
+follow useful hits with the relationships that answer the open question.
 
 ## Establish scope
 
@@ -162,9 +175,11 @@ searched nothing. The `diagnostic` block names the store that answered, its
    problem: the id matches more than one repository in *this* store, and the
    message says to pass the exact id. Do that and stop here. Everything below
    applies to the `not_in_store` reason.
-2. Do not fall back to file search. The refusal says so itself, in `_note`:
-   "Wrong store for this repo_id; do not fall back to filesystem search, ask
-   the session attached to the store named in diagnostic.repo_lives_in."
+2. Route graph questions to the owning store. A filesystem match cannot turn
+   this refusal into successful graph retrieval or prove that graph edges are
+   absent. Ordinary source work may continue when the actual checkout, path and
+   branch have been verified; keep that evidence separate from the unavailable
+   graph answer. Do not freeze the user's workflow while waiting for a store.
 3. Do not call `index_directory`. The repository is already indexed in the
    store `repo_lives_in` names. Indexing it here would build a second copy in
    the wrong store — writes are never routed to another store, so the call
@@ -176,7 +191,9 @@ searched nothing. The `diagnostic` block names the store that answered, its
    or `--workspace <name>` when a manifest or a Named Workspace owns its
    scope.
 5. If `repo_lives_in` is absent, no live Memtrace runtime declares the
-   repository. Running `memtrace start` in its own workspace is the fix.
+   repository. If graph access is needed and setup is authorized, start Memtrace
+   in that repository's own workspace. Ordinary verified source work need not
+   wait; a retrieval refusal is not authorization to create another index.
 
 A refusal is not the only outcome. When the runtime whose store declares the
 repository is live and publishes a reachable control port, the same read is
@@ -205,8 +222,9 @@ that sets no `repo_in_store` key, is handled in the section above, not here.
    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.
+   either. Use a membership-checking tool when a membership or absence claim
+   matters; a keyless zero alone cannot establish it. Ordinary source
+   verification remains available without an extra graph-call prerequisite.
 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.
@@ -233,8 +251,9 @@ 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
+When changing shared behavior, deleting code, or revisiting an approach that may
+have a recorded contract, use Cortex `recall_decision("<symbol/subsystem/approach>")`
+when available and relevant. 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
@@ -246,7 +265,8 @@ when choosing among competing local idioms.
 
 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. When a call is rejected,
+use a returned exact UUID when that tool supports identity-based recovery. Check
+the actual schema rather than guessing an argument name. When a call is rejected,
 check that tool's schema rather than retrying from memory; do not pre-read schemas.
 `find_code` has no `kind` filter; use `find_symbol` for it.
 Search without an explicit repository uses safe scope inference, not an implicit
@@ -261,12 +281,17 @@ receipts; preserve evidence internally and report meaningful findings and limits
 - 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 `repo_not_in_store` graph question was routed on `diagnostic.repo_lives_in`,
+  not answered by indexing another copy into this store. Any ordinary source
+  fallback verified the actual checkout and was not reported as graph evidence.
 - 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.
+- Source inspection was scoped to the question; exact claims and edits were
+  verified against the current source rather than inferred from graph edges.
+- Relevant recorded rationale and contracts were checked when available.
+- Before finishing, compare the requested requirements with the implementation
+  and verification: state any remaining unverified behavior. This checklist is
+  a review aid, not machine-verified correctness or an extra approval gate.