memtrace-skills 1.2.9 → 1.2.11

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,14 +37,28 @@ 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
 
-Call `list_indexed_repositories` once per session. Select the actual repository
-and branch; pass `repo_id` explicitly when possible. It lists this session's
+Select the actual repository and branch; pass `repo_id` explicitly when
+possible. When the task already names the repository, use it directly; call
+`list_indexed_repositories` only when the repository or branch is unknown. 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
@@ -85,7 +99,7 @@ answer from stale repos.
 ## Search, then investigate
 
 - Exact symbol: `find_symbol(name=..., repo_id=...)`.
-- Behavior or concept: `find_code(query=..., repo_id=...)`.
+- Behavior or concept: `find_code(query=..., repo_id=..., limit=10)` (default 20 rows).
 - 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.
@@ -101,7 +115,8 @@ 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
+and process; copy them rather than rebuilding arguments. A `context.processes[].id`
+is the `process` for `get_process_flow`. 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.
 
@@ -112,8 +127,11 @@ 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
+`get_symbol_context` returns 5 rows per relationship section and omits source
+bodies and references by default: `pagination` names sections with more
+(`limit`/`offset`), `omitted` names what was left out (`include_references: true`,
+`include_details: true`), and `include_content: true` returns the symbol's body whole
+with short neighbour previews. An omitted
 risk diagnostic means unknown, not zero callers or low risk. Check truncation and
 pagination metadata before describing a neighborhood as complete.
 
@@ -157,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
@@ -171,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
@@ -200,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.
@@ -228,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
@@ -241,8 +265,10 @@ 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. Prefer the live schema over
-remembered parameters. `find_code` has no `kind` filter; use `find_symbol` for it.
+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
 search of every repository. `get_evolution` uses `from`, not `days`.
 
@@ -255,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.

package/skills/workflows/memtrace-guided-refactor.md

