memtrace 0.8.9 → 0.8.11

package/pi-package/skills/memtrace-codebase-exploration/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: memtrace-codebase-exploration
+description: Map an indexed source-code repo into a structured overview — scale, communities, central symbols, execution flows, API surface, recent activity. Use when the user wants to explore, understand, onboard to, map, or get an overview of an indexed source-code repo, architecture, modules, or major flows. Do not use find, grep, or manual file browsing as the first exploration path; Memtrace provides structured graph briefing. Do NOT use for change history / what-changed questions — use memtrace-evolution.
+allowed-tools: memtrace_index_directory memtrace_check_job_status memtrace_list_indexed_repositories memtrace_get_repository_stats memtrace_list_communities memtrace_list_processes memtrace_find_central_symbols memtrace_find_bridge_symbols memtrace_find_api_endpoints memtrace_get_api_topology memtrace_get_evolution memtrace_find_most_complex_functions
+license: MIT
+metadata:
+  author: "Memtrace <support@syncable.dev>"
+  version: "1.0.0"
+  category: development
+---
+
+## Overview
+
+Full codebase exploration workflow — from indexing through architectural understanding. Chains indexing, graph algorithms, community detection, and temporal analysis into a structured onboarding experience. Use this when someone is new to a codebase and needs to build a mental model.
+
+## Steps
+
+### 1. Index the codebase
+
+Call `memtrace_list_indexed_repositories` first. If the repo is already indexed, skip to step 2.
+
+Otherwise, call `memtrace_index_directory` with the project path (or run `/memtrace:index`), then poll `memtrace_check_job_status` until completion.
+
+**Success criteria:** Repo appears in `memtrace_list_indexed_repositories` with non-zero node/edge counts.
+
+### 2. Get the lay of the land
+
+Call `memtrace_get_repository_stats` to understand scale:
+- How many functions, classes, methods, interfaces?
+- How many relationships (calls, imports, extends)?
+- How many communities and processes were detected?
+
+Report these numbers to the user — they set expectations for the codebase's size and complexity.
+
+### 3. Map the architecture (communities)
+
+Call `memtrace_list_communities` to see how the codebase naturally clusters into logical modules.
+
+**Decision:** If >10 communities, summarize the top 5–7 by size and let the user ask about specific ones.
+
+Each community represents a cohesive module — these are the "areas" of the codebase.
+
+### 4. Find the most important symbols
+
+Call `memtrace_find_central_symbols` — PageRank over CALLS/REFERENCES edges (no `method` param):
+
+```json
+{ "repo_id": "<repo>", "limit": 15 }
+```
+
+These are the symbols that the rest of the codebase depends on most heavily. They form the "skeleton" of the architecture.
+
+### 5. Find architectural bottlenecks
+
+Call `memtrace_find_bridge_symbols` to identify chokepoints — symbols that connect otherwise-separate parts of the codebase.
+
+**Decision:** If bridge symbols overlap heavily with central symbols, flag them as critical infrastructure — high importance AND single point of failure.
+
+### 6. Map execution flows
+
+Call `memtrace_list_processes` to discover entry points:
+- HTTP handlers (API endpoints)
+- Background jobs
+- CLI commands
+- Event handlers
+
+This shows HOW the code is actually used at runtime, not just how it's structured.
+
+### 7. Map the API surface (if applicable)
+
+Call `memtrace_find_api_endpoints` to list all HTTP routes.
+
+**Decision:** If multiple repos are indexed, also call `memtrace_get_api_topology` to map service-to-service dependencies.
+
+### 8. Recent activity
+
+Call `memtrace_get_evolution` to see recent activity:
+
+```json
+{ "repo_id": "<repo>", "from": "30d ago", "mode": "overview" }
+```
+
+Check `totals.episode_count` and episode boundaries. For file/symbol hotspots, switch to `compound`:
+
+```json
+{ "repo_id": "<repo>", "from": "30d ago", "mode": "compound" }
+```
+
+Review `top_changed_files` and `top_touched_symbols`.
+
+### 9. Complexity hotspots
+
+Call `memtrace_find_most_complex_functions`:
+
+```json
+{ "repo_id": "<repo>", "top_n": 10 }
+```
+
+Full parameter spec for every Memtrace tool: [`../references/mcp-parameters.md`](../references/mcp-parameters.md).
+
+## Report synthesis
+
+Synthesize findings into a structured overview:
+
+1. **Scale** — languages, total symbols, total relationships
+2. **Architecture** — main communities/modules and what they do
+3. **Critical Infrastructure** — central symbols and bridge points
+4. **Execution Flows** — how the code is entered and used
+5. **API Surface** — endpoints and service dependencies
+6. **Recent Activity** — what's been changing in the last 30 days
+7. **Technical Debt** — complexity hotspots and potential dead code
+
+## Output
+
+The deliverable is the 7-part overview above. Skeleton (one headline per part):
+
+1. Scale — 2 languages, 4,812 symbols, 19,344 relationships
+2. Architecture — 12 communities; top 5: auth, indexing, api, ui, billing
+3. Critical Infrastructure — `EngineHandle::open` (central AND bridge — flag it)
+4. Execution Flows — 14 processes: 9 HTTP handlers, 3 CLI commands, 2 jobs
+5. API Surface — 42 endpoints; 2 cross-repo service dependencies
+6. Recent Activity — 31 episodes in 30d; hottest file per `top_changed_files`
+7. Technical Debt — top-10 complex functions, highest complexity first
+
+## Common mistakes
+
+| Mistake | Reality |
+|---------|---------|
+| Skipping indexing and using file-based grep | The knowledge graph provides structural understanding that grep cannot — callers, callees, communities, processes |
+| Reporting raw numbers without interpretation | "450 functions across 12 communities" means nothing; describe what each community does |
+| Only looking at code structure | Execution flows (processes) show how the code is actually used — always include them |
+| Ignoring temporal context | Recent evolution shows where active development is happening — this is where the user will likely need to work |

