memtrace-skills 0.7.10

package/skills/commands/memtrace-impact.md

@@ -0,0 +1,64 @@
+---
+name: memtrace-impact
+description: "Always use before or during source-code changes when the user asks about blast radius, impact, what breaks, risk, upstream callers, downstream dependencies, or consequences of modifying a symbol. Do not use Grep or manual reference search; Memtrace computes transitive graph impact."
+allowed-tools:
+  - mcp__memtrace__get_impact
+  - mcp__memtrace__detect_changes
+  - mcp__memtrace__find_symbol
+  - mcp__memtrace__find_code
+user-invocable: true
+---
+
+## 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 |
+|------|---------|
+| `get_impact` | Blast radius from a specific symbol (by ID) |
+| `detect_changes` | Scope symbols affected by a diff/patch |
+
+> **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`.
+
+
+## Steps
+
+### 1. Identify the symbol
+
+If you have a symbol name but not its ID:
+- Use `find_symbol` for exact names
+- Use `find_code` for natural-language queries
+
+### 2. Run impact analysis
+
+Use the `get_impact` MCP tool:
+- `symbol_id` — the symbol you plan to change (required)
+- `direction` — `upstream` (what depends on me), `downstream` (what I depend on), or `both` (default)
+- `depth` — traversal hops (default 3)
+
+### 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; consider backward-compatible changes |
+
+### 4. For diff-based analysis
+
+When you have an actual code diff (not just a symbol), use `detect_changes`:
+- Scopes all symbols affected by the diff
+- Returns blast radius AND affected processes (execution flows)
+- Useful for PR reviews or pre-commit checks
+
+## Decision Points
+
+| Situation | Action |
+|-----------|--------|
+| Changing a single function | `get_impact` with `direction: both` |
+| Reviewing a PR or diff | `detect_changes` with the diff content |
+| Renaming/removing a public API | `get_impact` with `direction: upstream`, high depth |
+| Refactoring internals | `get_impact` with `direction: downstream` to check what you depend on |

package/skills/commands/memtrace-index.md

@@ -0,0 +1,71 @@
+---
+name: memtrace-index
+description: "Always use when the user asks to index, parse, ingest, reindex, watch, or prepare a source-code repo for Memtrace analysis, when code exploration needs an index, or when searches return 0/partial results for source paths under an indexed root. Use this before Grep, Glob, rg, find, or manual code search whenever the repo can be indexed."
+allowed-tools:
+  - mcp__memtrace__index_directory
+  - mcp__memtrace__check_job_status
+  - mcp__memtrace__list_jobs
+  - mcp__memtrace__list_indexed_repositories
+user-invocable: true
+---
+
+## Overview
+
+Index a local codebase into the persistent code knowledge graph. This is always the first step — it parses every source file, resolves cross-file relationships, detects API endpoints/calls, runs community detection and process tracing, and embeds all symbols for semantic search.
+
+## Quick Reference
+
+| Parameter | Purpose |
+|-----------|---------|
+| `path` | Absolute path to the directory to index |
+| `incremental` | Only re-parse changed files (use for subsequent runs) |
+| `clear_existing` | Wipe and rebuild from scratch |
+
+> **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`.
+
+
+## Steps
+
+### 1. Check if already indexed
+
+Use the `list_indexed_repositories` MCP tool first. If the repo is already indexed and recent, skip to step 4.
+
+**Success criteria:** You have a list of repo_ids and their last-indexed timestamps.
+
+If a repo is present but searches miss a source subdirectory under that repo
+root (for example `ui/`, `memtrace-ui/`, `web/`, `frontend/`, or `src/`), treat
+that as a stale/partial index. Do not use grep as a workaround. Run incremental
+indexing on the repo root, then retry the Memtrace query.
+
+### 2. Index the directory
+
+Use the `index_directory` MCP tool:
+
+- Set `path` to the project root (absolute path)
+- Set `incremental: true` if re-indexing after changes
+- Set `clear_existing: true` only if a full rebuild is needed
+
+**Success criteria:** You receive a `job_id` immediately.
+
+### 3. Poll for completion
+
+Use `check_job_status` with the `job_id` every 2–3 seconds.
+
+Pipeline stages in order: **scan → parse → resolve → communities → processes → persist → embeddings → api_detect → done**
+
+Wait until `status = "completed"`. If `status = "failed"`, report the error message to the user.
+
+### 4. Report to user
+
+After indexing completes, call `list_indexed_repositories` to confirm the repo appears with correct node/edge counts. Report: repo_id, languages detected, total symbols, total relationships.
+
+**Save the `repo_id`** — most other memtrace tools require it.
+
+## Error Handling
+
+| Error | Action |
+|-------|--------|
+| Path does not exist | Ask user to verify the absolute path |
+| Job status "failed" | Report the error message; suggest `clear_existing: true` for a fresh rebuild |
+| Timeout (job running > 5 min) | Large repos are normal; keep polling. For monorepos, index subdirectories separately |
+| Already indexed | Use `incremental: true` to update, or skip indexing entirely |

