memtrace-skills 0.7.10

package/skills/workflows/memtrace-incident-investigation.md

@@ -0,0 +1,125 @@
+---
+name: memtrace-incident-investigation
+description: "Always use for source-code bugs, incidents, regressions, production issues, failures, root cause analysis, what broke, or what changed when debugging. Do not start with Grep, Glob, rg, find, or manual file search for code causes; Memtrace combines symbol search, impact, call graph, and temporal history."
+allowed-tools:
+  - mcp__memtrace__get_evolution
+  - mcp__memtrace__get_timeline
+  - mcp__memtrace__detect_changes
+  - mcp__memtrace__get_impact
+  - mcp__memtrace__get_symbol_context
+  - mcp__memtrace__find_code
+  - mcp__memtrace__find_symbol
+  - mcp__memtrace__analyze_relationships
+  - mcp__memtrace__list_indexed_repositories
+  - mcp__memtrace__get_cochange_context
+  - mcp__memtrace__get_episode_replay
+user-invocable: true
+---
+
+## Overview
+
+Root cause investigation workflow for incidents, regressions, and production issues. Uses temporal analysis with the `recent` scoring mode to surface changes closest to the incident time, then traces blast radius and execution flows to identify the likely cause.
+
+## Steps
+
+### 1. Establish the timeline
+
+Determine:
+- **Incident time** — when did the problem start? (This becomes the `to` parameter)
+- **Lookback window** — how far back to search? Start with 24 hours, expand if needed.
+- **Repo(s)** — which services are affected? Call `list_indexed_repositories` to get repo_ids.
+
+### 2. Surface recent changes near the incident
+
+Call `get_evolution` with:
+- `mode: "recent"` — temporal proximity weighting: `impact × exp(−0.5 × Δhours)`
+- `from` — lookback start (e.g., 24 hours before incident)
+- `to` — the incident timestamp
+- `repo_id` — the affected repo
+
+**Why `recent` mode?** It exponentially amplifies changes close to the incident time while still weighting by structural impact. A high-impact change made 1 hour before the incident scores much higher than the same change made 20 hours before.
+
+**Success criteria:** A ranked list of changes, with the most likely culprits at the top.
+
+### 3. Check for unexpected changes
+
+Call `get_evolution` again with `mode: "novel"` on the same time window:
+- Flags changes to rarely-modified code (high in_degree, low change frequency)
+- A core utility that hasn't changed in 90 days suddenly changing near an incident is a strong signal
+
+**Decision:** If `novel` mode surfaces different symbols than `recent` mode, investigate both — the root cause may be an unexpected change to stable infrastructure.
+
+### 4. Trace the blast radius of top suspects
+
+For the top 3–5 symbols from steps 2–3, call `get_impact` with `direction: upstream`:
+- How many downstream consumers were affected?
+- What execution flows pass through this symbol?
+
+**Decision:** Prioritize symbols where the blast radius overlaps with the reported failure area.
+
+### 5. Trace execution flows
+
+Use `get_symbol_context` on the top suspects to see which processes (HTTP handlers, background jobs, etc.) they participate in.
+
+**Decision:** If the incident is in a specific endpoint/flow, focus on suspects that are members of that process.
+
+### 6. Build the full timeline for the suspect
+
+Once you have a primary suspect, call `get_timeline` with the symbol name to see its full version history:
+- What changed in each commit?
+- When was the last "stable" version?
+- Was the change a modification, or was it newly added?
+
+### 7. Correlate with surrounding changes
+
+Call `get_evolution` with mode `directional` to separate:
+- **Added symbols** — new code introduced (potential new bugs)
+- **Removed symbols** — deleted code (potential missing functionality)
+- **Modified symbols** — changed behaviour (potential regressions)
+
+### 8. Check historical coupling (cochange)
+
+For the primary suspect, call `get_cochange_context`:
+- Which symbols historically co-change with this one?
+- If the blast radius from `get_impact` doesn't explain the failure area, check cochange partners — the coupling may be behavioral, not structural.
+
+**Decision:** If a cochange partner is in the failure area but has no direct call relationship to the suspect, it's a hidden dependency — investigate both.
+
+### 9. Replay the sub-commit implementation history (if needed)
+
+If the suspect's commit history doesn't explain the intent, call `get_episode_replay`:
+- What was tried before the final committed state?
+- Was any approach attempted and reverted in the same session?
+- The `attempted_and_reverted` hint often explains why seemingly-correct code was changed to something subtler.
+
+## Report: Root Cause Analysis
+
+1. **Incident Timeline** — when it started, what was observed
+2. **Most Likely Cause** — the top-ranked change(s) by `recent` mode with blast radius confirmation
+3. **Supporting Evidence** — novelty signal (was this an unexpected change?), blast radius overlap with failure area, process membership overlap
+4. **Change History** — full timeline of the suspect symbol
+5. **Affected Scope** — all processes and downstream consumers impacted
+6. **Remediation** — revert the change, fix forward, or mitigate
+
+## Algorithm Selection Guide for Incidents
+
+| Phase | Tool / Mode | Why |
+|-------|-------------|-----|
+| Initial triage | `get_evolution` `recent` | Time-weighted ranking surfaces changes near the incident |
+| Anomaly detection | `get_evolution` `novel` | Catches unexpected changes to stable code |
+| Scope assessment | `get_impact` | Ranks by structural significance (blast radius) |
+| Hidden coupling | `get_cochange_context` | Surfaces behavioral coupling not in the call graph |
+| Direction analysis | `get_evolution` `directional` | Separates added/removed/modified |
+| Sub-commit intent | `get_episode_replay` | Reveals what was tried before the committed state |
+| Quick summary | `get_evolution` `overview` | Fast module-level scan before deep-diving |
+
+## Common Mistakes
+
+| Mistake | Reality |
+|---------|---------|
+| Starting with `impact` mode | Use `recent` first — time proximity is the strongest signal for incidents |
+| Only looking at the most recent commit | The root cause may be from an earlier change whose effects were delayed |
+| Ignoring `novel` mode | Unexpected changes to stable code are often the root cause |
+| Not checking blast radius overlap | A change is only a suspect if its blast radius reaches the failure area |
+| Stopping at call graph analysis | `get_cochange_context` finds hidden coupling — symbols that move together without calling each other |
+| Reading only committed code | `get_episode_replay` reveals tried-and-reverted approaches that explain the current implementation |

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