package/pi-package/skills/memtrace-evolution/SKILL.md

@@ -0,0 +1,158 @@
+---
+name: memtrace-evolution
+description: Trace source-code change history from Memtrace's symbol-level temporal memory. Use when the user asks about change history, recent modifications, what changed since a date, symbol timeline, evolution, unexpected changes, or incident timelines. Do not use git log, git diff, grep, or manual file search to reconstruct history. Do NOT use for current-state architecture overviews (use memtrace-codebase-exploration) or for replaying one commit/save's graph diff (use memtrace-impact for blast radius instead).
+allowed-tools: memtrace_get_evolution memtrace_get_timeline memtrace_detect_changes memtrace_list_indexed_repositories memtrace_get_changes_since memtrace_get_impact memtrace_get_cochange_context
+license: MIT
+metadata:
+  author: "Memtrace <support@syncable.dev>"
+  version: "1.0.0"
+  category: development
+---
+
+## Overview
+
+Temporal analysis for "what changed in this repo between two points in time?" Works on both git commits and uncommitted working-tree saves.
+
+## Required parameters — read before calling
+
+`memtrace_get_evolution` **always** requires `repo_id` and `from`. There is no `days` parameter.
+
+| Parameter | Required | Type | Example |
+|---|---|---|---|
+| `repo_id` | yes | string | `"my-repo"` |
+| `from` | yes | string | `"90d ago"`, `"2026-04-01T00:00:00Z"`, `"yesterday"` |
+| `to` | no | string | defaults to now; set to incident time when investigating |
+| `mode` | no | string | `"recent"` (default), `"compound"`, `"summary"`, `"overview"` |
+| `target` | no | string | symbol name or file path substring to scope results |
+| `branch` | no | string | branch filter |
+
+> **Parameter types:** MCP parameters are strictly typed. Numbers (`limit`, `cursor`, etc.) must be JSON numbers — not strings. Use `limit: 100`, never `limit: "100"`.
+
+### Time-window parameters — do not confuse these tools
+
+| Tool | Time param | Example | Notes |
+|---|---|---|---|
+| `memtrace_get_evolution` | **`from`** (required) | `"90d ago"` | optional `to`; **never** pass `days` |
+| `memtrace_get_changes_since` | **`since`** (required) | `"2026-04-13T10:43:00Z"` | optional `until` |
+
+Common failure: `MCP error -32602: missing field 'from'` — you omitted `from` or passed `days` instead.
+
+```json
+// CORRECT — 90-day overview
+{ "repo_id": "my-repo", "from": "90d ago", "mode": "overview" }
+
+// WRONG — days is not a memtrace_get_evolution parameter
+{ "repo_id": "my-repo", "days": 90, "mode": "overview" }
+```
+
+## Query modes — only these four exist
+
+| Mode | What you get | Best for |
+|---|---|---|
+| `recent` | Per-episode list with nodes/edges added/removed; paginate with `limit` + `cursor` | Incident timelines, walking commit-by-commit |
+| `compound` | Totals plus `top_changed_files` and `top_touched_symbols` | "What changed?" when you need hotspots |
+| `summary` | Totals plus `first_episode` / `last_episode` metadata | Cheapest window check |
+| `overview` | Alias for `summary` | Same as `summary` |
+
+Modes **`impact`**, **`novel`**, and **`directional`** are **not implemented** — calling them returns `unknown mode`.
+
+### `recent` mode filters (ignored by `compound` / `summary`)
+
+| Param | Purpose |
+|---|---|
+| `file_path` | substring match against episode `touched_files` |
+| `kind` | `"git_commit"` or `"working_tree"` |
+| `limit` | page size (default 100 episodes) |
+| `cursor` | pagination offset; follow `next_cursor` in response |
+
+Full parameter spec for every Memtrace tool: [`../references/mcp-parameters.md`](../references/mcp-parameters.md).
+
+## Steps
+
+### 1. Get `repo_id`
+
+```
+memtrace_list_indexed_repositories()
+```
+
+### 2. Choose the time window
+
+- `from` — start (required). Relative strings work: `"7d ago"`, `"24 hours ago"`.
+- `to` — end (optional, defaults to now). Set to the incident timestamp when investigating regressions.
+
+If resuming a session and you have a stored timestamp from last time, prefer `memtrace_get_changes_since(since=...)`.
+
+### 3. Choose the mode
+
+```
+User wants...
+├── per-commit / per-save changelog     → recent
+├── top changed files + symbols         → compound
+├── quick totals only                   → summary or overview
+└── one symbol's full history           → memtrace_get_timeline (not memtrace_get_evolution)
+```
+
+### 4. Execute
+
+```json
+// General "what changed lately?"
+{ "repo_id": "my-repo", "from": "30d ago", "mode": "compound" }
+
+// Changes in one file last week
+{ "repo_id": "my-repo", "from": "7d ago", "mode": "recent", "file_path": "auth.ts", "limit": 50 }
+
+// Incident: 24h before failure until failure time
+{ "repo_id": "my-repo", "from": "2026-04-16T13:00:00Z", "to": "2026-04-17T13:00:00Z", "mode": "recent" }
+```
+
+### 5. Interpret results
+
+**`recent` mode** — each entry in `episodes[]`:
+- `episode` — metadata (`source_type`, `reference_time`, `touched_files`, …)
+- `nodes_added`, `nodes_removed`, `edges_added`, `edges_removed`
+
+**`compound` mode:**
+- `totals` — aggregate counts
+- `top_changed_files` — files with most activity
+- `top_touched_symbols` — symbols with most activity
+
+**`summary` / `overview` mode:**
+- `totals` — episode and node/edge counts
+- `first_episode`, `last_episode` — window boundaries
+
+### 6. Drill deeper
+
+| Need | Tool |
+|---|---|
+| Full history of one symbol | `memtrace_get_timeline(repo_id, scope_path, file_path)` |
+| Blast radius of a suspect symbol | `memtrace_get_impact(repo_id, target)` — see `memtrace-impact` |
+| What a diff would affect | `memtrace_detect_changes(repo_id, diff=...)` |
+| Behavioral coupling | `memtrace_get_cochange_context(repo_id, target=<symbol>)` |
+
+## Output
+
+Sample `compound` payload (per-mode field lists: step 5 above):
+
+```json
+{
+  "totals": { "episodes": 42, "nodes_added": 310, "nodes_removed": 95,
+              "edges_added": 541, "edges_removed": 120 },
+  "top_changed_files":   [ /* files ranked by activity */ ],
+  "top_touched_symbols": [ /* symbols ranked by activity */ ]
+}
+```
+
+`recent` returns `episodes[]` + `totals` + `page.next_cursor`; `summary`/`overview` return `totals` + `first_episode`/`last_episode`.
+
+## Common mistakes
+
+| Mistake | Reality |
+|---|---|
+| Passing `days: 90` | Use `from: "90d ago"` |
+| Omitting `from` | Required — call fails with `-32602` before any query runs |
+| Using `mode: "novel"` / `"impact"` / `"directional"` | Not implemented — use `compound` + `memtrace_get_impact` + `memtrace_get_cochange_context` instead |
+| Expecting `by_module[]` or significance scores | Not in current response shape — use `top_changed_files` from `compound` |
+| Using `overview` when you need file/symbol detail | `overview`/`summary` are totals only — switch to `compound` or `recent` |
+| Using `memtrace_get_evolution` for one symbol's history | Use `memtrace_get_timeline` |
+| Guessing timestamps when resuming work | Use `memtrace_get_changes_since(since=<stored time>)` |
+| Applying `file_path` filter in `compound` mode | Filters are ignored in roll-up modes — use `recent` with `file_path` instead |

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