package/skills/commands/memtrace-quality.md

@@ -0,0 +1,69 @@
+---
+name: memtrace-quality
+description: "Always use for source-code quality, dead code, unused functions, zero callers, complexity, cyclomatic complexity, hotspots, refactoring candidates, or code smell questions. Do not use Grep, Glob, rg, or manual reference search for unused code; Memtrace uses graph reachability and complexity metrics."
+allowed-tools:
+  - mcp__memtrace__find_dead_code
+  - mcp__memtrace__calculate_cyclomatic_complexity
+  - mcp__memtrace__find_most_complex_functions
+  - mcp__memtrace__get_repository_stats
+user-invocable: true
+---
+
+## Overview
+
+Identify code quality issues using structural graph analysis — dead code (zero callers), complexity hotspots (high out-degree), and repository-wide statistics.
+
+## Quick Reference
+
+| Tool | Purpose |
+|------|---------|
+| `find_dead_code` | Symbols with zero callers (potentially unused) |
+| `calculate_cyclomatic_complexity` | Complexity score for a specific symbol |
+| `find_most_complex_functions` | Top-N functions by complexity across the repo |
+| `get_repository_stats` | Repo-wide counts: nodes, edges, communities, processes |
+
+> **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`.
+
+
+## Steps
+
+### 1. Get repository overview
+
+Use `get_repository_stats` to understand the codebase scale:
+- Node counts by kind (functions, classes, methods, interfaces)
+- Edge counts (calls, imports, extends, type references)
+- Community and process counts
+
+### 2. Find dead code
+
+Use `find_dead_code`:
+- `repo_id` — required
+- `include_tests` — set true to also flag unused test helpers (default false)
+
+**Note:** Exported symbols and entry points are excluded by default — the tool won't flag public APIs as "dead" just because they're called externally.
+
+### 3. Find complexity hotspots
+
+Use `find_most_complex_functions`:
+- `repo_id` — required
+- `limit` — how many to return (default 10)
+
+Complexity scoring (based on out-degree — number of callees):
+| Score | Rating | Action |
+|-------|--------|--------|
+| < 5 | Low | No action needed |
+| 5–10 | Medium | Monitor; consider splitting if growing |
+| 10–20 | High | Refactoring candidate; extract helper functions |
+| > 20 | Critical | Immediate attention; this function does too much |
+
+### 4. Drill into specific functions
+
+Use `calculate_cyclomatic_complexity` on specific symbols flagged by the user or found in step 3.
+
+## Common Mistakes
+
+| Mistake | Reality |
+|---------|---------|
+| Treating all dead code as deletable | Some "dead" code is called via reflection, dynamic dispatch, or external consumers |
+| Ignoring exported symbols in dead code results | If `include_tests: false`, exported symbols are already excluded |
+| Only looking at the highest complexity | Medium-complexity functions that are growing (check `get_evolution`) are often more urgent |

package/skills/commands/memtrace-relationships.md

@@ -0,0 +1,73 @@
+---
+name: memtrace-relationships
+description: "Always use for source-code relationship questions: callers, callees, references, imports, exports, type usages, class hierarchy, inheritance, implementations, overrides, or dependencies between symbols. Do not use Grep, Glob, rg, find, or manual text search for references; Memtrace traverses typed AST graph edges."
+allowed-tools:
+  - mcp__memtrace__analyze_relationships
+  - mcp__memtrace__get_symbol_context
+  - mcp__memtrace__find_symbol
+  - mcp__memtrace__find_code
+user-invocable: true
+---
+
+## Overview
+
+Traverse the code knowledge graph to map relationships between symbols — callers, callees, class hierarchies, imports, exports, and type usages. Essential for understanding a symbol's neighbourhood before modifying it.
+
+## Quick Reference
+
+| query_type | What it finds |
+|------------|---------------|
+| `find_callers` | What calls this function/method? |
+| `find_callees` | What does this function call? |
+| `class_hierarchy` | Parent classes, interfaces, mixins |
+| `overrides` | Which child classes override this method? |
+| `imports` | What modules does this file import? |
+| `exporters` | Which files import this module? |
+| `type_usages` | Where is this type/interface referenced? |
+
+> **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`.
+
+
+## Steps
+
+### 1. Get the symbol ID
+
+If you don't have a symbol `id`, find it first:
+- Use `find_symbol` for exact names
+- Use `find_code` for natural-language queries
+
+### 2. Choose your approach
+
+**Quick 360° view** → Use `get_symbol_context`
+Returns in one call: direct callers, callees, type references, community membership, process membership, and cross-repo API callers.
+
+**ALWAYS prefer `get_symbol_context` first** — it answers "what does this touch and what touches it?" faster than multiple `analyze_relationships` calls.
+
+**Targeted traversal** → Use `analyze_relationships`
+When you need a specific relationship type at a specific depth:
+- `symbol_id` — the symbol to start from (required)
+- `query_type` — one of the types above (required)
+- `depth` — traversal hops, default 2 (higher = slower but reveals indirect deps)
+
+### 3. Interpret results
+
+- **High in_degree** (many callers) → widely-used symbol; changes have large blast radius
+- **High out_degree** (many callees) → complex function; candidate for refactoring
+- **Deep class hierarchy** → check for Liskov violations or fragile base class issues
+- **Cross-repo API callers** → changes require coordination with other teams/services
+
+### 4. Follow up
+
+After understanding relationships, consider:
+- `get_impact` to quantify the blast radius of a change
+- `get_evolution` to see how this symbol has changed over time
+- `find_dead_code` if you found unreferenced symbols
+
+## Decision Points
+
+| Situation | Action |
+|-----------|--------|
+| Need broad context fast | Use `get_symbol_context` (one call, full picture) |
+| Need specific relationship at depth >2 | Use `analyze_relationships` with custom depth |
+| Symbol has many callers | Follow up with `get_impact` before modifying |
+| Found cross-repo API callers | This is a service boundary — coordinate changes |

