| name | memtrace-preflight |
| description | Run a one-call pre-flight check on a single existing symbol before editing it: blast radius, co-change partners, complexity, 30-day churn, and verification checklist, then check Cortex decision memory for rationale/bans when intent may matter. Use before modifying any existing function or symbol you did not just write. Do not start editing a non-trivial existing function without pre-flight plus decision-memory recall/provenance; Memtrace knows the dependency graph, change history, and recorded decisions. |
Overview
Pre-flight check: the two minutes before an edit that prevent the bug. One
preflight_check call composes the dependency graph, the bi-temporal change
history, and the complexity metrics into an actionable radar for a single
symbol.
Quick Reference
| Tool | Purpose |
|---|
preflight_check | Full radar for one symbol: blast radius + co-change + churn + checklist |
get_impact | Deeper blast-radius walk when the radar flags HIGH/CRITICAL |
get_cochange_context | Wider co-change window when partners look surprising |
recall_decision | Recorded choices, bans, and conventions for the symbol/subsystem/behavior |
why_is_this_here / governing_contracts | Symbol-scoped rationale and constraints when a symbol id is available |
Parameter types: MCP parameters are strictly typed. Numbers must be
Full parameter spec for every Memtrace tool: references/mcp-parameters.md (bundled at the memtrace-skills plugin root).
JSON numbers — not strings.
Steps
1. Run the pre-flight check before touching the symbol
preflight_check with:
repo_id — requiredsymbol — the function/method name you are about to modify
2. Read the checklist — it is generated from the graph, not boilerplate
Each line names something concrete to verify:
- "N symbols depend on this" → run
get_impact again after your edit and
compare total_affected; new dependents mean your change leaked wider
than intended.
- "hotspot: N changes in 30 days" → keep the edit small and reviewable;
hot code punishes large diffs.
- "sits in N process flow(s)" → check the process steps still order
correctly after the change.
- "last touched by agent session …" → read the latest episode before
assuming the current shape is intentional.
3. Treat co-change partners as part of the change
Files that historically changed together with the target usually need
updating in the same change. If you finish the edit without touching a
frequent partner, say so explicitly and why.
4. After the edit, close the loop
- Re-run
preflight_check (or get_impact) on the symbol.
- The complexity number should not have grown without a stated reason;
if it did, simplify before declaring the work done.
Cortex gate before editing
Before changing behavior, deleting code, or refactoring odd/legacy code:
- Run
recall_decision("<symbol/subsystem/behavior>").
- If the preflight/graph result gives you a numeric
symbol_id, run
why_is_this_here(symbol_id) and governing_contracts(symbol_id).
- Honor matching held decisions/bans. Treat CannotProve as unknown, not approval.
Verdict guidance
risk: CRITICAL/HIGH — propose the change plan before editing; consider
a feature flag or staged rollout.dependents: 0 — edit freely; note the symbol may be newly added or an
entry point.- A matching Cortex decision/ban — surface it before editing and do not
contradict it without explicit user sign-off.
Output
preflight_check returns one radar for the symbol:
| Field | Meaning |
|---|
risk | verdict, e.g. HIGH / CRITICAL (see Verdict guidance) |
dependents | blast radius — count of symbols that depend on the target |
| co-change partners | files that historically change with it (step 3) |
| complexity + 30-day churn | current complexity score and recent change count |
| checklist | generated verification lines, e.g. "hotspot: 6 changes in 30 days", "sits in 2 process flow(s)" |
