memtrace-skills 0.8.2 → 0.8.4

package/skills/workflows/memtrace-docs.md

@@ -0,0 +1,129 @@
+---
+name: memtrace-docs
+description: "Route Memtrace product documentation questions to the hosted docs MCP tools before guessing, searching the web, or reading stale local copies. Use when the user asks how Memtrace works, how to install/configure CLI/MCP/fleet/Cortex/enterprise MemDB, what tools or skills exist, what a command does, or wants the agent to read up on official docs. Calls search_docs, ask_docs, or read_doc on memtrace.io (override with MEMTRACE_DOCS_API_URL). Do not hallucinate Memtrace behavior — query docs first. Separate from memtrace-first (your repo's code graph)."
+allowed-tools:
+  - mcp__memtrace__search_docs
+  - mcp__memtrace__ask_docs
+  - mcp__memtrace__read_doc
+metadata:
+  author: "Syncable <support@syncable.dev>"
+  version: "1.0.0"
+  category: development
+---
+
+# Memtrace Docs First
+
+## The Iron Law
+
+```
+IF THE USER ASKS ABOUT MEMTRACE PRODUCT DOCS → USE DOCS MCP TOOLS FIRST.
+Do not guess CLI flags, MCP tool lists, enterprise deploy steps, or fleet rules
+from memory. Query the hosted documentation corpus at memtrace.io (or
+MEMTRACE_DOCS_API_URL), then answer with citations.
+
+memtrace-first  = your indexed SOURCE CODE (find_code, get_impact, …)
+memtrace-docs   = official MEMTRACE DOCUMENTATION (search_docs, ask_docs, read_doc)
+```
+
+Docs tools call the **hosted** Memtrace docs API over HTTPS. They do **not** read
+your local MemDB or your repo. Core graph tools stay offline; docs tools degrade
+gracefully when the network is down (`ok: false` + hint).
+
+## Server check (once per session)
+
+Confirm the docs tools are available on your `memtrace` MCP server:
+
+- `search_docs` — ranked chunks (slug, title, H2, excerpt)
+- `ask_docs` — grounded Q&A `{ answer, citations[], refused }`
+- `read_doc` — full page text by slug
+- Resources: `memtrace://docs/<slug>` via `read_resource` (optional)
+
+If none of these exist, the MCP build may be outdated — tell the user to update
+Memtrace and run `npx -y memtrace-skills@latest install`.
+
+Override API host: `MEMTRACE_DOCS_API_URL` (default `https://memtrace.io`).
+
+## The decision rule
+
+| User is asking | Right tool | Sub-skill |
+|---|---|---|
+| "How do I install / configure / deploy X in Memtrace?" | `ask_docs(question=…)` | `memtrace-docs-ask` |
+| "What MCP tools / skills / CLI commands exist?" | `ask_docs` or `search_docs` then `read_doc` on hit slugs | `memtrace-docs-ask` / `memtrace-docs-search` |
+| "What does `memtrace rail enable` do?" | `ask_docs` | `memtrace-docs-ask` |
+| "Find docs about fleet coordination" | `search_docs(query=…)` | `memtrace-docs-search` |
+| "Read the full getting-started page" | `read_doc(slug="getting-started")` | `memtrace-docs-read` |
+| "Read enterprise MemDB deploy guide" | `read_doc(slug="enterprise/memdb-deploy")` | `memtrace-docs-read` |
+| Need several related sections | `search_docs` → `read_doc` on top slugs | `memtrace-docs-search` + `memtrace-docs-read` |
+
+**Default for natural-language questions:** `ask_docs` — it retrieves context and
+returns a cited answer in one call.
+
+**Default for "find the doc about…":** `search_docs` — scan chunks, then `read_doc`
+if you need the full page.
+
+## Standard workflows
+
+### "How does X work in Memtrace?" (most common)
+
+1. `ask_docs(question="<user question verbatim>")`
+2. If `refused: true` or `ok: false` → `search_docs` with shorter keywords → `read_doc` on best slug
+3. Quote the answer; link slugs as `/docs/<slug>` when helpful
+4. If docs say "not found", say so — do not invent flags or behavior
+
+### "What tools / commands / skills are available?"
+
+1. `ask_docs(question="What MCP tools are available?")` or fleet/skills variant
+2. If the answer lists categories but user wants exhaustive detail → `read_doc(slug="mcp/tools")`
+3. For agent skills → `read_doc(slug="mcp/skills")`
+
+### "Read up on X before we implement"
+
+1. `search_docs(query="X", limit=8)`
+2. `read_doc(slug=<top hit>)` for each page you will rely on
+3. Summarize with citations; use `memtrace-first` only when switching to **their repo's code**
+
+### Enterprise / self-hosted MemDB
+
+1. `ask_docs(question="How do I deploy MemDB with Helm on Azure?")` or user wording
+2. Follow-up `read_doc(slug="enterprise/memdb-deploy")` for operator steps
+3. Engineer connect → `read_doc(slug="enterprise/connect")` or `cli/connect`
+
+## Red flags — STOP, use docs tools
+
+| Thought | Reality |
+|---|---|
+| "I know how Memtrace fleet works from training data" | Product docs change — `ask_docs` first |
+| "I'll grep the repo for README" | User repo ≠ official docs — use `search_docs` / `read_doc` |
+| "I'll web-search Memtrace" | Use hosted docs API — same corpus as memtrace.io/docs |
+| `ask_docs` returned `refused: true` | Docs corpus had no match — say so; try `search_docs` with different terms |
+| `ok: false` network error | Report offline; core Memtrace graph tools still work locally |
+
+## Relationship to other skills
+
+| Skill | When |
+|---|---|
+| `memtrace-docs` | Questions about **Memtrace product** (install, MCP, fleet, Cortex, enterprise) |
+| `memtrace-first` | Questions about **the user's indexed source code** |
+| `memtrace-decision-memory` | **Why** code exists (Cortex decisions) — not product docs |
+
+Use both when needed: docs for "how is Memtrace supposed to work?", graph tools for
+"how does *this repo* implement it?"
+
+## Output
+
+Prefer citing doc slugs returned in `citations` or `search_docs` results:
+
+```
+ask_docs → { ok: true, answer: "…", citations: ["cli/rail", "mcp/skills"], refused: false }
+search_docs → { ok: true, results: [{ slug, pageTitle, h2Title, excerpt }] }
+read_doc → { ok: true, slug, title, body }
+```
+
+When `refused: true`, tell the user the docs did not cover it and suggest browsing
+https://memtrace.io/docs or rephrasing.
+
+## Sub-skills
+
+- Discovery / chunk search → `memtrace-docs-search`
+- Grounded Q&A → `memtrace-docs-ask`
+- Full page read → `memtrace-docs-read`