package/skills/commands/memtrace-search.md

@@ -0,0 +1,93 @@
+---
+name: memtrace-search
+description: "Always use to find, search, locate, or look up source-code symbols, functions, classes, types, constants, definitions, implementations, logic, error strings inside code, or where code lives. Do not use Grep, Glob, rg, find, or manual file search for code discovery. If Memtrace returns 0 results, broaden the Memtrace query and diagnose/reindex; do not switch to grep."
+---
+
+## Overview
+
+Find code using hybrid BM25 full-text + semantic vector search with Reciprocal Rank Fusion. Works for both natural-language queries and exact symbol names. This is the primary discovery tool — use it before calling relationship or impact analysis tools.
+
+## Quick Reference
+
+| Tool | Best For |
+|------|----------|
+| `find_code` | Natural-language queries ("authentication middleware", "retry logic"), broad searches |
+| `find_symbol` | Exact identifier names ("getUserById", "PaymentService"), when you know the name |
+| `get_source_window` | Optional: bounded source read after a Memtrace hit, when your harness lacks `Read(file, offset, limit)`. Otherwise prefer your harness's bounded read with the returned `start_line` / `end_line`. |
+
+## Steps
+
+### 1. Choose the right search tool
+
+- **Know the exact name?** → Use `find_symbol` with `fuzzy: true` for typo tolerance
+- **Describing behaviour?** → Use `find_code` with a natural-language query
+- **Searching all repos?** → Omit `repo_id` from either tool
+
+### 2. Execute the search
+
+> **Parameter types:** numbers must be JSON numbers, not strings. `limit: 20` is correct; `limit: "20"` returns `MCP error -32602: expected usize`.
+
+**`find_code` parameters:**
+- `query` — string, required. Natural-language or exact text.
+- `repo_id` — string, optional. Scope to a single repo (omit to search all).
+- `kind` — string, optional. Filter by symbol type: `"Function"`, `"Class"`, `"Method"`, `"Interface"`, `"APIEndpoint"`, `"APICall"`.
+- `limit` — **integer**, optional. Max results. Default `20`, capped at `100`.
+- `as_of` — string, optional. ISO-8601 timestamp for time-travel search (e.g. `"2026-04-01T00:00:00Z"`).
+- `file_path` — string, optional. File path or directory substring to constrain results (e.g. `"cli/commands"` or `"auth.py"`).
+
+**`find_symbol` parameters:**
+- `name` — string, required. Exact or partial symbol name (e.g. `"ValidateToken"`).
+- `fuzzy` — boolean, optional. Enable Levenshtein correction. Default `false`.
+- `edit_distance` — **integer**, optional. Maximum Levenshtein edit distance for fuzzy search. Default `2`, capped at `2`.
+- `repo_id` — string, optional. Scope to a single repo.
+- `kind` — string, optional. Filter by symbol type (e.g. `"Function"`, `"Class"`, `"Variable"`).
+- `file_path` — string, optional. Filter by file path substring.
+- `limit` — **integer**, optional. Max results. Default `10`, capped at `50`.
+
+**Success criteria:** Results include `file_path`, `start_line`, `kind`, and relevance `score`.
+
+### 3. Use results for next steps
+
+The default next step is a **graph tool** — `get_symbol_context`,
+`analyze_relationships`, or `get_impact`. Those answer "who calls this",
+"what's the blast radius", "what community is it part of" — context no
+file read can give. That's what Memtrace uniquely provides.
+
+Source bytes come last, only when you're about to edit or quote. Use a
+bounded `Read(file_path, offset=start_line, limit=end_line-start_line+8)`,
+or `get_source_window` if your harness lacks bounded reads. Do not whole-file.
+
+Save the symbol `id` from results — pass it to:
+- `analyze_relationships` to map callers/callees
+- `get_symbol_context` for a 360-degree view
+- `get_impact` to assess blast radius before changes
+
+### Multi-word natural-language queries
+
+When your query is 3+ words and feels descriptive (e.g. "validate auth token", "find HTTP server error"), don't stop at the first `find_code` call:
+
+1. First try the verbatim query.
+2. If results look generic or the right doc isn't at rank 1, fan out **in parallel** with up to 3 identifier-shaped reshapes:
+   - camelCase: "validate auth token" → `validateAuthToken`
+   - snake_case: → `validate_auth_token`
+   - Domain-likely identifiers: → `auth_token`, `tokenValidator`, `verifyToken`
+3. Memtrace's tokenizer splits camelCase / snake / kebab at index time, so reshaped queries hit identifier names directly.
+4. Take the union of top-5 from each call, dedupe by `file_path:start_line`.
+
+**Worked examples** (verbatim → reshapes to try in parallel):
+- "validate auth token" → `validateAuthToken`, `validate_auth_token`, `verifyToken`
+- "find http server error" → `findHttpServerError`, `http_error`, `serverError`
+- "render value panel" → `renderValuePanel`, `ValuePanel`, `value_panel`
+
+## Common Mistakes
+
+| Mistake | Reality |
+|---------|---------|
+| Searching without indexing first | Call `list_indexed_repositories` to verify the repo is indexed |
+| Using find_symbol for vague queries | Use `find_code` for natural-language; `find_symbol` is for exact names |
+| Ignoring the `kind` filter | Narrow results with kind=Function, kind=Class etc. to reduce noise |
+| Re-searching to get more context | Use the symbol `id` with `get_symbol_context` instead of re-searching |
+| Reading the whole file after a hit | First call `get_symbol_context` for callers/callees. If you still need source, do a bounded `Read(file, offset=start_line, limit=N)` — never whole-file. `get_source_window` is fine if your harness has no bounded read. |
+| Going straight from `find_code` to source read | Memtrace's value is the graph. Default next step is `get_symbol_context` or `get_impact`, not source. |
+| Treating 0 results as permission to grep | 0 results means broaden the Memtrace query, check repo_id/path filters, then reindex if coverage is missing |
+| Assuming a UI subdirectory is unindexed because stats show backend files | If `ui/`, `memtrace-ui/`, or another source directory is under the indexed repo root, diagnose/reindex with Memtrace instead of searching files manually |