@@ -0,0 +1,116 @@
+---
+name: memtrace-refactoring-guide
+description: "Always 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."
+allowed-tools:
+  - mcp__memtrace__find_most_complex_functions
+  - mcp__memtrace__find_dead_code
+  - mcp__memtrace__find_bridge_symbols
+  - mcp__memtrace__find_central_symbols
+  - mcp__memtrace__get_symbol_context
+  - mcp__memtrace__get_impact
+  - mcp__memtrace__get_evolution
+  - mcp__memtrace__analyze_relationships
+  - mcp__memtrace__list_communities
+  - mcp__memtrace__calculate_cyclomatic_complexity
+  - mcp__memtrace__list_indexed_repositories
+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.
+
+## Steps
+
+### 1. Identify refactoring candidates
+
+Run these three tools in parallel to build a candidate list:
+
+**a) Complexity hotspots:**
+Call `find_most_complex_functions` with `limit: 20`
+
+**b) Dead code:**
+Call `find_dead_code` to find unused symbols
+
+**c) Architectural bottlenecks:**
+Call `find_bridge_symbols` to find chokepoints with too much responsibility
+
+### 2. Score candidates by volatility
+
+Call `get_evolution` with mode `compound` over a 90-day window:
+- Symbols that are BOTH complex AND frequently changing are the highest priority
+- Complex but stable code can wait — it's not causing active pain
+- Volatile but simple code may be fine — frequent changes to simple code is normal
+
+**Priority matrix:**
+
+| | Low Complexity | High Complexity |
+|---|---|---|
+| **Stable (low change freq)** | Leave alone | Monitor; refactor if touched |
+| **Volatile (high change freq)** | Normal; leave alone | **TOP PRIORITY** — refactor first |
+
+### 3. Assess risk for top candidates
+
+For each top-priority candidate, call `get_impact` with `direction: both`:
+- **Low risk** → refactor directly
+- **Medium risk** → refactor with comprehensive tests
+- **High/Critical risk** → plan incremental migration with backward compatibility
+
+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
+
+For each refactoring target, call `analyze_relationships`:
+- `find_callees` — what does it depend on? (these become candidates for extraction)
+- `find_callers` — what depends on it? (these need updating after refactoring)
+- `class_hierarchy` — is it part of an inheritance chain? (Liskov concerns)
+
+### 5. 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
+
+Synthesize into a phased plan:
+
+**Phase 1 — Quick Wins:**
+- Dead code removal (zero-risk deletions)
+- Simple functions with high churn (reduce volatility)
+
+**Phase 2 — High-Impact Refactors:**
+- Complex + volatile functions (highest priority by the matrix)
+- Bridge symbols with too many responsibilities (extract interfaces)
+
+**Phase 3 — Structural Improvements:**
+- Splitting oversized communities into smaller, focused modules
+- Extracting shared logic from bridge symbols into dedicated services
+
+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
+
+## Decision Points
+
+| Condition | Action |
+|-----------|--------|
+| 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 |
+| 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 |
+
+## Common Mistakes
+
+| Mistake | Reality |
+|---------|---------|
+| Refactoring the most complex function first | Complexity alone isn't enough — prioritize by complexity × volatility |
+| Deleting all dead code at once | Some "dead" code is called dynamically; verify before batch deletion |
+| Refactoring without checking blast radius | A "simple" refactor on a bridge symbol can cascade across the codebase |
+| Not checking temporal evolution | A complex function that hasn't changed in a year is lower priority than a simpler one that changes weekly |

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

