memtrace-skills 0.8.2 → 0.8.4

package/plugins/memtrace-skills/skills/memtrace-refactoring-guide/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: memtrace-refactoring-guide
-description: "Build a phased, risk-scored refactoring plan from Memtrace complexity, dead-code, bridge, and impact analysis. Use when the user wants to refactor source code, reduce complexity, clean technical debt, split large functions, extract modules, reorganize code, or choose refactoring priorities. Do not use Grep or manual reference search to plan refactors; Memtrace provides complexity, dead-code, relationships, and impact context."
+description: "Build a phased, risk-scored refactoring plan from Memtrace complexity, dead-code, bridge, impact analysis, and Cortex decision-memory constraints. Use when the user wants to refactor source code, reduce complexity, clean technical debt, delete dead code, split large functions, extract modules, reorganize code, or choose refactoring priorities. Do not plan refactors from grep/manual reference search alone; check graph impact and decision rationale/bans/contracts before changing existing code."
 ---
 
 ## Overview
 
-Guided refactoring workflow — identifies refactoring candidates using structural analysis, scores them by risk and priority, and produces a phased refactoring plan. Combines complexity metrics, dead code detection, bridge analysis, and temporal evolution to prioritize what to refactor first and how to do it safely.
+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
 
@@ -49,7 +49,17 @@ Also call `get_symbol_context` to check:
 - How many processes does this symbol participate in? (More = more testing needed)
 - Is it part of a cross-repo API? (If yes, coordinate with consumers)
 
-### 4. Understand the neighbourhood
+### 4. Check decision memory before refactoring/removing
+
+For each top candidate, call `recall_decision("<symbol/subsystem/refactor intent>")`.
+If you have a numeric `symbol_id`, call `why_is_this_here(symbol_id)` and
+`governing_contracts(symbol_id)`.
+
+- A matching held decision/ban can veto or reshape the refactor.
+- Contracts become acceptance criteria for the new design.
+- CannotProve is unknown, not permission to delete.
+
+### 5. Understand the neighbourhood
 
 For each refactoring target, call `analyze_relationships`:
 - `find_callees` — what does it depend on? These become candidates for extraction
@@ -58,13 +68,13 @@ For each refactoring target, call `analyze_relationships`:
 
 Full parameter spec for every Memtrace tool: `references/mcp-parameters.md` (bundled at the memtrace-skills plugin root).
 
-### 5. Check community boundaries
+### 6. Check community boundaries
 
 Call `list_communities` and check: does the refactoring target sit at a community boundary?
 - If yes, the refactoring may involve splitting responsibilities across modules
 - If it belongs clearly to one community, the refactoring is more contained
 
-### 6. Produce the refactoring plan
+### 7. Produce the refactoring plan
 
 Synthesize into a phased plan:
 
@@ -84,8 +94,9 @@ For each item, include:
 1. **Target** — function/class name, file, current complexity score
 2. **Why** — complexity + volatility + blast radius rationale
 3. **How** — specific refactoring approach (extract method, split class, introduce interface)
-4. **Risk** — impact analysis rating + affected processes
-5. **Test Plan** — which callers/processes to verify
+4. **Decision Memory** — relevant Cortex decisions/bans/contracts, or CannotProve as unknown
+5. **Risk** — impact analysis rating + affected processes
+6. **Test Plan** — which callers/processes to verify
 
 ## Decision Points
 
@@ -93,9 +104,10 @@ For each item, include:
 |-----------|--------|
 | Complex + volatile + high blast radius | Highest priority — but plan carefully; incremental approach |
 | Complex + stable + low blast radius | Can wait; refactor when you're already touching nearby code |
-| Dead code with zero callers | Safe to delete — quick win |
+| Dead code with zero callers | Run Cortex provenance/recall first; zero callers is not proof that no decision/contract keeps it |
 | Bridge symbol with many dependents | Extract interface first, then refactor implementation behind it |
 | Symbol in cross-repo API | Coordinate with consumers; backward-compatible changes only |
+| Cortex returns a held ban/contract | Preserve it or ask before overriding it |
 
 ## Output
 
@@ -109,7 +121,7 @@ A phased plan (Phases 1–3). One worked entry:
 | Risk | High — upstream spans 3 processes incl. `checkout_flow`; incremental migration |
 
 Acceptance criteria:
