ldy26098
/
BMAD-METHOD
mirror of https://github.com/bmad-code-org/BMAD-METHOD.git
1
0
Fork 0
Code Packages Projects Releases Wiki Activity
BMAD-METHOD/.agents/skills/bmad-memtrace-fallback/SKILL.md

8.7 KiB
Raw Blame History

name description
bmad-memtrace-fallback Memtrace MCP fallback override. Use when server recovery has failed and the Human Developer EXPLICITLY grants permission to use legacy text-search tools (grep, glob, rg, find) instead of Memtrace structural queries.

Memtrace Manual Fallback Override

When to Use

Activate this skill after ALL the following have been attempted and failed:

  1. Timeout detected — The MCP connection failed, timed out, or a specific tool call returned an error (see the timeout detection and recovery workflow).
  2. Auto-recovery attempted — npm run memtrace:restart was executed and the adapter --check-freshness was re-run.
  3. Manual restart attempted — The recovery command was typed directly in the system terminal (by the developer or at their request).
  4. Still failing — After all the above, the Memtrace server or specific tools remain unavailable.

Pre-condition check before activating this skill:

  • Verify that npm run memtrace:restart exists in package.json (script from the recovery workflow). If it does not exist, the recovery attempt was incomplete — do not enter fallback mode.

DO NOT activate this skill:

  • Before attempting the full recovery chain (restart + reindex + manual terminal attempt)
  • When the Memtrace server is simply slow (wait for timeout first)
  • When you suspect the server might recover with another retry
  • Preemptively "just in case" the server goes down

Permission Protocol

Step 1: Halt Execution + Verify

Before asking the developer, run a final verification: call list_indexed_repositories via MCP. If it succeeds, the server is operational — abort this skill and resume normal Memtrace operation. If it fails or hangs, proceed below.

Immediately stop the current task. Do NOT attempt to continue with any code-discovery or code-modification operations.

Output a clear status message to the Human Developer:

Memtrace MCP server is unrecoverable.

Recovery script (npm run memtrace:restart) failed with exit code 1. The graph engine is permanently inoperable for this session.

I need your explicit permission to continue using legacy text-search heuristics (grep, glob, rg, find) instead of Memtrace structural queries.

WARNING: Without Memtrace, structural verification (blast radius, dead code detection, dependency analysis) will NOT be performed. Quality gates that require structural data (qa-memtrace.mjs) cannot run. Code changes made in this mode carry higher risk of unintended breakage.

Do you authorize me to proceed with legacy text-search tools? [yes / no]

Step 2: Wait for Explicit Response

  • ONLY "yes" (English) is accepted as explicit permission. Any other response ("no", "maybe", "I guess so", "whatever", "if you must", silence, non-English) is treated as NOT granted.
  • Timeout: Wait up to 5 minutes for a response. After 2 minutes of silence, re-prompt once. After 3 total timeouts with no response, treat as permission denied.
  • If the developer asks clarifying questions, answer honestly but do NOT proceed until a clear "yes" is given.
  • If the agent session restarts (crash, disconnect), re-request permission — fallback state is not persisted across sessions.

Step 3a: Permission GRANTED

If the developer responds with "yes":

  1. Acknowledge the authorization: "Proceeding with legacy text-search heuristics as authorized. Structural verification via Memtrace will be skipped."
  2. Disable Memtrace tools: Do NOT call any Memtrace MCP tools (find_code, find_symbol, get_impact, find_dead_code, list_indexed_repositories, etc.) for the remainder of this session. These will fail (connection refused).
  3. Use legacy tools instead:
    • grep (or rg) for content search
    • glob for cross-platform file-pattern matching
    • Get-ChildItem (PowerShell) or ls (Unix) for directory listing
    • read for reading file contents
    • write / edit for modifying files (standard agent tools — unaffected by Memtrace)
  4. Follow all other architectural constraints: Anti-Promise.all, JSON mutation safety, file location rules, naming conventions — these still apply.
  5. Tools not listed in the equivalences table: For any Memtrace tool without a legacy equivalent listed below, use grep + glob where applicable, or skip the operation entirely. Document which tools were skipped.
  6. Quality gates: For quality gates (qa-memtrace.mjs) that require structural data, produce a textual best-effort analysis using grep results. Explain to the developer that the gate cannot run without Memtrace and ask whether to proceed or skip.
  7. Document the fallback: In completion notes, explicitly state that legacy fallback was used and Memtrace structural verification was NOT performed. Record who granted permission, when, and what task was affected. Include the specific grep/glob patterns used.
  8. Re-check periodically: Every 15 minutes, attempt one list_indexed_repositories call. If it succeeds, the server has recovered — exit legacy mode, notify the developer, and resume normal Memtrace operation.

Step 3b: Permission DENIED

If the developer denies permission, does not respond, or gives any response other than "yes":

  1. Acknowledge the decision: "Understood. Abandoning task since Memtrace MCP server is unavailable and legacy fallback was not authorized."
  2. Abandon the task: Do NOT attempt to work around the denial. Do NOT use grep/glob secretly. Do NOT "try anyway."
  3. Discard partial results: Any grep/glob results collected before the halt should be discarded (not trusted without Memtrace verification).
  4. Document the abort: Record that the task was abandoned due to unrecoverable Memtrace failure and denied fallback authorization. Include who made the decision, the timestamp, and the task description.

Legacy Tool Equivalents

When using legacy tools, map Memtrace operations to their text-search equivalents. For any tool not listed here, use grep + glob where applicable or skip the operation:

Memtrace Tool Legacy Equivalent
Discovery
find_code / find_symbol grep / rg for name; glob for file patterns
get_source_window read with offset/limit at known file
get_directory_tree Get-ChildItem -Recurse / ls -R
Dependency
get_impact Manual grep for callers/references (less reliable, no transitive analysis)
get_symbol_context Read surrounding file context; grep for imports and callers
analyze_relationships Manual grep for callers/callees (no graph traversal)
find_dependency_path Manual path tracing via grep (error-prone)
get_api_topology Not available — document as skipped
Quality
find_dead_code Manual reference counting via grep (error-prone, misses dynamic dispatch)
find_most_complex_functions Not available — document as skipped
find_bridge_symbols Not available — document as skipped
find_central_symbols Not available — document as skipped
Temporal
get_evolution Not available in single snapshot — document as skipped
get_changes_since git log --oneline (file-level, not symbol-level)
get_timeline git log --follow <file> (file-level only)
get_episode_replay Not available — document as skipped
Process / Community
list_communities Manual directory inspection
list_processes Not available — document as skipped
get_process_flow Manual code reading (no call-graph traversal)
Index Management
list_indexed_repositories Not applicable — no index available
get_codebase_briefing Manual glob + directory tree inspection
index_directory Not available — document as skipped
watch_directory Not available — document as skipped
delete_repository Not applicable

Confinement Rules

  • ALWAYS request explicit permission before using legacy tools
  • ALWAYS verify server is unreachable via list_indexed_repositories before halting
  • ALWAYS wait up to 5 minutes for a clear "yes" (English only) — any other response denies permission
  • ALWAYS document that legacy fallback was used, structural verification was skipped, and who/when/what authorized it
  • ALWAYS re-check server availability every 15 minutes and exit legacy mode if it recovers
  • ALWAYS re-request permission if the agent session restarts (state is not persisted)
  • NEVER silently fall back to grep/glob without permission
  • NEVER use this skill preemptively — the full recovery chain must be attempted first
  • NEVER call Memtrace MCP tools after entering legacy fallback mode (they will fail)