@@ -0,0 +1,98 @@
+---
+name: memtrace-session-continuity
+description: "Always use at session start or resume when the user asks to continue, catch up, see what changed while away, recover prior context, or orient without guessing timestamps in an indexed source-code repo. Do not use git log, Grep, or manual file search for catch-up; Memtrace provides session anchors and change memory."
+allowed-tools:
+  - mcp__memtrace__get_changes_since
+  - mcp__memtrace__list_indexed_repositories
+  - mcp__memtrace__get_evolution
+user-invocable: true
+---
+
+## Overview
+
+Session continuity for agents. Instead of guessing a time window and blindly running `get_evolution`, pass a `session_anchor` from your last session and get back exactly what changed — nothing more. The response returns a new anchor to persist for next time.
+
+**Core principle:** Agents track a cursor, not a clock. Never guess timestamps.
+
+## Steps
+
+### 1. Find or bootstrap the session anchor
+
+Look for a stored `session_anchor` from your last session:
+
+```json
+{
+  "last_episode_id": "ep_abc123",
+  "last_reference_time": "2026-04-13T10:43:00Z"
+}
+```
+
+If you have no anchor yet (first run), call `list_indexed_repositories`. Each repo now includes `last_episode_id`, `last_episode_time`, and `last_episode_type` — use `last_episode_id` as your bootstrap anchor.
+
+### 2. Call `get_changes_since`
+
+```
+get_changes_since(
+  repo_id: "...",
+  last_episode_id: "ep_abc123"      // preferred — exact episode boundary
+  // OR
+  last_reference_time: "2026-04-13T10:43:00Z"   // fallback
+)
+```
+
+### 3. Interpret the response
+
+| `status` | Meaning | Action |
+|---|---|---|
+| `no_changes` | Nothing changed since your anchor | Safe to proceed; store new anchor |
+| `changes_detected` | Full symbol-level delta returned | Review `modified[]`, `added[]`, `removed[]` |
+| `changes_detected_overview` | >500 candidates — module rollup only | Check `by_module` for affected areas |
+| `error` | Bad anchor or unknown episode | Fall back to `last_reference_time` or re-index |
+
+### 4. Decide whether changes are relevant
+
+```
+changes_detected
+├── Check modified[]/added[]/removed[] — do any overlap with your current task?
+│   ├── YES → understand what changed before proceeding
+│   └── NO  → safe to continue, update anchor
+
+changes_detected_overview (large window)
+├── Check by_module — does any changed module overlap with your task area?
+│   ├── YES → get_evolution(mode: compound) scoped to that window for detail
+│   └── NO  → ignore, update anchor
+```
+
+### 5. Always persist the returned anchor
+
+Every response includes a new `session_anchor`. Store it for next session:
+
+```json
+{
+  "session_anchor": {
+    "last_episode_id": "ep_xyz789",
+    "last_reference_time": "2026-04-13T14:22:00Z"
+  }
+}
+```
+
+## Auto-mode Selection
+
+`get_changes_since` automatically picks the right mode so it never crashes:
+
+| Candidate count | Mode selected | What you get |
+|---|---|---|
+| 0 | — | `no_changes` immediately |
+| 1–499 | `compound` | Full symbol scoring |
+| 500+ | `overview` | Module rollup only |
+
+`candidate_count` in the response tells you what was found before selection.
+
+## Common Mistakes
+
+| Mistake | Reality |
+|---------|---------|
+| Using `get_evolution` with a guessed timestamp | `get_changes_since` uses an exact episode boundary — no guessing, no over-fetching |
+| Discarding the returned `session_anchor` | Without it, next session reverts to timestamp guessing |
+| Treating `changes_detected_overview` as too large to act on | `by_module` is complete — it tells you exactly which areas changed even in large windows |
+| Calling this tool repeatedly within one session | Call once at session start; use the returned evolution result for the rest of the session |