-- Every plan item cites complexity, volatility, and blast radius — no gut-feel picks.
+- Every plan item cites complexity, volatility, blast radius, and decision-memory status — no gut-feel picks.
 - High/Critical-risk items include a test plan naming affected callers/processes.
 
 ## Common Mistakes

package/skills/commands/memtrace-decision-recall.md

@@ -1,6 +1,6 @@
 ---
 name: memtrace-decision-recall
-description: "Recall ranked decisions, bans, and conventions from Cortex decision memory by free-text query. Use when the user asks what was decided, what was chosen or rejected, whether there's a convention/ban/policy on something, or before re-picking a library, pattern, or approach that may already be settled. Do not reconstruct past decisions from git log or guesswork. To verify whether a known decision held, use memtrace-intent-verification; for symbol-scoped decision lineage/contracts, use memtrace-provenance."
+description: "Recall ranked decisions, bans, and conventions from Cortex decision memory by free-text query through the normal Memtrace MCP server. Use when the user asks what was decided/chosen/rejected, whether there is a convention/ban/policy, and before any non-trivial edit/refactor/delete or re-picking a library, pattern, architecture, or subsystem behavior that may already be settled. Do not reconstruct decisions from git log or guesswork. To verify whether a known decision held, use memtrace-intent-verification; for symbol lineage/contracts, use memtrace-provenance."
 allowed-tools:
   - mcp__memtrace__recall_decision
   - mcp__memtrace__verify_intent
@@ -16,7 +16,8 @@ metadata:
 `recall_decision` is the **free-text entry point** to decision memory. Given a query,
 it returns the statistically-ranked set of decisions/conversations that bear on it —
 including **bans** ("never use X", "don't do Y"), which are recorded as decisions.
-Use it before re-litigating a settled choice or contradicting a convention.
+Use it before re-litigating a settled choice, changing existing behavior, or
+contradicting a convention.
 
 This is the one decision-memory tool that takes plain text. The ranked decisions it
 returns carry the `decision_id`s the other tools (`verify_intent`, `get_arc`) need.
