nikolai-vysotskyi/trace-mcp

Use `trace_get_index_health` to check the index, then `trace_search` to find symbols before reading whole files. Use `trace_get_symbol` for an exact definition and `trace_get_outline` for file structure. Use `trace_get_project_memo` at the start of a task when prior decisions matter, `trace_query_decisions` for a focused recall query, and `trace_remember_decision` to record an explicit English-language decision with the current bb thread as its session ID. Automatic decision capture rejects non-English text; for a manually entered decision in another language use the panel or `bb trace remember`. For other capabilities, search the catalog with `trace_tools` and pass the selected tool name and arguments to `trace_call`.

The thread's **Trace context** panel shows index health, saved decisions, and the provider's context-window usage. The same data and explicit writes are available through `bb trace status`, `bb trace decisions`, `bb trace remember`, and `bb trace index`; pass `--thread <id>` outside a bb thread.

The plugin runs trace-mcp in the bb environment's repository on its host machine. A thread needs an environment with a path. On first use, indexing may take time. Tool results are capped; narrow or page a query when a result says it was shortened.

# trace-mcp — Code Intelligence Routing

trace-mcp is a framework-aware code intelligence MCP server. It exposes 182 tools that return semantic, structured results over a cross-language dependency graph. When trace-mcp is available, it is almost always cheaper and more accurate than native file tools.

## When to Use

Activate this skill whenever you need to:
- Find a function, class, method, route, component, or any symbol
- Understand a file, module, or feature before editing
- Determine what breaks if you change something
- Trace a request flow, call graph, or data flow
- Audit architecture, dead code, tests, or security

**Do not use** `Read`, `Grep`, `Glob`, or shell `ls`/`find`/`cat`/`head`/`tail` for exploring source code (`.ts`, `.js`, `.py`, `.php`, `.go`, `.rb`, `.java`, etc.). Use trace-mcp tools instead. Native tools stay allowed only for non-code files (`.md`, `.json`, `.yaml`, configs) or immediately before an `Edit` on a known file.

# trace-mcp — Codemod Workflow

`apply_codemod` is the correct tool for any repeated mechanical change. Using `Edit` for the same pattern twice or more is a waste of tokens and is error-prone.

## When to Use — HARD RULE

If you are about to make the **same kind of change 2 or more times** — whether in one file or across many — stop and use `apply_codemod`. This includes:

- Adding `async`/`await` to a set of functions
- Updating a function signature everywhere it is called
- Fixing import paths after a move
- Adding or removing keywords/decorators
- Wrapping calls in a logger, try/catch, or feature flag
- Replacing a deprecated API usage

# trace-mcp — Pre-Commit & Pre-PR Checks

Before creating a commit or opening a pull request, run the trace-mcp validation suite. Fix any critical or high findings before committing.

## When to Use

- The user asks to commit, stage, or push changes
- The user asks to open a PR
- The agent has finished implementing a feature or fix and is about to hand off

## Checklist

### 1. Security scan

# trace-mcp — Refactoring Workflow

Use this skill whenever you are about to rename, restructure, extract, or otherwise refactor code in a project indexed by trace-mcp. The goal is to never break cross-file references and never guess at what is affected.

## When to Use

- Renaming a class, function, method, variable, or file
- Extracting a function or method
- Restructuring a module or splitting a file
- Changing a function signature
- Any change that touches more than one call site

## Refactoring Workflow