memtrace-skills 0.7.25 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memtrace-skills",
-  "version": "0.7.25",
+  "version": "0.8.0",
   "description": "Memtrace skills for AI coding agents — codebase exploration, temporal evolution, impact analysis, and more.",
   "type": "module",
   "bin": {

package/plugins/memtrace-skills/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "memtrace-skills",
-  "description": "Memtrace skills for codebase exploration, code search, relationship analysis, temporal evolution, blast radius impact, code quality, graph algorithms, API topology, GitHub PR code review, multi-agent fleet coordination (branch-scoped intents, conflict classification, and agent-judged Class C resolution), and multi-step workflows for change impact, incident investigation, refactoring, session continuity, co-change analysis, and episode replay.",
-  "version": "0.7.25",
+  "description": "Memtrace skills for codebase exploration, code search, relationship analysis, temporal evolution, blast radius impact, code quality, graph algorithms, API topology, GitHub PR code review, multi-agent fleet coordination (branch-scoped intents, conflict classification, and agent-judged Class C resolution), and multi-step workflows for change impact, incident investigation, refactoring, session continuity, co-change analysis, and episode replay, Cortex decision memory (decision recall, provenance, intent verification), session bookends (daily briefing, hotspots, self-audit), and single-symbol pre-edit preflight checks.",
+  "version": "0.8.0",
   "author": {
     "name": "Syncable",
     "email": "support@syncable.dev"

package/plugins/memtrace-skills/references/mcp-parameters.md

@@ -35,8 +35,8 @@ arrays as arrays. No quoting numbers, no `"true"` for booleans.
 | `branch` *or* `branch_name` | string | Git branch. Default `"main"` across every tool. Both spellings occur historically — use whichever the specific tool's schema says |
 | `limit` | integer | Cap on returned results. Always a JSON number, never a string |
 | `depth` | integer | Graph traversal hops. 1–5 is reasonable; >8 explodes on wide graphs |
-| `symbol_id` | string (UUID) | Node UUID from `find_symbol` / `find_code` results |
-| `from` / `to` / `incident_time` | string (ISO-8601 with timezone) | e.g. `"2026-04-17T13:00:00Z"` — NOT a date like `"2026-04-17"` |
+| `target` / `symbol` | string | Symbol **name** for graph tools — `get_impact`/`analyze_relationships` use `target`; `get_symbol_context` uses `symbol` |
+| `from` / `to` / `since` / `until` | string | e.g. `"90d ago"`, `"2026-04-17T13:00:00Z"`, `"yesterday"` — relative strings work for temporal tools. **Never `days` on `get_evolution`.** |
 
 ## Search & discovery
 
@@ -45,16 +45,18 @@ arrays as arrays. No quoting numbers, no `"true"` for booleans.
 |---|---|---|---|---|
 | `query` | string | yes | — | Natural-language text |
 | `repo_id` | string | no | all repos | Scope to one repo |
-| `kind` | string | no | — | One of `Function`, `Class`, `Method`, `Interface`, `APIEndpoint`, `APICall` |
 | `file_path` | string | no | — | Path substring filter |
-| `limit` | integer | no | `20` | Capped at `100` |
-| `as_of` | string (ISO-8601) | no | now | Time-travel search |
+| `limit` | integer | no | `20` | Max 100 |
+| `as_of` | string | no | now | Time-travel search |
+| `include_diagnostics` | boolean | no | `false` | Include `id`, `score` in results |
+
+No `kind` param — use `find_symbol(kind=...)` instead.
 
 ### `find_symbol`
 | Field | Type | Required | Default | Notes |
 |---|---|---|---|---|
 | `name` | string | yes | — | Exact or partial identifier |
-| `fuzzy` | boolean | no | `false` | Levenshtein tolerance |
+| `fuzzy` | boolean | no | `false` | Exact-match today; field kept for API parity |
 | `edit_distance` | integer | no | `2` | Max 2. Only used when `fuzzy: true` |
 | `repo_id` | string | no | all repos | |
 | `kind` | string | no | — | Same enum as `find_code` |
@@ -80,27 +82,34 @@ No parameters. Call once at session start to get `repo_id` values.
 ### `get_symbol_context`
 | Field | Type | Required | Default |
 |---|---|---|---|
-| `symbol_id` | string (UUID) | yes | — |
+| `repo_id` | string | yes | — |
+| `symbol` | string | yes | — |
+| `file_path` | string | no | — |
+| `branch` | string | no | `"main"` |
+| `as_of` | string | no | now |
+| `view` | string | no | `"live"` |
 
 Returns: symbol, callers, callees, type_references, community, processes, api_callers_cross_repo.
 
 ### `analyze_relationships`
 | Field | Type | Required | Default | Notes |
 |---|---|---|---|---|
-| `symbol_id` | string (UUID) | yes | — | |
+| `repo_id` | string | yes | — | |
+| `target` | string | yes | — | Symbol name |
 | `query_type` | string enum | yes | — | `find_callers` \| `find_callees` \| `class_hierarchy` \| `overrides` \| `imports` \| `exporters` \| `type_usages` |
-| `depth` | integer | no | `2` | |
-| `limit` | integer | no | `50` | |
+| `depth` | integer | no | `3` | Max 10 |
+| `file_path` | string | no | — | Disambiguation hint |
 
 ## Impact
 
 ### `get_impact`
 | Field | Type | Required | Default | Notes |
 |---|---|---|---|---|
-| `symbol_id` | string (UUID) | yes | — | |
+| `repo_id` | string | yes | — | |
+| `target` | string | yes | — | Symbol name |
 | `direction` | string enum | no | `"both"` | `"upstream"` \| `"downstream"` \| `"both"` |
-| `depth` | integer | no | `3` | |
-| `limit` | integer | no | `100` | |
+| `depth` | integer | no | `5` | Max 15 |
+| `as_of` | string | no | now | |
 
 ### `detect_changes`
 | Field | Type | Required | Default | Notes |
@@ -118,13 +127,22 @@ Returns: symbol, callers, callees, type_references, community, processes, api_ca
 | Field | Type | Required | Default | Notes |
 |---|---|---|---|---|
 | `repo_id` | string | yes | — | |
-| `from` | string (ISO-8601) | yes | — | Start of window |
-| `to` | string (ISO-8601) | yes | — | End of window |
-| `mode` | string enum | no | `"compound"` | `"compound"` \| `"impact"` \| `"novel"` \| `"recent"` \| `"directional"` \| `"overview"` |
-| `incident_time` | string (ISO-8601) | no | — | Reference for `recent` mode |
-| `branch` | string | no | `"main"` | |
-| `max_symbols` | integer | no | `50` | Per category |
-| `scope` | string | no | — | File / module prefix |
+| `from` | string | yes | — | Start of window. RFC3339, ISO date, epoch, or relative (`"7d ago"`, `"yesterday"`). **Never pass `days`.** |
+| `to` | string | no | now | End of window |
+| `mode` | string enum | no | `"recent"` | `"recent"` \| `"compound"` \| `"summary"` \| `"overview"` (alias for `summary`) |
+| `target` | string | no | — | Symbol name or file path substring scope |
+| `branch` | string | no | any branch | |
+| `file_path` | string | no | — | **`recent` mode only** — substring match on `touched_files` |
+| `kind` | string | no | — | **`recent` mode only** — `"git_commit"` or `"working_tree"` |
+| `limit` | integer | no | `100` | **`recent` mode only** — page size; `0` = server cap |
+| `cursor` | integer | no | `0` | **`recent` mode only** — pagination offset |
+
+**Response by mode:**
+- `recent` → `episodes[]`, `totals`, `page` (with `next_cursor`)
+- `compound` → `totals`, `top_changed_files`, `top_touched_symbols`
+- `summary` / `overview` → `totals`, `first_episode`, `last_episode`
+
+Modes **`impact`**, **`novel`**, **`directional`** are **not implemented**.
 
 ### `get_timeline`
 | Field | Type | Required | Default | Notes |
@@ -137,30 +155,41 @@ Returns: symbol, callers, callees, type_references, community, processes, api_ca
 ### `get_episode_replay`
 | Field | Type | Required | Default | Notes |
 |---|---|---|---|---|
-| `repo_id` | string | yes | — | |
-| `symbol` | string | yes | — | Symbol name, e.g. `"validateToken"` |
-| `from` | string (ISO-8601) | yes | — | Window start |
-| `to` | string (ISO-8601) | yes | — | Window end |
-| `branch` | string | no | `"main"` | |
-| `include_working_tree` | boolean | no | `true` | Include uncommitted file-save episodes |
+| `episode_id` | string | † | — | Episode UUID — preferred when known |
+| `repo_id` | string | † | — | Required with `episode_index` when `episode_id` omitted |
+| `episode_index` | integer | † | — | 0 = newest episode |
+| `branch` | string | no | any branch | Used with `episode_index` |
+| `symbol` | string | no | — | Optional filter — scope to one symbol |
+| `kind` | string | no | — | e.g. `Function`, `CALLS` — narrow large commits |
+| `file_path` | string | no | — | Substring filter on record paths |
+| `limit` | integer | no | `200` | Page size per bucket; `0` = no pagination |
+| `cursor` | integer | no | `0` | Pagination offset |
+| `mode` | string | no | default | `"graph_summary"` for digest on large commits |
+| `compress` | boolean | no | `true` | Collapse identical-hash modifications |
+
+† Supply `episode_id`, OR `repo_id` + `episode_index`.
 
 ### `get_changes_since`
 | Field | Type | Required | Default | Notes |
 |---|---|---|---|---|
 | `repo_id` | string | yes | — | |
-| `last_episode_id` | string | no † | — | Preferred anchor from previous response |
-| `last_reference_time` | string (ISO-8601) | no † | — | Fallback when no episode ID |
-| `branch` | string | no | `"main"` | |
+| `since` | string | yes | — | Cutoff timestamp. Same formats as `get_evolution.from`. **Not** `last_episode_id`. |
+| `until` | string | no | now | Optional upper bound |
+| `branch` | string | no | any branch | |
 
-† Pass exactly one.
+Returns `episodes[]` with per-episode change counts and `totals`. Store `until` (or latest episode `reference_time`) as the next session's `since` value.
 
 ### `get_cochange_context`
 | Field | Type | Required | Default | Notes |
 |---|---|---|---|---|
 | `repo_id` | string | yes | — | |
-| `symbol` | string | yes | — | Symbol name (not ID) |
-| `branch` | string | no | `"main"` | |
-| `limit` | integer | no | `20` | |
+| `target` | string | yes | — | Symbol name or file path |
+| `window_days` | integer | no | `30` | Lookback from `as_of` |
+| `as_of` | string | no | now | Window anchor |
+| `branch` | string | no | any branch | |
+| `limit` | integer | no | `10` | Max cochanged files returned |
+
+Returns `cochanged_files[]` with `file_path`, `cochange_count`, `last_cochanged_at`.
 
 ## Graph algorithms
 
@@ -168,9 +197,9 @@ Returns: symbol, callers, callees, type_references, community, processes, api_ca
 | Field | Type | Required | Default | Notes |
 |---|---|---|---|---|
 | `repo_id` | string | yes | — | |
-| `branch` | string | no | `"main"` | |
-| `algorithm` | string enum | no | `"pagerank"` | `"pagerank"` \| `"degree"` — falls back to degree if MAGE unavailable |
-| `limit` | integer | no | `20` | Max 100 |
+| `branch` | string | no | any branch | |
+| `kinds` | array of string | no | Function/Method/Class/… | |
+| `limit` | integer | no | `25` | Max 100. Always PageRank — no `method` param. |
 
 ### `find_bridge_symbols`
 | Field | Type | Required | Default | Notes |
@@ -204,10 +233,11 @@ Returns: symbol, callers, callees, type_references, community, processes, api_ca
 ### `find_dependency_path`
 | Field | Type | Required | Default | Notes |
 |---|---|---|---|---|
-| `repo_id` | string | yes | — | — |
-| `from` | string | yes | — | Source symbol name |
-| `to` | string | yes | — | Destination symbol name |
-| `max_depth` | integer | no | `8` | BFS hop limit |
+| `repo_id` | string | yes | — | |
+| `source` | string | yes | — | Start symbol name |
+| `target` | string | yes | — | End symbol name |
+| `max_depth` | integer | no | `20` | Max 20 |
+| `edge_type` | string | no | calls+refs+… | Comma-separated or alias |
 
 ## Quality
 
@@ -231,13 +261,14 @@ Returns: symbol, callers, callees, type_references, community, processes, api_ca
 |---|---|---|---|
 | `repo_id` | string | yes | — |
 | `branch` | string | no | `"main"` |
-| `limit` | integer | no | `10` |
-| `min_complexity` | integer | no | `0` |
+| `top_n` | integer | no | `20` |
+| `kinds` | array of string | no | Function+Method |
 
 ### `calculate_cyclomatic_complexity`
 | Field | Type | Required | Default |
 |---|---|---|---|
-| `symbol_id` | string (UUID) | yes | — |
+| `repo_id` | string | yes | — |
+| `target` | string | yes | — |
 
 ## API topology
 
@@ -291,12 +322,82 @@ Connects already-indexed repos so `get_api_topology` can stitch their HTTP graph
 |---|---|---|---|
 | `repo_id` | string | yes | — |
 
-### `watch_directory` / `unwatch_directory` / `list_watched_paths`
-File watcher control. See the tool schema via `list_tools` for current fields.
+### `watch_directory`
+| Field | Type | Required | Default |
+|---|---|---|---|
+| `path` | string | yes | — |
+| `repo_id` | string | yes | — |
+| `branch` | string | no | `"main"` |
+
+### `unwatch_directory`
+| Field | Type | Required |
+|---|---|---|
+| `path` | string | yes |
+
+### `list_watched_paths`
+No parameters. Returns `{ watches: [{ path, repo_id, branch, started_at, origin }], count }`.
+
+### `replay_history`
+| Field | Type | Required | Default |
+|---|---|---|---|
+| `repo_id` | string | yes | — |
+| `days` | integer | no | all history |
+
+## Session bookends & pre-edit checks
+
+### `get_daily_briefing`
+| Field | Type | Required | Default | Notes |
+|---|---|---|---|---|
+| `repo_id` | string | yes | — | |
+| `window_hours` | integer | no | `24` | Clamped to 1–336 (14 days) |
+
+### `review_agent_sessions`
+| Field | Type | Required | Default | Notes |
+|---|---|---|---|---|
+| `repo_id` | string | yes | — | |
+| `window_hours` | integer | no | `24` | Clamped to 1–336. Saves >30 min apart split into separate sessions |
+
+### `find_hotspots`
+| Field | Type | Required | Default | Notes |
+|---|---|---|---|---|
+| `repo_id` | string | yes | — | |
+| `window_days` | integer | no | `14` | Kept inside the engine's 15-day hot-history horizon; deeper windows trigger a full-store scan |
+| `top_n` | integer | no | `20` | Max rows |
+
+### `preflight_check`
+| Field | Type | Required | Default |
+|---|---|---|---|
+| `repo_id` | string | yes | — |
+| `symbol` | string | yes | — |
+
+## Cortex decision memory
+
+Proxied to memcortex-serve; available when the Cortex store is enabled. Ids are
+**JSON numbers** (Cortex node ids), not strings — `decision_id: 1`, never `"1"`.
+An unknown or empty query/id returns an explicit **CannotProve**, never a
+fabricated result.
+
+### `recall_decision`
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `query` | string | yes | Free text; drives the lexical lane, decisions ranked first |
+
+(A tier-based decision cap is applied server-side; it is not a caller parameter.)
+
+### `get_arc` / `verify_intent`
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `decision_id` | integer | yes | The `id` of a `kind: "decision"` hit from `recall_decision` |
+
+### `why_is_this_here` / `governing_contracts`
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `symbol_id` | integer | yes | Cortex symbol node id |
 
 ## When this file is wrong
 
 It's drift-prone. Regenerate by grepping `crates/memtrace-mcp/src/tools/*.rs`
-for `^pub struct.*Params` — the Rust declarations are the source of truth.
+for `^pub struct.*Params` — the Rust declarations are the source of truth
+(Cortex decision tools: `MemCortex/crates/memcortex-mcp/src/request.rs`).
 If a live tool call rejects with `-32602`, trust the Rust struct over this
 doc and file a fix PR.

package/plugins/memtrace-skills/skills/memtrace-api-topology/SKILL.md

@@ -1,58 +1,51 @@
 ---
 name: memtrace-api-topology
-description: "Always use for API endpoint, HTTP route, fetch/client call, REST surface, service dependency, cross-repo dependency, or API topology questions in source code. Do not use Grep, Glob, rg, find, or manual file search for routes or HTTP calls; Memtrace maps endpoints and call edges from the indexed AST graph."
+description: "Map API endpoints, outbound HTTP calls, and cross-repo service topology in indexed source code. Use when the user asks about API endpoints, HTTP routes, fetch/client calls, REST surface, service dependencies, cross-repo dependencies, or API topology. Do not use Grep, Glob, rg, find, or manual file search for routes or HTTP calls; Memtrace maps endpoints and call edges from the indexed AST graph."
 ---
 
 ## Overview
 
-Map the HTTP API surface of a codebase — exposed endpoints, outbound HTTP calls, and cross-repo service-to-service dependency graphs. Supports auto-detection for Express, Encore, NestJS, Axum, FastAPI, Flask, Gin, Spring Boot, and more.
+Map HTTP API surface — endpoints, outbound calls, cross-repo topology.
 
 ## Quick Reference
 
-| Tool | Purpose |
-|------|---------|
-| `find_api_endpoints` | All exposed HTTP endpoints (GET /users, POST /orders, etc.) |
-| `find_api_calls` | All outbound HTTP calls (fetch, axios, reqwest, etc.) |
-| `get_api_topology` | Cross-repo call graph: which service calls which endpoint |
-| `link_repositories` | Manually link repos for cross-repo edge detection |
-
-> **Parameter types:** MCP parameters are strictly typed. Numbers (`limit`, `depth`, `min_size`, `last_n`, etc.) must be JSON numbers — not strings. Use `limit: 20`, never `limit: "20"`. Passing a string yields `MCP error -32602: invalid type: string, expected usize`.
+| Tool | Required | Key optional |
+|------|----------|--------------|
+| `find_api_endpoints` | `repo_id` | `method`, `path_contains`, `limit`, `branch` |
+| `find_api_calls` | `repo_id` | `method`, `path_contains`, `limit`, `branch` |
+| `get_api_topology` | — | `repo_id`, `min_confidence`, `include_external` |
 
+Full parameter spec for every Memtrace tool: `references/mcp-parameters.md` (bundled at the memtrace-skills plugin root).
 
 ## Steps
 
-### 1. Discover endpoints
-
-Use `find_api_endpoints`:
-- `repo_id` — required
-- Returns: method, path, handler function, framework detected
-
-### 2. Discover outbound calls
+### 1–3. Endpoints, calls, topology
 
-Use `find_api_calls`:
-- `repo_id` — required
-- Returns: target URL/path, HTTP method, calling function, library used (fetch, axios, reqwest, etc.)
+```json
+{ "repo_id": "memdb" }
+{ "repo_id": "memdb", "method": "GET", "path_contains": "/users" }
+{ "min_confidence": 0.7 }
+```
 
-### 3. Map service topology
+### 4. Deep-dive an endpoint handler
 
-Use `get_api_topology` to see the cross-repo HTTP call graph:
-- Which services call which endpoints
-- Confidence scores for each detected link
-- Service-to-service dependency direction
+Use handler **symbol name** — not symbol ID:
 
-**Prerequisite:** Multiple repos must be indexed. If cross-repo links aren't appearing, use `link_repositories` to explicitly connect them.
+```json
+{ "repo_id": "memdb", "symbol": "handleGetUsers" }
+```
 
-### 4. Deep-dive into an endpoint
+## Output
 
-For any specific endpoint, use `get_symbol_context` with the endpoint's symbol ID to see:
-- Which internal functions handle the request
-- Which processes (execution flows) include this endpoint
-- Which external services call this endpoint
+| Result | Carries |
+|--------|---------|
+| Endpoint entry (`find_api_endpoints`) | HTTP method, route path, handler symbol name (feed to `get_symbol_context` as `symbol`) |
+| Call entry (`find_api_calls`) | HTTP method, target path, calling symbol |
+| Topology edge (`get_api_topology`) | caller repo → handler repo, confidence 0.0–1.0 (edges below `min_confidence` dropped) |
 
 ## Common Mistakes
 
 | Mistake | Reality |
 |---------|---------|
-| Expecting cross-repo links with only one repo indexed | Index ALL related services first; cross-repo HTTP edges are linked automatically after indexing |
-| Missing endpoints from custom frameworks | Memtrace auto-detects major frameworks; for custom routers, the endpoints may appear as regular functions |
-| Not using `link_repositories` | If auto-linking missed a connection, use this to manually establish cross-repo edges |
+| `get_symbol_context(symbol_id=...)` | Use **`symbol`** (name) + `repo_id` |
+| Cross-repo links with one repo indexed | Index all services; use `link_repositories` if needed |

package/plugins/memtrace-skills/skills/memtrace-change-impact-analysis/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: memtrace-change-impact-analysis
-description: "Always use before source-code edits, refactors, API changes, renames, removals, PR reviews, or risk assessments when the user needs to know what will break. Do not manually grep references or browse files for impact; this workflow uses Memtrace graph context, impact, and change detection."
+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."
 ---
 
 ## Overview
@@ -15,11 +15,11 @@ Find the target symbol(s):
 - Use `find_symbol` if the user named specific functions/classes
 - Use `find_code` if the user described behaviour ("the authentication middleware")
 
-Collect symbol IDs for all targets.
+Collect symbol **names** (`name`, `scope_path`, `file_path`) for all targets — graph tools use names, not internal IDs.
 
 ### 2. Get 360° context for each target
 
-For each symbol, call `get_symbol_context`:
+For each symbol, call `get_symbol_context` (`repo_id`, `symbol`, `file_path`):
 - Direct callers and callees
 - Community membership (which module is this in?)
 - Process membership (which execution flows does this participate in?)
@@ -29,7 +29,7 @@ For each symbol, call `get_symbol_context`:
 
 ### 3. Compute blast radius
 
-For each target, call `get_impact` with `direction: both`:
+For each target, call `get_impact` (`repo_id`, `target`) with `direction: "both"`, `depth: 5`:
 - Upstream impact: what depends on this symbol
 - Downstream impact: what this symbol depends on
 - Risk rating: Low / Medium / High / Critical
@@ -44,13 +44,16 @@ For each target, call `get_impact` with `direction: both`:
 
 ### 4. Check temporal stability
 
-Call `get_evolution` with mode `novel` for a 30-day window on the repo:
-- Are any of the target symbols flagged as "rarely changing"? If so, this change is structurally surprising and deserves extra scrutiny.
-- Have the target symbols been changing frequently? High churn + high impact = volatile hotspot.
+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
 
-From step 2, you already know which processes are affected. For critical changes, use `analyze_relationships` with `query_type: find_callers` at `depth: 3` to trace the full transitive caller chain.
+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
 
@@ -60,7 +63,7 @@ Synthesize into a change plan:
 2. **Blast Radius** — number of direct/transitive dependents, risk rating
 3. **Affected Processes** — which execution flows will be impacted
 4. **Cross-Service Impact** — any external callers or consumers
-5. **Stability Signal** — is this code stable (novel) or volatile (frequent changes)?
+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
 
@@ -70,6 +73,20 @@ Synthesize into a change plan:
 |-----------|--------|
 | Risk = Critical | Recommend backward-compatible change + deprecation path |
 | Cross-repo callers exist | Flag as requiring multi-service coordination |
-| Symbol has high novelty score | Extra review — this rarely changes; make sure the change is intentional |
+| 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 |
+
+## Output
+
+The workflow's artifact is the step-6 risk-rated change plan. Compact example:
+
+```text
+Target: AuthService::validateToken (src/auth/service.ts)
+Blast Radius: 4 direct / 23 transitive dependents — Risk: High
+Affected Processes: login-flow, session-refresh
+Cross-Service Impact: 2 cross-repo API callers — needs multi-service coordination
+Stability Signal: appears in top_touched_symbols (volatile hotspot)
+Recommended Approach: incremental migration behind a feature flag
+Test Coverage: all 4 direct callers + both affected processes
+```

package/plugins/memtrace-skills/skills/memtrace-cochange/SKILL.md

@@ -1,61 +1,83 @@
 ---
 name: memtrace-cochange
-description: "Always use for historical coupling, co-change, what changes with this, hidden dependency, or what else needs to move questions for source code. Do not use git log, git diff, Grep, or manual file search to correlate changes; Memtrace queries co-change and temporal graph data directly."
+description: "Find files that historically co-change with a target symbol or file, ranked by co-occurrence across git episodes. Use when the user asks about historical coupling, co-change, what changes with this, hidden dependencies, or what else needs to move for source code. Do not use git log, git diff, Grep, or manual file search to correlate changes; Memtrace queries co-change and temporal graph data directly."
 ---
 
 ## Overview
 
-Find symbols that historically co-change with a target symbol — ranked by co-occurrence frequency across all episodes. This surfaces **behavioral coupling** that the static call graph cannot see.
+Find **files** that historically co-change with a target symbol or file path — ranked by co-occurrence frequency across git episodes. Surfaces **behavioral coupling** the static call graph cannot see.
 
 `get_impact` answers "who calls this?" (structural).
-`get_cochange_context` answers "what always moves when this moves?" (historical).
-
-They are complementary. A symbol with no direct callers can still have strong cochange partners if it's always modified alongside another in every commit.
+`get_cochange_context` answers "what files always move when this moves?" (historical, file-level).
+
+They are complementary. A file with no call-graph edges to the target can still be a strong cochange partner if it's always modified alongside it in every commit.
+
+> **Parameter types:** Numbers (`limit`, `window_days`, etc.) must be JSON numbers — not strings.
+
+## Required parameters
+
+| Parameter | Required | Default | Notes |
+|---|---|---|---|
+| `repo_id` | yes | — | |
+| `target` | yes | — | Symbol name **or** file path substring — **not** `symbol` |
+| `limit` | no | **10** | Max cochanged files returned |
+| `window_days` | no | **30** | Lookback from `as_of` |
+| `as_of` | no | now | Window anchor |
+| `branch` | no | any branch | |
+
+```json
+{
+  "repo_id": "memdb",
+  "target": "execute",
+  "limit": 10,
+  "window_days": 30
+}
+```
 
-> **Parameter types:** MCP parameters are strictly typed. Numbers (`limit`, `depth`, `min_size`, `last_n`, etc.) must be JSON numbers — not strings. Use `limit: 20`, never `limit: "20"`. Passing a string yields `MCP error -32602: invalid type: string, expected usize`.
+Full parameter spec for every Memtrace tool: `references/mcp-parameters.md` (bundled at the memtrace-skills plugin root).
+
+## Output
+
+```json
+{
+  "cochanged_files": [
+    {
+      "file_path": "src/order/types.rs",
+      "cochange_count": 8,
+      "last_cochanged_at": "2026-04-13T10:43:00Z"
+    }
+  ],
+  "target_files": ["src/order/service.rs"]
+}
+```
 
+There is **no** `cochanges[]` with symbol names — results are **file-level**.
 
 ## Steps
 
-### 1. Identify the target symbol
+### 1. Identify the target
 
-Use `find_symbol` if you need the exact name. The tool matches by `name` field.
+Use `find_symbol` if needed. Pass the symbol **`name`** or a **`file_path`** as `target`.
 
 ### 2. Call `get_cochange_context`
 
-```
-get_cochange_context(
-  repo_id: "...",
-  symbol: "execute",    // exact symbol name
-  limit: 20             // default 20, increase for broader view
-)
-```
+See required parameters above.
 
 ### 3. Interpret results
 
-The response contains `cochanges[]`, each with:
-- `name` — symbol name
-- `kind` — Function / Method / Class / Struct
-- `file_path` — where it lives
-- `cochange_count` — how many episodes it shared with the target
-
-```
-High cochange_count = strong historical coupling
-→ If you modify the target, you will likely need to touch this too
-→ Or it may be the real root cause you should investigate first
-```
+High `cochange_count` on a file → strong historical coupling. When you modify the target, review those files too — even without direct call-graph edges.
 
 ### 4. Cross-reference with call graph
 
-For the top cochange partners, optionally run `get_impact` to see if the coupling is also structural:
+For symbols in cochanged files, optionally run `get_impact(target=...)`:
 
 | Structural coupling | Historical coupling | Interpretation |
 |---|---|---|
-| Yes | Yes | Core architectural dependency — highest risk |
-| No | Yes | Hidden coupling — only visible through history |
-| Yes | No | Called frequently but changed independently — lower risk |
+| Yes | Yes | Core dependency — highest risk |
+| No | Yes | Hidden coupling — history-only |
+| Yes | No | Called often but changed independently |
 
-## When to Use
+## Use Cases
 
 - **Before modifying a symbol** — get blast awareness beyond what `get_impact` shows
 - **Incident investigation** — when `get_impact` doesn't explain the blast radius, check cochange history
@@ -67,5 +89,9 @@ For the top cochange partners, optionally run `get_impact` to see if the couplin
 | Mistake | Reality |
 |---------|---------|
 | Only using `get_impact` for blast radius | Structural coupling misses behavioral coupling — always pair with cochange |
-| Ignoring low-`in_degree` cochange partners | A rarely-called utility with high cochange_count is a strong coupling signal |
-| Using cochange as a dependency map | It's not a dependency graph — it's a change correlation. Two symbols can cochange without any direct relationship. |
+| Ignoring cochanged files with no call-graph edges | A rarely-called file with high `cochange_count` is a strong coupling signal |
+| Using cochange as a dependency map | It's a change correlation, not a dependency graph — files can cochange without any direct relationship |
+| Passing `symbol:` | Required param is **`target`** |
+| Expecting `cochanges[]` with symbol names | Response is **`cochanged_files[]`** (file paths) |
+| Using `limit: 20` as default | API default is **10** |
+| Empty results with 0 git episodes | Run `replay_history` during indexing to populate co-change data |