package/skills/workflows/memtrace-change-impact-analysis.md

@@ -0,0 +1,85 @@
+---
+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."
+allowed-tools:
+  - mcp__memtrace__find_symbol
+  - mcp__memtrace__find_code
+  - mcp__memtrace__get_symbol_context
+  - mcp__memtrace__get_impact
+  - mcp__memtrace__detect_changes
+  - mcp__memtrace__get_evolution
+  - mcp__memtrace__analyze_relationships
+  - mcp__memtrace__list_indexed_repositories
+user-invocable: true
+---
+
+## Overview
+
+Pre-change risk assessment workflow. Before modifying code, this workflow maps the full blast radius, identifies affected processes, checks recent change history for instability signals, and produces a risk-rated change plan.
+
+## Steps
+
+### 1. Identify what's being changed
+
+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.
+
+### 2. Get 360° context for each target
+
+For each symbol, call `get_symbol_context`:
+- Direct callers and callees
+- Community membership (which module is this in?)
+- Process membership (which execution flows does this participate in?)
+- Cross-repo API callers (is this an endpoint called by other services?)
+
+**Decision:** If cross-repo API callers exist, this change requires coordination with other teams. Flag this immediately.
+
+### 3. Compute blast radius
+
+For each target, call `get_impact` with `direction: both`:
+- Upstream impact: what depends on this symbol
+- Downstream impact: what this symbol depends on
+- Risk rating: Low / Medium / High / Critical
+
+**Decision:**
+| Risk | Action |
+|------|--------|
+| Low | Proceed with standard testing |
+| Medium | Review all direct callers; test affected processes |
+| High | Plan incremental migration; consider feature flags |
+| Critical | Full migration strategy; backward-compatible changes required |
+
+### 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.
+
+### 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.
+
+### 6. Produce the risk assessment
+
+Synthesize into a change plan:
+
+1. **Target(s)** — what's being changed and where
+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)?
+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
+
+## Decision Points
+
+| Condition | Action |
+|-----------|--------|
+| 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 |
+| 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 |

