jungho-git/fs-mcp-failure-recovery

FS MCP Failure Recovery

Overview

Use this skill for the full dated recovery loop: date parameter in, failure queue out, real project fixes, verification, and separate success records. Do not use it for read-only summaries unless the user explicitly asks for audit only.

---

Invocation Contract

Expected user shape:

$fs-mcp-failure-recovery 2026-05-15

Rules:

1. Treat the first YYYY-MM-DD token as the target date.
2. Resolve failures from %USERPROFILE%/.mcp/fs-mcp-failures-YYYY-MM-DD.jsonl.
3. Resolve completed items from %USERPROFILE%/.mcp/fs-mcp-successes-YYYY-MM-DD.jsonl.
4. Use %USERPROFILE%/.mcp/fs-mcp-failure-state.json only as pending-state evidence.
5. If no date is provided, use today in Asia/Seoul and say that assumption.
6. If the dated failure log is missing, report no failure log for that date and stop without creating success records.

Start each run with:

bun %CODEX_HOME%/skills/quality/fs-mcp-failure-recovery/scripts/analyze-date.ts --date 2026-05-15

The analyzer returns unresolved groups after subtracting existing success records. Work from those groups, not from the raw failure log alone.

---

Hook Flow

The hook source is %CODEX_HOME%/hooks.json and %CODEX_HOME%/hooks/fs-mcp-failure-logger/fs-mcp-failure-logger-hook.ts.

1. PostToolUse runs the logger for every tool call.
2. PostToolUse records fs_mcp_tool_failure, fs_mcp_tool_degradation, and fs_mcp_basic_tool_fallback.
3. Stop runs the logger with stop and records negative_fs_mcp_response when the final answer admits fs-mcp was bypassed, substituted, unavailable, or insufficient.
4. The failure log is append-only evidence.
5. The success log is the separate completed-item ledger.

Do not patch the failure log to hide failures. Patch the source project or hook code that caused the failure.

---

Dated Recovery Workflow

1. Run analyze-date.ts --date <YYYY-MM-DD>.
2. Read the top unresolved group: event, tool_name, reason, cwd, sample keys, and transcript paths.
3. Inspect the real project under cwd plus the transcript path when present.
4. Check two to four in-scope paths before editing: normal source path, stronger contract/test path, and one assumption check such as generated output, stale MCP process, or runtime restart.
5. Patch the real source of the failure. If cwd is the fs-mcp project, fix fs-mcp source and generated runtime only when that artifact is the active maintained runtime.
6. Run the smallest command that proves the fix: original fs-mcp call when possible, then project test/type/contract checks that cover the edited path.
7. Build a success input JSON for each verified key. Include changed files and checks.
8. Run record-success.ts --date <YYYY-MM-DD> --input <success-input.json>.
9. Re-run analyze-date.ts --date <YYYY-MM-DD> and confirm the key moved out of unresolved items.

The task is not complete while unresolved items remain for the date unless the final report explicitly marks them unfixed with a blocker and no success record.

---

Failure Classes

Handle event types by cause:

1. fs_mcp_tool_failure: the tool returned an error, failed count, or failure status. Reproduce the tool call and fix the source error.
2. fs_mcp_tool_degradation: a tracked fs-mcp read/search/list call succeeded but returned preview, truncation, omitted, indexed, contextIndex, previewOnly, or similar markers. Fix compaction/output contracts or adjust the logger only when it is a false positive.
3. fs_mcp_basic_tool_fallback: a basic shell/command fallback followed a pending fs-mcp issue. Fix the fs-mcp path first; fallback usage itself is not success.
4. negative_fs_mcp_response: the final assistant response says fs-mcp was bypassed or insufficient. Inspect the transcript, then fix the tooling/workflow cause that forced the negative response.

---

Success Recording

Success input shape:

{
  "key": "failure-key-from-analyze-date",
  "failure_event": "fs_mcp_tool_degradation",
  "failure_timestamp": "2026-05-15T06:25:47.185Z",
  "session_id": "019e...",
  "cwd": "C:/path/to/project",
  "tool_name": "mcp__fs_mcp__read_files",
  "reason": "fs-mcp output degraded or unsuitable",
  "transcript_path": "%CODEX_HOME%/sessions/...",
  "fix_summary": "Patched the project source and regenerated active runtime output.",
  "changed_files": [
    "src/features/context/context-output-compactor.ts"
  ],
  "checks": [
    "bun tests/contracts/tool-result-response.contract.test.js",
    "reran original mcp__fs_mcp__read_files path without preview markers"
  ],
  "notes": "MCP process restarted before final check."
}

Record verified success:

bun %CODEX_HOME%/skills/quality/fs-mcp-failure-recovery/scripts/record-success.ts --date 2026-05-15 --input C:/path/to/success-input.json

record-success.ts appends fs_mcp_failure_resolved to fs-mcp-successes-YYYY-MM-DD.jsonl, fills the dated failure_log path when omitted, and removes the same key from pending state if present. Use --dry-run before writing when the payload is uncertain.

---

Stop Conditions

Stop as complete only when:

1. Every targeted key for the date has a verified source fix or a stated blocker.
2. Verified keys exist in the dated success JSONL.
3. analyze-date.ts --date <YYYY-MM-DD> no longer lists verified keys as unresolved.
4. Actual project edits and validation commands are reported.

Stop as incomplete when:

1. The runtime needs restart before the original failure can be rechecked.
2. The affected project cannot be located from cwd or transcript evidence.
3. A test or original fs-mcp rerun still fails.
4. Only logs were edited or only a summary was produced.

---

Reporting Rules

Final output must separate:

1. date: target date and resolved log paths.
2. analyzed: failure counts, groups, and keys inspected.
3. edited: actual project files changed.
4. validated: commands and original paths rerun.
5. success-recorded: success JSONL path and keys written.
6. remaining: unresolved keys, blockers, or restart requirements.

Never list an item as success without a source fix plus validation evidence. Never delete failure evidence.