memtrace 0.1.2-2.5

package/skills/workflows/memtrace-codebase-exploration.md

@@ -0,0 +1,108 @@
+---
+name: memtrace-codebase-exploration
+description: "Use when the user asks to explore a codebase, understand a project, onboard to a new repo, get an overview of how code is structured, map the architecture, or wants a comprehensive understanding of a codebase they're new to"
+allowed-tools:
+  - mcp__memtrace__index_directory
+  - mcp__memtrace__check_job_status
+  - mcp__memtrace__list_indexed_repositories
+  - mcp__memtrace__get_repository_stats
+  - mcp__memtrace__list_communities
+  - mcp__memtrace__list_processes
+  - mcp__memtrace__find_central_symbols
+  - mcp__memtrace__find_bridge_symbols
+  - mcp__memtrace__find_api_endpoints
+  - mcp__memtrace__get_api_topology
+  - mcp__memtrace__get_evolution
+  - mcp__memtrace__find_most_complex_functions
+user-invocable: true
+---
+
+## 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 `list_indexed_repositories` first. If the repo is already indexed, skip to step 2.
+
+Otherwise, call `index_directory` with the project path, then poll `check_job_status` until completion.
+
+**Success criteria:** Repo appears in `list_indexed_repositories` with non-zero node/edge counts.
+
+### 2. Get the lay of the land
+
+Call `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 `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 `find_central_symbols` with `method: "pagerank"` and `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 `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 `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 `find_api_endpoints` to list all HTTP routes.
+
+**Decision:** If multiple repos are indexed, also call `get_api_topology` to map service-to-service dependencies.
+
+### 8. Recent activity
+
+Call `get_evolution` with mode `overview` and a 30-day window to see which modules have been most active recently.
+
+**Decision:** If the user asks about specific recent changes, switch to mode `compound` for symbol-level detail.
+
+### 9. Complexity hotspots
+
+Call `find_most_complex_functions` with `limit: 10` to identify potential technical debt.
+
+## 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
+
+## 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/skills/workflows/memtrace-incident-investigation.md

@@ -0,0 +1,104 @@
+---
+name: memtrace-incident-investigation
+description: "Use when the user is investigating a bug, incident, production issue, regression, something that broke, root cause analysis, debugging a failure, or trying to figure out what went wrong and when"
+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
+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)
+
+## 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 | Mode | Why |
+|-------|------|-----|
+| Initial triage | `recent` | Time-weighted ranking surfaces changes near the incident |
+| Anomaly detection | `novel` | Catches unexpected changes to stable code |
+| Scope assessment | `impact` | Ranks by structural significance (blast radius) |
+| Direction analysis | `directional` | Separates added/removed/modified |
+| Quick summary | `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 |

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

@@ -0,0 +1,116 @@
+---
+name: memtrace-refactoring-guide
+description: "Use when the user wants to refactor code, reduce complexity, clean up technical debt, split a large function, extract a module, reorganize code, identify refactoring priorities, or improve code structure"
+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 |