package/skills/workflows/memtrace-code-review.md

@@ -0,0 +1,48 @@
+---
+name: memtrace-code-review
+description: "Always use when the user asks to review a GitHub pull request, run Memtrace code review, post Memtrace review comments, create a PR with a review step, or publish local graph-backed review findings to GitHub. Prefer the review_github_pr MCP tool over manual diff inspection."
+when_to_use: "Triggered by 'review this PR', 'code review this pull request', 'post Memtrace review', 'run memtrace code-review', 'create PR with review', 'GitHub PR review', 'publish review comments', or any request to use Memtrace as a GitHub code reviewer. Use after code is pushed as a PR, and call review_github_pr instead of manually grepping diffs."
+paths: "**/*.{py,js,jsx,ts,tsx,mjs,cjs,rs,go,java,rb,c,cc,cpp,cxx,h,hpp,hh,cs,php,swift,kt,kts,scala,clj,cljs,ex,exs,erl,hrl,ml,mli,fs,fsx,r,jl,lua,dart,m,mm,asm,sql,gql,graphql,proto,sh,bash,zsh,fish,vue,svelte}"
+allowed-tools:
+  - mcp__memtrace__review_github_pr
+  - mcp__memtrace__find_code_review_issues
+  - mcp__memtrace__list_indexed_repositories
+user-invocable: true
+---
+
+## Overview
+
+Use Memtrace's local-first PR review workflow. The agent should call the `review_github_pr` MCP tool so review runs against the developer's local indexed graph, AST detectors, YAML rule pack, and review policy. GitHub is used for PR context and optional comment publication; source code analysis stays local.
+
+## Default Flow
+
+1. If the user gives a GitHub PR URL and asks to inspect or review it, call `review_github_pr` with `post: false`.
+2. If the user explicitly asks to publish, post comments, or complete the PR review, call `review_github_pr` with `post: true`.
+3. Use `graphMode: "strict"` by default. Use `graphMode: "off"` only when the user asks to benchmark non-graph behavior or the local graph is unavailable.
+4. Default to `minSeverity: "high"` and `maxComments: 5` when posting. For previews, `maxComments: 10` is acceptable.
+5. Pass `repoRoot` when the PR checkout is not the current working directory. Pass `repoId` when the indexed repository id is known.
+
+## Example User Prompts
+
+- "Review this PR with Memtrace: https://github.com/OWNER/REPO/pull/123"
+- "Use Memtrace to review this pull request and post the findings: https://github.com/OWNER/REPO/pull/123"
+- "Create the PR, then run Memtrace code review and publish the review comments."
+
+## Guardrails
+
+- Do not start with generic grep, rg, or manual diff review when `review_github_pr` is available.
+- Do not post comments unless the user explicitly requested publication.
+- Do not create benchmark-specific or PR-specific findings. The review must come from general Memtrace detectors, graph evidence, and policy ranking.
+- If the tool reports missing auth, tell the user to run `memtrace auth login`.
+- If the tool reports missing GitHub App installation, tell the user to install Memtrace Code Reviewer on that repository.
+- If the tool reports missing local graph context, tell the user to run `memtrace index .` at the workspace root.
+
+## Output
+
+For previews, summarize:
+- PR URL and repository
+- Graph state
+- Number of candidate comments
+- File, line, severity, and message for each finding
+
+For posted reviews, report the PR URL and number of comments posted.

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

@@ -0,0 +1,108 @@
+---
+name: memtrace-codebase-exploration
+description: "Always 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 Glob, find, tree, rg, or manual file browsing as the first exploration path; Memtrace provides structured graph briefing."
+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 `limit: 15`. It ranks symbols by PageRank over the repo's CALLS / REFERENCES edges (default `method: "pagerank"`, 0.85 damping factor).
+
+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 |