@@ -0,0 +1,213 @@
+---
+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, 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.
+allowed-tools: memtrace_list_indexed_repositories memtrace_index_directory memtrace_find_symbol memtrace_find_code memtrace_get_symbol_context memtrace_get_impact memtrace_analyze_relationships memtrace_get_process_flow memtrace_list_communities memtrace_find_central_symbols memtrace_find_api_endpoints memtrace_find_api_calls memtrace_get_service_diagram memtrace_get_api_topology memtrace_find_dependency_path memtrace_get_cochange_context memtrace_get_evolution memtrace_get_changes_since memtrace_get_style_fingerprint memtrace_find_most_complex_functions memtrace_get_source_window memtrace_status read grep find
+license: MIT
+metadata:
+  author: "Memtrace <support@syncable.dev>"
+  version: "1.0.0"
+  category: development
+---
+
+# Memtrace First
+
+## The Iron Law
+
+```
+IF THE REPO IS INDEXED IN MEMTRACE → USE memtrace_* TOOLS FIRST.
+After a search hit, route to GRAPH tools (memtrace_get_symbol_context,
+memtrace_get_impact, memtrace_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 Memtrace returned (start_line .. end_line + small
+context). Do not grep/find to "locate" anything already in the graph, and do
+not read the whole file when Memtrace has given you exact lines.
+```
+
+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. `read`/`grep`/`find` are blind to all of that.
+
+**No exceptions for what's in the graph.**
+
+## Before you start: check Memtrace is available
+
+Call `memtrace_status` once per session if you are unsure whether Memtrace is connected. It reports whether the `memtrace` binary is installed, whether the MCP server is connected, and which repos are indexed (with their `repo_id` values you need for every other `memtrace_*` call). If it reports `installed: false`, tell the user to run `npm install -g memtrace`, then `memtrace start`.
+
+## What Memtrace actually indexes
+
+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.
+
+The semantic side means **string literals, error messages, magic constants, log strings, and any text inside an indexed symbol's body are findable through `memtrace_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.
+
+## Zero results are not a grep license
+
+If Memtrace returns 0 results, or repository stats look incomplete, do **not** infer that a source subdirectory is outside the index. Diagnose through Memtrace:
+
+1. Call `memtrace_list_indexed_repositories` and identify the repo root/repo_id.
+2. If the path is under that indexed repo root, keep using Memtrace.
+3. Retry with broader `memtrace_find_code` terms and, when available, `file_path` filters such as `ui/`, `src/`, or the framework directory.
+4. If the language/path still appears missing, run `memtrace_index_directory` on the repo root with `incremental: true` (or ask before `clear_existing: true`).
+5. Report the indexing coverage problem instead of silently switching to grep.
+
+**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/find are still right
+
+These are the ONLY cases where file tools beat Memtrace:
+
+- **Files outside every indexed repo root.** Confirm this with `memtrace_list_indexed_repositories`; 0 search results or missing language stats do not prove it. 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, `read` is fine. For source-code spans returned by Memtrace, read the precise line range with `read(file, offset, limit)` or `memtrace_get_source_window`. 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 you're asking | Right tool |
+|---|---|
+| "Where is symbol `foo` defined?" | `memtrace_find_symbol(name="foo")` → then `memtrace_get_symbol_context` for callers/callees/community, NOT a source read unless you're editing. |
+| "What calls `foo`?" | `memtrace_get_symbol_context(repo_id, symbol="foo")` → callers with file:line. |
+| "How does authentication work?" | `memtrace_find_code(query="authentication")` → `memtrace_get_symbol_context` on the top hit, NOT a source read. |
+| "Find behavior X" with multi-word phrase (3+ words) | `memtrace_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`" | `memtrace_find_code(query="STRIPE_KEY_FOO_BAR")` → semantic finds it inside any embedded body. |
+| "Where's that error message `'connection refused for tenant'`?" | `memtrace_find_code(query="connection refused for tenant")` → semantic catches it. |
+| "What breaks if I change `foo`?" | `memtrace_get_impact(repo_id, target="foo")` → blast radius. |
+| "What changed in `auth.ts` last week?" | `memtrace_get_evolution(repo_id, from="7d ago", mode="recent", file_path="auth.ts")`. |
+| "List all `*.test.ts` files." | `find` (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, offset=start_line, limit=end_line-start_line+8)`, or `memtrace_get_source_window`. 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_*` 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"` |
+| `memtrace_get_evolution.from` | `from: "90d ago"` | `days: 90` (wrong param — use `from`, not `days`) |
+| `memtrace_get_changes_since.since` | `since: "2026-04-13T10:43:00Z"` | `last_episode_id: "..."` (wrong param) |
+| `memtrace_get_impact.target` / `memtrace_get_symbol_context.symbol` | `target: "foo"` / `symbol: "foo"` | `symbol_id: "..."` (wrong — use name) |
+| `memtrace_find_most_complex_functions` | `top_n: 10` | `limit: 10` (wrong param name) |
+| `memtrace_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 `memtrace_get_evolution` without `from` — pass e.g. `"90d ago"`, never `days`.
+
+Full parameter spec for every Memtrace tool: [`../references/mcp-parameters.md`](../references/mcp-parameters.md).
+
+## Check indexing first (once per session)
+
+```
+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 `memtrace_index_directory`, then follow this skill. (Or use `/memtrace:index`.)
+
+## Task → tool map
+
+| What you need | Use instead of grep/find/read |
+|---|---|
+| Find a function / class / symbol | `memtrace_find_symbol` or `memtrace_find_code` |
+| Understand how something works | `memtrace_get_symbol_context` (the default next step) |
+| Find all callers of a function | `memtrace_get_symbol_context` (callers field) |
+| Find all callees / dependencies | `memtrace_get_symbol_context` (callees field) |
+| Trace a request / execution path | `memtrace_get_process_flow` |
+| Understand module structure | `memtrace_list_communities` |
+| Find the most important symbols | `memtrace_find_central_symbols` |
+| Find API endpoints | `memtrace_find_api_endpoints` |
+| Find where an API is called | `memtrace_find_api_calls` |
+| Debug a problem | `memtrace_get_symbol_context` → `memtrace_get_impact` → `memtrace_get_evolution` |
+| What changed recently? | `memtrace_get_changes_since` or `memtrace_get_evolution` |
+| What breaks if I change X? | `memtrace_get_impact` |
+| Cross-service / cross-repo calls | `memtrace_get_service_diagram` or `memtrace_get_api_topology` |
+| Dependency between two symbols | `memtrace_find_dependency_path` |
+| What files change together? | `memtrace_get_cochange_context` |
+| Architecture overview | `memtrace_list_communities` + `memtrace_find_central_symbols` (see `memtrace-codebase-exploration`) |
+| About to edit / quote — need exact lines | Bounded `read(file, offset=start_line, limit=N)` (preferred), or `memtrace_get_source_window` |
+| About to choose between competing idioms (ternary vs if-else, arrow vs fn-decl, const vs let, await vs `.then`) | `memtrace_get_style_fingerprint(repo_id, file_path)` — empirical codebase norm |
+
+## Standard workflows
+
+### "How does X work?" / "Explain X"
+1. `memtrace_find_symbol` or `memtrace_find_code` → locate the symbol
+2. `memtrace_get_symbol_context` → callers, callees, community, processes (this usually answers "how it works")
+3. `memtrace_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 `memtrace_get_source_window`
+
+### Debugging "X is broken"
+1. `memtrace_find_symbol` → locate the broken thing
+2. `memtrace_get_symbol_context` → understand its role
+3. `memtrace_get_impact` → blast radius (what else breaks)
+4. `memtrace_get_evolution(from=<lookback>, mode: recent)` → per-episode changelog near the incident
+5. `memtrace_get_changes_since(since=<anchor>)` → catch-up since last session (requires stored `since` timestamp)
+
+### "Where is X defined / called?"
+1. `memtrace_find_symbol` with `fuzzy: true`
+2. `memtrace_get_symbol_context` for full caller/callee map
+3. Only if you need source text: bounded `read` at start_line..end_line, or `memtrace_get_source_window`
+
+### Before any code modification
+1. `memtrace_find_symbol` → confirm you have the right target
+2. `memtrace_get_symbol_context` → understand full context
+3. `memtrace_get_impact` → know blast radius before touching anything
+4. `memtrace_get_style_fingerprint(repo_id, file_path=<file>)` → match the codebase's empirical idiom
+
+## Red flags — STOP, use Memtrace instead
+
+You are violating this skill if you think:
+
+| Thought | Reality |
+|---|---|
+| "Let me grep for this" | `memtrace_find_code` or `memtrace_find_symbol` is faster and structurally aware |
+| "Let me find the file by name" | `memtrace_find_symbol` returns exact location with context |
+| "Let me read the whole file" | `memtrace_get_symbol_context` for the WHY (callers/callees/community); a bounded source read at start_line..end_line for the WHAT |
+| "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 `memtrace_status` or `memtrace_list_indexed_repositories` first — takes 1 second |
+| "Memtrace returned 0 results" | Broaden the Memtrace query, check repo_id/path coverage, then reindex if needed |
+| "Stats only show one language, but I need another directory" | 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 `memtrace_find_symbol` vs 20 file reads |
+
+## When file tools are still correct
+
+Use `grep`/`find`/`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
+
+For source-code spans already located by Memtrace, use a **bounded** `read(file, offset, limit)` with the returned `start_line`/`end_line`, or `memtrace_get_source_window`. 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 task.
+
+When this skill applies, it overrides default file-search behavior. Companion skills installed alongside this one by `memtrace install`:
+
+- Architecture overview → `memtrace-codebase-exploration`
+- Temporal / change analysis → `memtrace-evolution`
+- Impact analysis → `memtrace-impact`
+- Search, quality, refactoring, decision memory, fleet coordination, etc. → other `memtrace-*` skills in `~/.pi/agent/skills/`
+
+## Output
+
+`memtrace_find_symbol` / `memtrace_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 }
+```
+
+`memtrace_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 `memtrace_get_source_window` — never a whole-file read.
+
+## Success criteria
+
+- The answer is grounded in Memtrace graph results (search hit → `memtrace_get_symbol_context` / `memtrace_get_impact`), not file-tool discovery.
+- `grep`/`find`/`read` appear only via the documented narrow exceptions (non-source artifacts, paths outside every indexed root, file inventory, bounded span reads).
+- Zero-result queries were diagnosed (`memtrace_list_indexed_repositories` → broaden → reindex), not bypassed to grep.
+- Any source read was bounded to the span Memtrace returned.

package/pi-package/skills/memtrace-impact/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: memtrace-impact
+description: Compute the blast radius of modifying a symbol through transitive graph impact. Use when the user asks about blast radius, impact, what breaks, risk, upstream callers, downstream dependencies, or consequences of modifying a symbol, before or during source-code changes. Do not use grep or manual reference search; Memtrace computes transitive graph impact.
+allowed-tools: memtrace_get_impact memtrace_detect_changes memtrace_find_symbol memtrace_find_code
+license: MIT
+metadata:
+  author: "Memtrace <support@syncable.dev>"
+  version: "1.0.0"
+  category: development
+---
+
+## Overview
+
+Compute the blast radius of changing a specific symbol. Traces upstream (what depends on this) and downstream (what this depends on) through the knowledge graph to quantify risk before making modifications.
+
+## Quick reference
+
+| Tool | Purpose |
+|------|---------|
+| `memtrace_get_impact` | Blast radius from a symbol **name** (`target`) |
+| `memtrace_detect_changes` | Scope symbols affected by a diff/patch |
+
+> **Parameter types:** MCP parameters are strictly typed. Numbers (`depth`, `limit`, etc.) must be JSON numbers — not strings.
+
+## Required parameters — `memtrace_get_impact`
+
+| Parameter | Required | Default | Notes |
+|---|---|---|---|
+| `repo_id` | yes | — | |
+| `target` | yes | — | Symbol name (e.g. `"validateToken"`) — **not** `symbol_id` |
+| `direction` | no | `"both"` | `"upstream"` \| `"downstream"` \| `"both"` |
+| `depth` | no | `5` | BFS depth (max 15) |
+| `as_of` | no | now | ISO-8601 for time-travel |
+
+```json
+{ "repo_id": "my-repo", "target": "validateToken", "direction": "both", "depth": 5 }
+```
+
+Full parameter spec for every Memtrace tool: [`../references/mcp-parameters.md`](../references/mcp-parameters.md).
+
+## Steps
+
+### 1. Identify the symbol name
+
+If you don't know the exact name:
+- `memtrace_find_symbol(name="...")` for exact identifiers
+- `memtrace_find_code(query="...")` for natural-language queries
+
+Use the returned **`name`** (and optional `file_path` hint) — graph tools resolve by name, not internal IDs.
+
+### 2. Run impact analysis
+
+```json
+{
+  "repo_id": "my-repo",
+  "target": "validateToken",
+  "direction": "upstream",
+  "depth": 5
+}
+```
+
+### 3. Interpret the risk rating
+
+| Risk | Meaning | Action |
+|------|---------|--------|
+| **Low** | Few dependents, leaf node | Safe to modify; minimal testing needed |
+| **Medium** | Moderate dependents | Test direct callers; review interface contracts |
+| **High** | Many dependents across modules | Coordinate changes; comprehensive test coverage |
+| **Critical** | Core infrastructure, many transitive dependents | Plan migration strategy; backward-compatible changes |
+
+### 4. For diff-based analysis
+
+When you have an actual code diff, use `memtrace_detect_changes`:
+
+```json
+{ "repo_id": "my-repo", "diff": "<unified git diff text>" }
+```
+
+Or pass `changed_files: ["path/a.rs", "path/b.ts"]` when no diff text is available.
+
+## Decision points
+
+| Situation | Action |
+|-----------|--------|
+| Changing a single function | `memtrace_get_impact` with `direction: "both"` |
+| Reviewing a PR or diff | `memtrace_detect_changes` with the diff content |
+| Renaming/removing a public API | `memtrace_get_impact` with `direction: "upstream"`, higher `depth` |
+| Refactoring internals | `memtrace_get_impact` with `direction: "downstream"` |
+
+## Output
+
+`memtrace_get_impact` returns the blast radius for the target symbol:
+
+| Field | Example / meaning |
+|---|---|
+| Risk rating | `High` — one of `Low` / `Medium` / `High` / `Critical` (interpret via step 3) |
+| Upstream | Transitive dependents (callers/importers) within `depth` hops — what breaks if the target changes |
+| Downstream | Transitive dependencies — what the target relies on |
+
+`memtrace_detect_changes` returns the set of symbols affected by the supplied `diff` / `changed_files`, plus the affected processes (execution flows).
+
+## Common mistakes
+
+| Mistake | Reality |
+|---------|---------|
+| Passing `symbol_id` or `name` | Required param is **`target`** |
+| Omitting `repo_id` | Both `repo_id` and `target` are required |
+| Defaulting `depth` to 3 | API default is **5** |