superforge-debug

Superforge Debug — Systematic Debugging & FailForward Memory Engine

Use this skill whenever an error, bug, test failure, or unexpected behavior occurs. NEVER apply trial-and-error edits or mask symptoms with dummy fallbacks.

---

1. FailForward Memory Pre-Flight (Mandatory)

Before forming diagnostic hypotheses, read the project's failure log:

docs/failforward.md — committed, in the repository. This is the memory, and it works whether or not any CLI is installed. Thirty seconds of reading it before hypothesising is the entire reason it exists, because the thing it records is not the list of past fixes but the list of past wrong first guesses, and those repeat.

If the local FailForward CLI is available, query it as well:

failforward recall "<error keyword or component name>"

If a relevant past failure is recalled:

• Apply the verified lesson immediately.
• Mark as useful via failforward useful <id>.

The file's entry format, and why the Looked like line is the one that pays → references/failforward.md.

---

2. 4-Phase Empirical Debugging Protocol

Phase 1 — Log Extraction & Inspection

• Read the FULL, un-truncated log or stack trace.
• Extract exact error symbols, line numbers, and file locations.

Phase 2 — Reproduce & Isolate

• Isolate the minimal reproduction case.
• Trace upstream data flow to pinpoint where the contract was broken.
• If it will not reproduce, do not proceed to Phase 3 — a fix formulated without a reproduction cannot be verified. Narrow what "sometimes" means, match the environment one variable at a time, or instrument and wait (references/failforward.md §2). For "it used to work", stop reasoning about the code and bisect (§3 there).

Phase 3 — Root-Cause Fix Formulation

• Diagnose based strictly on empirical log evidence.
• Fix the underlying contract failure. Never swallow exceptions or bypass assertions.

Phase 4 — Verification & FailForward Recording

• Run tests to confirm clean success — and re-run the original reproduction, not only the new test.
• Append the entry to docs/failforward.md, including Looked like and Locked by (write 無し deliberately if no test locks it).
• If the CLI is present, record it there too:

  failforward record \
    --category <build|type|test|lint|logic|debug|other> \
    --severity <p0|p1|p2|p3> \
    --symptom "<What happened>" \
    --cause "<Why it happened>" \
    --fix "<How it was fixed>" \
    --context "<File/function>" \
    --scope project