@@ -0,0 +1,89 @@
+---
+name: memtrace-guided-refactor
+description: "Run a saved, staged refactor shared with Memtrace's Quality page. Use for splitting tangled functions, extracting helpers, or continuing a guided refactor run with fixed file scope and checks between edits."
+user-invocable: true
+---
+
+Use the `guided_refactor` MCP tool to track the same run shown in Quality. This
+skill coordinates the agent's edits and language tools; Memtrace does not execute
+shell commands or rewrite source on behalf of the browser. Never invent check
+results. Recorded checks are agent-reported evidence, not proof of equivalence.
+
+## Diagnose
+
+1. Resolve the repository and exact symbol/file with `find_symbol` and
+   `get_symbol_context`. Use the runtime attached to that repository.
+2. If a run ID was supplied, call `guided_refactor` with `action: "get"`,
+   `repo_id`, and `run_id`. Otherwise call `action: "list"` and reuse a relevant
+   unfinished run; create one with `file_path` and `symbol` only when needed.
+3. Inspect function complexity, affected callers, evolution/churn, module
+   boundaries, existing tests, and decision-memory constraints. Use
+   `get_function_quality_metrics`, `get_impact`, `get_evolution`, and
+   `get_symbol_context` as available; read the selected source. Record missing
+   evidence explicitly. LOC alone is never a reason to split code.
+4. Respect the returned classification. `Manual` runs permit diagnosis and
+   blueprint only. In this first version, staged source work is available for
+   Rust, TypeScript, JavaScript, Python, and Go in Git checkouts. Other indexed
+   languages and configuration files still get a saved manual plan. Nothing is
+   classified Automatic.
+
+## Blueprint
+
+Call `get` before running baseline checks and retain its `snapshot`. Run the
+project's compiler/type checker and relevant behavior tests. Compare the exported
+API and affected callers. If a check fails or is unavailable, record that fact;
+do not label it passed or begin source work.
+
+Submit `action: "blueprint"` with the returned `revision`, retained `snapshot`,
+diagnostic evidence in `note`, baseline `checks`, and 1–12 ordered `steps`:
+
+```json
+{
+  "title": "Capture diagnostic behavior",
+  "operation": "capture_tests",
+  "files": ["src/parser.rs", "tests/parser.rs"],
+  "boundary": "Add cases for existing diagnostics; preserve parsing behavior"
+}
+```
+
+The only staged operations are `capture_tests` and `extract_helper`. Name every
+file a step can change, including planned new files, with repository-relative
+paths. Keep each step small enough to review. Do not change generated code,
+ownership or lifetime contracts, macros, import side effects, public APIs, or
+configuration semantics as an incidental extraction. If those boundaries cannot
+be justified, pause and explain the manual decision needed.
+
+Every check has `kind` (`compiler`, `tests`, or `api`), `command`, `passed`, and
+`evidence`. All three kinds are required. Evidence should include exact commands,
+results/counts, and uncertainty. API evidence can be a documented source/caller
+comparison when the project has no API-check command.
+
+## Execute one step
+
+1. Call `get`, inspect saved state, and send `action: "begin"` with `revision`,
+   `snapshot`, and one stable `agent_id`. The coordinator refuses overlapping
+   active runs and source changes between steps. Do not delegate overlapping edits.
+2. Make only the active step's bounded change. Preserve existing unrelated edits.
+   Do not commit during a run: a changed Git HEAD requires a fresh diagnosis.
+3. Call `get` after editing and **before** running the checks. Retain that snapshot,
+   run the compiler, tests, and API comparison, then send `action: "checkpoint"`
+   with that same `snapshot`, current `revision`, `agent_id`, `checks`, and `note`.
+   Never refresh the snapshot after tests merely to get past a stale-source gate.
+4. Inspect the response. A paused run is not a passed checkpoint. Stop editing
+   until the failure is understood. Keep failed evidence visible. To resume after
+   fixing the active step, obtain a fresh snapshot, rerun all checks, and send
+   `action: "resume"` with checks and an explanation, then checkpoint the step.
+   Restore an accidental scope escape without discarding someone else's work;
+   otherwise create a new diagnosis with an explicitly reviewed scope.
+5. Begin the next step only after the preceding checkpoint is accepted.
+
+## Verify
+
+After every step is checked, the run enters Verify. Compare before/after
+complexity, callers, public API, test results, and the actual diff. Get a snapshot,
+run final checks, then submit `action: "complete"` with `revision`, `snapshot`,
+`agent_id`, `checks`, and the comparison in `note`. State what remains unproven.
+
+The Quality page shows saved stages, agent, scope, current tracked-file diff,
+failed checks, and the final comparison. Closing the browser does not discard the
+run. Use `pause` with a reason whenever the next safe step needs a decision.

package/skills/workflows/memtrace-refactoring-guide.md

@@ -23,6 +23,10 @@ user-invocable: true
 
 ## Overview
 
+For an executable sequence with persisted progress and checks between edits, use
+`memtrace-guided-refactor`. This guide remains the broader prioritization and
+planning workflow; a guided run carries an approved bounded plan into execution.
+
 Guided refactoring workflow — identifies refactoring candidates using structural analysis, scores them by risk and priority, checks Cortex decision memory for rationale/bans/contracts, and produces a phased refactoring plan. Combines complexity metrics, dead code detection, bridge analysis, temporal evolution, and decision memory to prioritize what to refactor first and how to do it safely.
 
 ## Steps

package/skills/workflows/memtrace-session-continuity.md

@@ -14,6 +14,10 @@ user-invocable: true
 
 ## Overview
 
+### Choose the scope
+
+Use this entry to resume from a saved session anchor. For the fixed last-24-hour briefing, hotspots, or a session self-audit, use `memtrace-daily`. Preserve the requested time window instead of treating both workflows as the same catch-up.
+
 Session continuity for agents. Store a timestamp from your last session and call `get_changes_since` to see exactly what happened since then — then drill into details with `get_evolution` if needed.
 
 **Core principle:** Persist a `since` timestamp (or the `until` from your last catch-up call). Never invent a `days` parameter.