@@ -41,7 +42,8 @@ Full parameter spec for every Memtrace tool: `references/mcp-parameters.md` (bun
 
 `recall_decision(query)` — `query` is free text. Use the noun phrase of the thing in
 question: a library (`"redis vs in-memory cache"`), a pattern (`"error handling
-strategy"`), a subsystem (`"auth tokens"`), or the exact thing you're about to do.
+strategy"`), a subsystem (`"auth tokens"`), a symbol, or the exact edit/refactor/delete
+you are about to do.
 
 ### 2. Read the ranked result
 
@@ -71,7 +73,8 @@ require a Decision node and will honestly return CannotProve. See
 
 | Situation | Action |
 |-----------|--------|
-| About to choose a library/pattern/approach | `recall_decision` FIRST — you may be undoing a deliberate choice or ban |
+| About to edit/refactor/delete existing code where intent may matter | `recall_decision("<symbol/subsystem/behavior>")` FIRST — you may be crossing a recorded decision, ban, or convention |
+| About to choose or replace a library/pattern/architecture | `recall_decision` FIRST — you may be undoing a deliberate choice or ban |
 | User asks "did we decide X?" / "what's our convention on Y?" | `recall_decision("X" / "Y")` |
 | You suspect a "don't do this" rule exists | `recall_decision` — bans are decisions and will surface |
 | Recall returns a decision you're about to contradict | Surface it to the user verbatim; don't silently override |

package/skills/commands/memtrace-docs-ask.md

@@ -0,0 +1,99 @@
+---
+name: memtrace-docs-ask
+description: "Answer questions from official Memtrace documentation only — installation, CLI, MCP tools, fleet, Cortex, enterprise MemDB deploy, skills, configuration. Use when the user asks how Memtrace works or wants a cited explanation. Calls ask_docs on memtrace.io (RAG + guardrails). Do not guess product behavior from training data."
+allowed-tools:
+  - mcp__memtrace__ask_docs
+  - mcp__memtrace__search_docs
+  - mcp__memtrace__read_doc
+metadata:
+  author: "Syncable <support@syncable.dev>"
+  version: "1.0.0"
+  category: development
+---
+
+## Overview
+
+`ask_docs` sends the user's question to the hosted docs RAG backend. The server
+retrieves relevant doc chunks, generates an answer **only from that context**, and
+returns citations. Off-topic or ungrounded questions return `refused: true`.
+
+This is the **default** tool for "how does Memtrace X work?" questions.
+
+Umbrella routing: `memtrace-docs` workflow.
+
+## `ask_docs` parameters
+
+| Param | Required | Notes |
+|---|---|---|
+| `question` | yes | Pass the user's question verbatim when possible |
+
+```json
+{ "question": "How do I deploy MemDB with Docker Compose?" }
+```
+
+## Response shape
+
+```json
+{
+  "ok": true,
+  "answer": "…markdown with /docs/… links…",
+  "citations": ["enterprise/memdb-deploy", "cli/connect"],
+  "refused": false
+}
+```
+
+| Field | Meaning |
+|---|---|
+| `answer` | Grounded response text |
+| `citations` | Doc slugs used as context |
+| `refused` | `true` when no context or injection detected |
+| `refusalReason` | `no_context` or `injection` when refused |
+
+## Steps
+
+### 1. Ask
+
+Use the user's exact wording when it is already a clear question:
+
+```json
+{ "question": "What MCP tools are available?" }
+```
+
+### 2. Handle refusal
+
+If `refused: true` with `no_context`:
+
+1. Retry `search_docs` with shorter keywords
+2. `read_doc` on the best slug
+3. If still empty — tell the user docs did not cover it; do not invent
+
+### 3. Deepen with read_doc
+
+When the user needs exhaustive tables (e.g. all MCP tools):
+
+```json
+{ "slug": "mcp/tools" }
+```
+
+After `ask_docs` gave a summary.
+
+## Example questions → ask_docs
+
+| User asks | ask_docs question |
+|---|---|
+| How to install Memtrace? | `"How do I install Memtrace?"` |
+| What is Rail? | `"What is Memtrace Rail and how do I enable it?"` |
+| Enterprise MemDB on Azure | `"How do I deploy self-hosted MemDB on Azure?"` |
+| How to connect local memtrace to shared MemDB | `"How do engineers connect with memtrace connect?"` |
+| What skills exist? | `"What agent skills does Memtrace ship?"` |
+
+## Privacy note
+
+`ask_docs` sends the **question string** to memtrace.io, which runs retrieval and
+calls a hosted LLM (DeepSeek) server-side. No repo source code is transmitted.
+Do not paste secrets into questions.
+
+## Offline behavior
+
+`ok: false` → network or API error. Quote the `error` and `hint` fields; suggest
+checking connectivity or `MEMTRACE_DOCS_API_URL`.

package/skills/commands/memtrace-docs-read.md

@@ -0,0 +1,91 @@
+---
+name: memtrace-docs-read
+description: "Read the full plain-text body of an official Memtrace docs page by slug. Use when you know the page path (from search_docs, ask_docs citations, or user link) and need complete content — CLI reference, enterprise deploy guide, MCP tool tables. Calls read_doc or memtrace://docs/* resources on memtrace.io."
+allowed-tools:
+  - mcp__memtrace__read_doc
+  - mcp__memtrace__search_docs
+metadata:
+  author: "Syncable <support@syncable.dev>"
+  version: "1.0.0"
+  category: development
+---
+
+## Overview
+
+`read_doc` fetches the full rendered text of one docs page. Use after `search_docs`
+or `ask_docs` when excerpts are not enough — long flag tables, deploy runbooks,
+MCP tool inventories.
+
+Alternative: MCP resource `memtrace://docs/<slug>` via `read_resource` if your
+client prefers resources over tools.
+
+Umbrella routing: `memtrace-docs` workflow.
+
+## `read_doc` parameters
+
+| Param | Required | Notes |
+|---|---|---|
+| `slug` | yes | Path without `/docs/` prefix |
+
+```json
+{ "slug": "enterprise/memdb-deploy" }
+```
+
+Valid examples:
+
+- `getting-started`
+- `cli/start`
+- `mcp/tools`
+- `enterprise/connect`
+- `cli/rail` (hidden from sidebar but indexed)
+
+## Response shape
+
+```json
+{
+  "ok": true,
+  "slug": "enterprise/memdb-deploy",
+  "title": "Deploy MemDB",
+  "body": "…full plain text…"
+}
+```
+
+## Steps
+
+### 1. Resolve slug
+
+From user URL `https://memtrace.io/docs/cli/connect` → slug `cli/connect`.
+
+From `ask_docs` citations array → use slug directly.
+
+From unknown topic → `search_docs` first, then `read_doc` on top hit.
+
+### 2. Read and summarize
+
+Read the `body`, answer the user, keep `/docs/<slug>` links when citing.
+
+### 3. Multi-page topics
+
+Enterprise deploy + engineer connect:
+
+```json
+{ "slug": "enterprise/memdb-deploy" }
+```
+
+then
+
+```json
+{ "slug": "enterprise/connect" }
+```
+
+## When NOT to use read_doc
+
+| Situation | Use instead |
+|---|---|
+| User asked a natural-language question | `ask_docs` first |
+| You don't know which page | `search_docs` first |
+| User's **source code** in their repo | `memtrace-search` / `memtrace-first` |
+
+## Offline behavior
+
+`ok: false` → docs API unreachable. Do not substitute local README guesses.

package/skills/commands/memtrace-docs-search.md

@@ -0,0 +1,94 @@
+---
+name: memtrace-docs-search
+description: "Search official Memtrace documentation with semantic full-text search. Use when the user wants to find doc pages, locate a guide, or discover which docs cover a topic (fleet, MCP, CLI, enterprise MemDB, skills). Calls search_docs on memtrace.io. Do not grep local files or web-search for Memtrace product docs."
+allowed-tools:
+  - mcp__memtrace__search_docs
+  - mcp__memtrace__read_doc
+metadata:
+  author: "Syncable <support@syncable.dev>"
+  version: "1.0.0"
+  category: development
+---
+
+## Overview
+
+`search_docs` queries the hosted Memtrace docs corpus (same index as memtrace.io/docs
+and the Ask AI widget). Returns ranked **chunks** — not full pages. Follow with
+`read_doc` when you need the complete page.
+
+Umbrella routing: `memtrace-docs` workflow.
+
+## Quick Reference
+
+| Tool | Best for |
+|------|----------|
+| `search_docs` | Find which doc pages/sections match a topic |
+| `read_doc` | Load full page text after search hits |
+
+## `search_docs` parameters
+
+| Param | Required | Default | Notes |
+|---|---|---|---|
+| `query` | yes | — | Natural-language search string |
+| `limit` | no | 8 | Max chunks to return |
+
+```json
+{ "query": "deploy MemDB helm azure", "limit": 8 }
+```
+
+## Steps
+
+### 1. Search
+
+```json
+{ "query": "memtrace rail enable hook", "limit": 6 }
+```
+
+### 2. Inspect results
+
+Each hit includes:
+
+```json
+{
+  "slug": "cli/rail",
+  "pageTitle": "memtrace rail & route",
+  "h2Title": "Subcommands",
+  "h2Id": "enable-sub",
+  "excerpt": "…",
+  "distance": 0.12
+}
+```
+
+Lower `distance` ≈ better match.
+
+### 3. Read full pages when needed
+
+```json
+{ "slug": "cli/rail" }
+```
+
+Slug uses forward slashes: `enterprise/memdb-deploy`, `mcp/tools`, `getting-started`.
+
+## Common slugs
+
+| Topic | Slug |
+|---|---|
+| Getting started | `getting-started` |
+| MCP tools list | `mcp/tools` |
+| MCP docs tools | `mcp/docs-tools` |
+| Agent skills | `mcp/skills` |
+| Deploy MemDB (enterprise) | `enterprise/memdb-deploy` |
+| Connect to shared MemDB | `enterprise/connect` |
+| memtrace connect CLI | `cli/connect` |
+| Rail | `cli/rail` |
+
+## Offline behavior
+
+If `ok: false`, the docs API is unreachable. Report the error; do not fall back to
+hallucinated documentation. Local code-graph tools are unaffected.
+
+## Hand off
+
+- Natural-language "how do I…" → `memtrace-docs-ask` (`ask_docs`) instead
+- Found the right slug → `memtrace-docs-read` (`read_doc`)
+- User's **source code** → `memtrace-first` / `memtrace-search` (different corpus)

package/skills/commands/memtrace-preflight.md

@@ -1,10 +1,13 @@
 ---
 name: memtrace-preflight
-description: "Run a one-call pre-flight check on a single existing symbol before editing it: blast radius (who depends on it), co-change partners (files that historically change with it), complexity, 30-day churn, and a generated verification checklist. Use before modifying any existing function or symbol you did not just write. Do not start editing a non-trivial existing function without a pre-flight check; Memtrace knows the dependency graph and change history. For a full multi-symbol change plan or what-will-break analysis, use memtrace-change-impact-analysis."
+description: "Run a one-call pre-flight check on a single existing symbol before editing it: blast radius, co-change partners, complexity, 30-day churn, and verification checklist, then check Cortex decision memory for rationale/bans when intent may matter. Use before modifying any existing function or symbol you did not just write. Do not start editing a non-trivial existing function without pre-flight plus decision-memory recall/provenance; Memtrace knows the dependency graph, change history, and recorded decisions."
 allowed-tools:
   - mcp__memtrace__preflight_check
   - mcp__memtrace__get_impact
   - mcp__memtrace__get_cochange_context
+  - mcp__memtrace__recall_decision
+  - mcp__memtrace__why_is_this_here
+  - mcp__memtrace__governing_contracts
 metadata:
   author: "Syncable <support@syncable.dev>"
   version: "1.0.0"
@@ -26,6 +29,8 @@ symbol.
 | `preflight_check` | Full radar for one symbol: blast radius + co-change + churn + checklist |
 | `get_impact` | Deeper blast-radius walk when the radar flags HIGH/CRITICAL |
 | `get_cochange_context` | Wider co-change window when partners look surprising |
+| `recall_decision` | Recorded choices, bans, and conventions for the symbol/subsystem/behavior |
+| `why_is_this_here` / `governing_contracts` | Symbol-scoped rationale and constraints when a symbol id is available |
 
 > **Parameter types:** MCP parameters are strictly typed. Numbers must be
 
@@ -65,12 +70,23 @@ frequent partner, say so explicitly and why.
 - The complexity number should not have grown without a stated reason;
   if it did, simplify before declaring the work done.
 
+### Cortex gate before editing
+
+Before changing behavior, deleting code, or refactoring odd/legacy code:
+
+1. Run `recall_decision("<symbol/subsystem/behavior>")`.
+2. If the preflight/graph result gives you a numeric `symbol_id`, run
+   `why_is_this_here(symbol_id)` and `governing_contracts(symbol_id)`.
+3. Honor matching held decisions/bans. Treat CannotProve as unknown, not approval.
+
 ## Verdict guidance
 
 - `risk: CRITICAL/HIGH` — propose the change plan before editing; consider
   a feature flag or staged rollout.
 - `dependents: 0` — edit freely; note the symbol may be newly added or an
   entry point.
+- A matching Cortex decision/ban — surface it before editing and do not
+  contradict it without explicit user sign-off.
 
 ## Output
 

package/skills/commands/memtrace-provenance.md

@@ -1,6 +1,6 @@
 ---
 name: memtrace-provenance
-description: "Retrieve the governing decision lineage (why is this here) and the contracts that bind a symbol, from Cortex decision memory. Use before deleting, rewriting, or 'cleaning up' code that looks unused, odd, or redundant, and when the user asks why a symbol exists or what rules constrain it. Symbol-scoped; for free-text decision search use memtrace-decision-recall. Do not infer intent from the diff or assume unfamiliar code is safe to remove."
+description: "Retrieve the governing decision lineage (why is this here) and contracts that bind a symbol from Cortex decision memory through the normal Memtrace MCP server. Use before deleting, rewriting, refactoring, or 'cleaning up' existing code that looks unused, odd, redundant, legacy, or policy-sensitive, and when the user asks why a symbol exists or what rules constrain it. Symbol-scoped; for free-text decision search use memtrace-decision-recall first. Do not infer intent from the diff or assume unfamiliar code is safe to remove."
 allowed-tools:
   - mcp__memtrace__why_is_this_here
   - mcp__memtrace__governing_contracts
@@ -46,7 +46,10 @@ Full parameter spec for every Memtrace tool: `references/mcp-parameters.md` (bun
 ### 1. Get the symbol_id
 
 If you have a name or a "why" question, run `recall_decision(...)` first and take the
-`symbol_id` from the result (or the Cortex view). The id-based tools need a numeric id.
+`symbol_id` from the result if present, or use the id returned by a graph/Cortex view.
+The id-based tools need a numeric id. If you cannot get a symbol id, do not skip
+decision memory entirely: use `recall_decision("<symbol/subsystem/behavior>")` and
+report any matching decision/bans before changing the code.
 
 ### 2. Ask why it's here
 
@@ -71,8 +74,8 @@ was superseded via `recall_decision`) changes whether the code should still look
 | Situation | Action |
 |-----------|--------|
 | Code looks unused/dead and you want to delete it | `why_is_this_here` + `governing_contracts` BEFORE deleting; CannotProve is not a green light |
-| Code is written in a strange/non-obvious way | `why_is_this_here` — there's likely a decision explaining the oddity |
-| About to refactor a symbol's internals | `governing_contracts` — preserve every constraint, not just the test surface |
+| Code is written in a strange/non-obvious way | `why_is_this_here` if you have a symbol id; otherwise `recall_decision` for the symbol/subsystem |
+| About to refactor a symbol's internals | `why_is_this_here` + `governing_contracts` — preserve the rationale and every constraint, not just the test surface |
 | User asks "why is this here?" | `why_is_this_here(symbol_id)`; if you only have a name, `recall_decision` first |
 | All provenance returns CannotProve | Treat as unknown; combine with `memtrace-impact` (blast radius) and ask the user before removing |
 

package/skills/workflows/memtrace-change-impact-analysis.md

@@ -1,6 +1,6 @@
 ---
 name: memtrace-change-impact-analysis
-description: "Compute what a planned source-code change will break — blast radius, affected processes, cross-repo callers — and produce a risk-rated change plan. Use when the user needs to know what will break before a change: edits, refactors, API changes, renames, removals, PR reviews, or risk assessments. Do not manually grep references or browse files for impact; this workflow uses Memtrace graph context, impact, and change history. For a quick blast-radius check on one symbol, use memtrace-impact."
+description: "Compute what a planned source-code change will break — blast radius, affected processes, cross-repo callers, temporal stability, and Cortex decision-memory constraints — and produce a risk-rated change plan. Use before edits, refactors, API changes, renames, removals, PR reviews, or risk assessments, especially when changing established behavior or deleting code. Do not manually grep references or browse files for impact; use Memtrace graph context, change history, and decision recall/provenance."
 allowed-tools:
   - mcp__memtrace__find_symbol
   - mcp__memtrace__find_code
@@ -9,6 +9,10 @@ allowed-tools:
   - mcp__memtrace__get_evolution
   - mcp__memtrace__get_timeline
   - mcp__memtrace__analyze_relationships
+  - mcp__memtrace__recall_decision
+  - mcp__memtrace__why_is_this_here
+  - mcp__memtrace__governing_contracts
+  - mcp__memtrace__verify_intent
 metadata:
   author: "Syncable <support@syncable.dev>"
   version: "1.0.0"
@@ -18,7 +22,7 @@ user-invocable: true
 
 ## Overview
 
-Pre-change risk assessment workflow. Before modifying code, this workflow maps the full blast radius, identifies affected processes, checks recent change history for instability signals, and produces a risk-rated change plan.
+Pre-change risk assessment workflow. Before modifying code, this workflow maps the full blast radius, identifies affected processes, checks recent change history for instability signals, checks Cortex decision memory for recorded decisions/bans/contracts, and produces a risk-rated change plan.
 
 ## Steps
 
@@ -55,20 +59,30 @@ For each target, call `get_impact` (`repo_id`, `target`) with `direction: "both"
 | High | Plan incremental migration; consider feature flags |
 | Critical | Full migration strategy; backward-compatible changes required |
 
-### 4. Check temporal stability
+### 4. Check Cortex decision memory
+
+For each target or subsystem, call `recall_decision("<target/subsystem/approach>")`.
+If the graph result exposes a numeric `symbol_id`, also call
+`why_is_this_here(symbol_id)` and `governing_contracts(symbol_id)`.
+
+- Matching decision/ban/convention → include it in the plan before recommending a change.
+- Decision you intend to rely on → run `verify_intent(decision_id)` first.
+- CannotProve → record "no decision proven"; do not treat it as approval.
+
+### 5. Check temporal stability
 
 Call `get_evolution` (`repo_id`, `from: "30d ago"`, `mode: "compound"`), then `get_timeline` on each target symbol (requires `scope_path` + `file_path` from `find_symbol`):
 - Sparse timeline history + you're about to change it → structurally surprising; extra scrutiny warranted.
 - Target appears in `top_touched_symbols` → high churn + high impact = volatile hotspot.
 
-### 5. Map affected execution flows
+### 6. Map affected execution flows
 
 From step 2, you already know which processes are affected. For critical changes, use `analyze_relationships` (`repo_id`, `target`) with `query_type: "find_callers"` at `depth: 3` to trace the full transitive caller chain.
 
 `depth: 3` is a JSON number, not a string — the validator rejects `"3"`.
 Full parameter spec for every Memtrace tool: `references/mcp-parameters.md` (bundled at the memtrace-skills plugin root).
 
-### 6. Produce the risk assessment
+### 7. Produce the risk assessment
 
 Synthesize into a change plan:
 
@@ -77,8 +91,9 @@ Synthesize into a change plan:
 3. **Affected Processes** — which execution flows will be impacted
 4. **Cross-Service Impact** — any external callers or consumers
 5. **Stability Signal** — sparse `get_timeline` history (stable) vs frequent appearance in `top_touched_symbols` (volatile)
-6. **Recommended Approach** — based on risk: direct change, incremental migration, or backward-compatible evolution
-7. **Test Coverage** — which callers/processes to verify after the change
+6. **Decision Memory** — relevant decisions/bans/contracts, or CannotProve as unknown
+7. **Recommended Approach** — based on risk and decision constraints: direct change, incremental migration, or backward-compatible evolution
+8. **Test Coverage** — which callers/processes to verify after the change
 
 ## Decision Points
 
@@ -89,6 +104,7 @@ Synthesize into a change plan:
 | Symbol has sparse timeline but high impact | Extra review — this rarely changes; make sure the change is intentional |
 | Multiple processes affected | List each affected flow; recommend testing each one |
 | Symbol is a bridge point | Change may disconnect parts of the architecture — verify alternative paths exist |
+| Cortex returns a held ban/contract | Do not recommend contradicting it without explicit user sign-off |
 
 ## Output
 

package/skills/workflows/memtrace-decision-memory.md

@@ -1,6 +1,6 @@
 ---
 name: memtrace-decision-memory
-description: "Check Cortex decision memory — the umbrella entry point for decision recall, provenance (why is this here), intent verification, and governing contracts. Use before assuming WHY code exists, before making a choice that may contradict a past one, or before deleting/rewriting code that looks odd or redundant. Route: free-text what-was-decided → memtrace-decision-recall; why does this symbol exist / what constrains it → memtrace-provenance; did the decision hold → memtrace-intent-verification. Do not guess rationale from the diff or git log; Cortex remembers the decision, the ban, and whether it still holds."
+description: "Check Cortex decision memory through the normal Memtrace MCP tools — the umbrella entry point for decision recall, provenance (why is this here), intent verification, and governing contracts. Use before assuming WHY code exists, before any non-trivial edit/refactor/delete of existing code, before re-picking a library/pattern/architecture, or before contradicting an apparent convention. Route: free-text decisions/bans/conventions → memtrace-decision-recall; symbol lineage/contracts → memtrace-provenance; did the decision hold → memtrace-intent-verification. Do not guess rationale from the diff or git log."
 allowed-tools:
   - mcp__memtrace__recall_decision
   - mcp__memtrace__why_is_this_here
@@ -52,12 +52,14 @@ These five tools are **deterministic, zero-LLM**. Every call returns a labeled
 `CannotProve` is a real, trustworthy answer ("memory has nothing on this"), not a
 failure and not a green light. Never invent a rationale to fill the gap.
 
-## Server check (once per session)
+## Tool availability (once per session)
 
-These tools are served by the **`memcortex`** MCP server (decision memory), separate
-from the `memtrace` code-graph server. If `recall_decision` isn't available, decision
-memory isn't wired in this environment — say so and use `memtrace-first` instead;
-don't fabricate decisions.
+These tools are exposed on the normal **`memtrace` MCP server**:
+`recall_decision`, `why_is_this_here`, `verify_intent`, `get_arc`, and
+`governing_contracts`. Hosts do not need a second MemCortex MCP connection. If a
+tool call returns CannotProve because Cortex is unavailable (for example native
+Windows without WSL2), say decision memory was unavailable/unknown and continue
+with `memtrace-first`; do not fabricate decisions.
 
 ## The decision rule
 
@@ -65,9 +67,9 @@ don't fabricate decisions.
 |---|---|---|
 | "Did we already decide/choose/reject X?" "What's our convention on Y?" | `recall_decision("X")` | `memtrace-decision-recall` |
 | "Is there a ban / a 'don't do this' on Z?" | `recall_decision("Z")` — bans surface as decisions | `memtrace-decision-recall` |
-| About to re-pick a library/pattern/approach | `recall_decision` FIRST — don't re-litigate a settled call | `memtrace-decision-recall` |
+| About to edit behavior, re-pick a library/pattern/architecture, or change a subsystem policy | `recall_decision` FIRST — don't re-litigate a settled call | `memtrace-decision-recall` |
 | "Why is this code here?" "Why is it done this odd way?" | `why_is_this_here(symbol_id)` | `memtrace-provenance` |
-| About to delete/refactor code that looks unused or strange | `why_is_this_here` + `governing_contracts` before touching it | `memtrace-provenance` |
+| About to delete/refactor/clean up existing code, especially odd or "dead" code | `why_is_this_here` + `governing_contracts` before touching it | `memtrace-provenance` |
 | "What rules/contracts constrain this symbol?" | `governing_contracts(symbol_id)` | `memtrace-provenance` |
 | "Did decision D actually hold, or did we drift?" | `verify_intent(decision_id)` | `memtrace-intent-verification` |
 | "What commits/episodes implemented decision D?" | `get_arc(decision_id)` | `memtrace-intent-verification` |
@@ -95,10 +97,11 @@ have a name or a free-text question, start with `recall_decision`.** Do not inve
 ## Standard workflows
 
 ### "Why does this code exist / can I delete it?"
-1. `why_is_this_here(symbol_id)` → the governing decision, if any
-2. `governing_contracts(symbol_id)` → constraints that must survive a rewrite
-3. If a decision governs it → `verify_intent(decision_id)` to see if it still holds
-4. **CannotProve on all three ≠ safe to delete** — confirm with `memtrace-impact` (blast radius) and the user
+1. If you only have a name/free-text target, `recall_decision("<symbol/subsystem>")` first.
+2. If you have a `symbol_id`, `why_is_this_here(symbol_id)` → the governing decision, if any.
+3. `governing_contracts(symbol_id)` → constraints that must survive a rewrite.
+4. If a decision governs it → `verify_intent(decision_id)` to see if it still holds.
+5. **CannotProve on all checks ≠ safe to delete** — confirm with `memtrace-impact` (blast radius) and the user.
 
 ### "Should I do X?" (about to make a choice)
 1. `recall_decision("X")` → did we already decide or ban this?
@@ -114,6 +117,7 @@ have a name or a free-text question, start with `recall_decision`.** Do not inve
 | Thought | Reality |
 |---|---|
 | "This code looks unused, I'll delete it" | `why_is_this_here` first — a decision may govern it; deletion may reopen a closed issue |
+| "I'll just edit/refactor this existing behavior" | `recall_decision("<behavior/subsystem>")` first — the change may violate a recorded decision or ban |
 | "I'll just use library/pattern X" | `recall_decision("X")` — you may be undoing a deliberate ban |
 | "The diff/git log will tell me why" | Git shows *what changed*, not *what was decided or rejected*. Decision memory has the rationale and the bans. |
 | "CannotProve, so it's fine/approved" | CannotProve = unknown, not approved. Don't treat absence of a record as permission. |