package/skills/workflows/memtrace-style-fingerprint.md

@@ -0,0 +1,111 @@
+---
+name: memtrace-style-fingerprint
+description: "Always use before writing or editing source code in an indexed repo when choosing between competing idioms (ternary vs if-else, arrow vs function declaration, const vs let, await vs .then, early-return vs nested-return). Pull the codebase's empirical style norm from Memtrace and match it instead of re-deriving style from training priors. Do not maintain a markdown style guide for the project; the fingerprint is sampled live from the actual code."
+allowed-tools:
+  - mcp__memtrace__get_style_fingerprint
+  - mcp__memtrace__get_codebase_briefing
+  - mcp__memtrace__find_code
+  - mcp__memtrace__list_indexed_repositories
+user-invocable: true
+---
+
+## Overview
+
+Every indexed Memtrace repository carries an empirical **style fingerprint** — descriptive histograms of competing AST idioms (ternary vs if-else, arrow vs function declaration, const vs let, await vs `.then`, early-return vs nested-return depth) computed at parse time and rolled up to Repository + Community level. This workflow tells you when and how to consult it so your edits match the codebase's existing idioms instead of drifting on stylistic choices the linter doesn't catch.
+
+The fingerprint is **descriptive, not prescriptive**. It reports what the codebase actually does, not what a style guide says it should do. If the codebase deviates from a popular convention for some reason, the fingerprint captures the deviation and you should match the deviation — that's the whole point. For prescriptive bug/security/perf rules, use `find_code_review_issues` instead.
+
+## When to use this workflow
+
+| Situation | Action |
+|---|---|
+| About to write new code (function, component, module) in an indexed repo | Step 1 + Step 2 with `file_path=<the file you'll create>` |
+| About to edit an existing file | Step 1 + Step 2 with `file_path=<that file>` |
+| Asked "what's the convention here for X?" | Step 1 only — repo-mode fingerprint answers it |
+| Deciding between two equivalent idioms (ternary vs if, arrow vs fn-decl, await vs then) | Step 2 with `file_path` — `delta_from_codebase_norm` tells you which idiom matches the norm |
+| Reviewing a diff | Step 2 on each modified file — flag any new idioms that diverge from the file's language norm |
+| Session start in a multi-day project | Read the `style:` line in `get_codebase_briefing` (auto-included) |
+
+If the repo is not indexed in Memtrace, this workflow does not apply — fall back to your default behavior.
+
+## Steps
+
+### 1. Get the codebase's overall norm
+
+Call `get_style_fingerprint(repo_id)` with no `file_path`. The response includes:
+
+- `histogram` — raw counts (e.g. `ternary_count: 1005, if_stmt_count: 8087`)
+- `ratios` — computed shares for each competing pair (e.g. `ternary_share: 0.11`)
+- `dominant_idioms` — top-3 dimensions sorted by `|ratio - 0.5|` (strongest preferences first), each with a `dimension`, `ratio`, and human-readable `interpretation`
+- `function_count` — sample size at the repo level
+- `sample_threshold` — minimum observations before a ratio is committed (currently 20)
+
+A `ratio` of `null` means the codebase doesn't have enough observations for that dimension to commit a norm — treat it as "no signal", do not assume one.
+
+### 2. Get the file's deviation from the norm (when about to edit a specific file)
+
+Call `get_style_fingerprint(repo_id, file_path=<file>)`. The response adds:
+
+- `file_fingerprint` — the same shape as `histogram`/`ratios`/`function_count` but computed over just the functions in that file
+- `codebase_fingerprint` — repo aggregate for comparison
+- `delta_from_codebase_norm` — array of dimensions where the file diverges ≥0.15 from the codebase, sorted by absolute delta, capped at top 5. Each entry has `dimension`, `file_ratio`, `codebase_ratio`, `abs_delta`, and a `note` describing the direction
+
+**Match the file's `language_fingerprint`, not the repo aggregate.** In file mode the response carries `language` (the file's language), `language_fingerprint` (that language's slice — the primary comparator), and `delta_from_language_norm` (divergence vs the language, not the repo). Per-language slicing prevents cross-applying Python norms to JS code or vice versa — read the `language_fingerprint`. (`delta_from_codebase_norm` is retained as a deprecated alias and is removed in 0.5.14.)
+
+If `delta_from_language_norm` is empty, the file is already aligned — proceed without style adjustments. If it has entries, your edits should not amplify the divergence (e.g. don't add more ternaries to a file that's already above the language's ternary norm).
+
+### 3. Read the briefing line at session start (passive)
+
+`get_codebase_briefing(repo_id)` auto-includes a `style:` line in its summary when the sample threshold is met and at least one ratio is outside the 0.4..0.6 no-preference band. Format:
+
+```
+style: <interpretation 1> (<%>); <interpretation 2> (<%>); <interpretation 3> (<%>)
+```
+
+Example on a TS/JS-heavy codebase:
+
+```
+style: strongly prefers arrow functions (98%); strongly prefers async/await over .then chains (88%); strongly prefers const over let (94%)
+```
+
+You should already be reading the briefing at session start (per `memtrace-codebase-exploration`). The `style:` line lands in your context for free — no extra call needed.
+
+## Decision points
+
+| Condition | Action |
+|---|---|
+| `dominant_idioms[0].ratio >= 0.85` or `<= 0.15` | Treat as a hard preference — match it unless there's a specific structural reason not to |
+| `dominant_idioms[0].ratio` in `0.65..0.85` or `0.15..0.35` | Treat as a soft preference — match it for new code, leave existing patterns alone |
+| `ratio` in `0.4..0.6` | No clear preference — use your own judgment, match local file context |
+| `ratio` is `null` (below sample threshold) | No signal — don't assume a norm; pick the idiom that fits the immediate context |
+| `delta_from_codebase_norm` shows your target file already diverges from the norm | Don't amplify the divergence with your edits — match the codebase, not the outlier file |
+| `file_fingerprint` is empty (file has no functions yet, or is a config file) | Use the language slice or repo aggregate; this is creation territory |
+
+## Anti-patterns — do not do these
+
+- **Reading the repo aggregate when editing a single-language file.** If the codebase is 70% TS / 30% Python, the repo aggregate mixes both. The `language_fingerprint` (when available) or `codebase_fingerprint.ratios` filtered by the file's language is what you should match. Cross-applying TS norms to a Python file is the failure mode this whole tool exists to prevent.
+- **Treating the fingerprint as prescriptive.** It tells you what the codebase does. If the codebase consistently does something unusual, match that — don't override with "this isn't best practice" arguments. The whole point is to stop drifting from the codebase's own choices.
+- **Calling `get_style_fingerprint` for every line of code.** Once per file at the start of an edit session is enough. The norm doesn't change between your edits within the same session.
+- **Ignoring the briefing line.** It auto-loads into your context. If you act on style choices in an edit session without reading it first, you're spending tool calls to re-derive something you already had.
+- **Adding a markdown style guide to the project.** The fingerprint is the style guide. It refreshes on every reindex. A markdown file would either duplicate it or contradict it.
+
+## Naming-case dimensions (shipped in 0.5.13)
+
+Beyond the AST idioms, the fingerprint also reports identifier **naming-case** per scope, across all 13 source languages:
+
+- **Variables / functions / types / constants / files** — the share of camelCase / snake_case / PascalCase / SCREAMING_SNAKE / kebab. Read e.g. `ratios.naming_variables_snake_share` or the `dominant_idioms` entry that names the scope's winning case ("vars are snake_case (89%)").
+- **Config keys** for YAML / JSON / TOML / HCL / SQL — `ratios.config_keys_*_share`.
+- **Enforcement-aware:** languages that compiler-enforce a scope return `null` for it (Rust vars/fns/types/consts, Ruby constants). A `null` there means "the compiler decides, not the codebase" — don't try to match a non-signal.
+- **Go** reports `go_exported_share` (PascalCase = exported) instead of per-case naming, because case encodes visibility in Go.
+
+When editing, match the naming case the file's `language_fingerprint` reports for the scope you're touching — same per-language rule as the idiom dimensions.
+
+## What this workflow does NOT cover
+
+- **Security / bug / performance rules** — use `find_code_review_issues` (prescriptive deterministic review).
+- **Comment / docstring style** — not in scope; use file-local examples.
+- **Architecture / module-organization decisions** — see `memtrace-codebase-exploration` and `memtrace-refactoring-guide`.
+
+## Why this exists
+
+Without this workflow, LLM editors drift session-to-session on style choices that aren't enforced by linters — one session uses ternaries, the next doesn't; one uses arrow functions, the next uses `function`. The fix isn't a manually-maintained style guide (stale by week 2). The fix is sampling the codebase's actual idioms at parse time and reading them before each edit. The fingerprint is computed in the same parse pass as cyclomatic + cognitive complexity at sub-1% overhead, so the cost of providing the answer is near zero.