package/skills/workflows/memtrace-first.md

@@ -1,6 +1,6 @@
 ---
 name: memtrace-first
-description: "Route code discovery, debugging, flow tracing, and how-code-works questions in indexed source-code repos to Memtrace graph tools. Use first — before searching files, reading code for discovery, debugging, tracing flows, finding implementations, understanding behavior, or answering how code works. Do not use Grep, Glob, rg, find, or manual file browsing for code discovery when Memtrace is indexed. Zero results, missing languages, or partial-looking stats are not permission to grep; diagnose/reindex with Memtrace."
+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."
 allowed-tools:
   - mcp__memtrace__list_indexed_repositories
   - mcp__memtrace__index_directory
@@ -23,6 +23,10 @@ allowed-tools:
   - mcp__memtrace__get_style_fingerprint
   - mcp__memtrace__find_most_complex_functions
   - mcp__memtrace__get_source_window
+  - mcp__memtrace__recall_decision
+  - mcp__memtrace__verify_intent
+  - mcp__memtrace__why_is_this_here
+  - mcp__memtrace__governing_contracts
   - Read
   - Grep
   - Glob
@@ -44,6 +48,12 @@ 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.
@@ -103,6 +113,8 @@ For everything else inside the indexed repo, memtrace is the right tool.
 | "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")`. |
 | "List all `*.test.ts` files." | `Glob` (file inventory, not symbol search). |
 | "Find this string in my `.env`." | `Grep` (non-source artifact). |
@@ -160,6 +172,8 @@ If not indexed → offer to index with `mcp__memtrace__index_directory`, then fo
 | 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
@@ -185,8 +199,10 @@ If not indexed → offer to index with `mcp__memtrace__index_directory`, then fo
 ### Before any code modification
 1. `find_symbol` → confirm you have the right target
 2. `get_symbol_context` → understand full context
-3. `get_impact` → know blast radius before touching anything
-4. `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
+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
 
@@ -197,6 +213,9 @@ You are violating this skill if you think:
 | "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" | Broaden the Memtrace query, check repo_id/path coverage, then reindex if needed |
@@ -210,6 +229,7 @@ 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` /
@@ -227,9 +247,11 @@ When this skill applies, it overrides default file-search behavior. Use the spec
 - 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
 

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

@@ -1,6 +1,6 @@
 ---
 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."
 allowed-tools:
   - mcp__memtrace__find_most_complex_functions
   - mcp__memtrace__find_dead_code
@@ -10,6 +10,10 @@ allowed-tools:
   - mcp__memtrace__get_symbol_context
   - mcp__memtrace__analyze_relationships
   - mcp__memtrace__list_communities
+  - 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"
@@ -19,7 +23,7 @@ user-invocable: true
 
 ## 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
 
@@ -63,7 +67,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
@@ -72,13 +86,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:
 
@@ -98,8 +112,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
 
@@ -107,9 +122,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
 
@@ -123,7 +139,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