Debugging and recovery

Skill aneja5/forge-skills/skills/debugging-and-recovery

Use when something is broken, a test is failing, behavior is wrong, when investigating a production incident, when a user reports a bug, when a feature works locally but not in another environment, or when the system behaves differently than the contract specifies.From its SKILL.md

Install

npx -y skills add aneja5/forge-skills --skill debugging-and-recovery

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

2 things to look at

3 stars3 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
runs commandsInstructs the agent to run 1 command, including `git log -p <files>`.

SKILL.md

3.5 KB, 747 tokens by cl100k_base, as published. Nobody here has run it

Debugging and Recovery

Overview

Reproduce → localize → fix → guard. Never guess at root cause. The fix is not done until a regression test guards it. For bugs with GitHub issues, see triage-issue for the full investigation + issue creation flow.

When to Use

Something broke or behaves unexpectedly
A test is failing and the cause is not obvious
A bug has been reported and needs diagnosis before a fix
An error is ambiguous — multiple possible causes

When NOT to Use

The fix is obvious and well-understood — just implement with tdd
The bug is a missing feature, not broken behavior — use spec-driven-development
You want to preemptively prevent bugs — use code-review-and-quality

Common Rationalizations

Thought	Reality
"I know what the bug is"	You think you do. Reproduce it first.
"I'll just try this fix and see"	Untested fixes introduce new bugs
"The root cause is obvious from the stack trace"	Stack traces show symptoms, not causes
"A unit test would be too hard to write for this"	Write an integration test — the behavior is observable
"The fix is one line, no test needed"	One-line bugs are re-introduced in one line

Red Flags

Fixing before reproducing — you might be fixing the wrong thing
Fix that passes all tests but doesn't change observable behavior
No regression test added — the bug will return
Root cause described as "it just wasn't working" — not a cause
Fix modifies more than what the bug report describes

Core Process

Step 1: Reproduce

Get the minimal reproduction: exact steps, inputs, environment. If you can't reproduce it, you don't understand it. Run the failing scenario manually or via test before writing any fix.

Step 2: Write a failing test

Before fixing:

RED: Write a test that reproduces the bug
     → The test must fail
     → If it passes, your reproduction is wrong

The test proves you understand the bug.

Step 3: Localize

With a failing test, trace the code path:

Where does the expected behavior diverge from actual?
What invariant is being violated?
What recently changed in this code path? (git log -p <files>)
Is it the logic, the data, or the interface contract?

Step 4: Fix — minimum change

Implement the smallest change that makes the failing test pass. Do not refactor adjacent code. Do not fix other bugs you notice. Do not add features.

Step 5: Guard

Run the full test suite. Confirm:

The specific regression test passes
No previously passing tests now fail
The fix doesn't silently break adjacent behavior

Step 6: Document

If the bug was non-obvious: add a comment explaining WHY the fix is correct, not what it does. Consider whether the bug points to a missing contract invariant in .forge/contracts/.

Verification

Bug reproduced before any fix was written
Failing test written that specifically captures the bug
Root cause identified (not just symptom)
Fix is the minimum change to make the test pass
Regression test passes after fix
Full test suite still passes
If contract was violated: .forge/contracts/ updated with the missing invariant

What ships with it

Read from the repository

Just SKILL.md. No reference files, no scripts.

Gives 1 of the 12 instructions most debug triage skills give in 747 tokens

Counted across 1,020 of the 1,639 authors here whose files we hold, read 2026-09-06

Find root cause before attempting any fixin 134 of 1020, across 118 files
Create a failing test case before implementing a fixin 109 of 1020, across 95 files
Read error messages and stack traces completelyin 102 of 1020, across 88 files
Reproduce the issue consistently before investigatingin 90 of 1020, across 77 files
Make the smallest possible change to test a hypothesisin 90 of 1020, across 76 files
Trace data flow backward to find the sourcein 84 of 1020, across 70 files
Form a single hypothesis before testingin 78 of 1020, across 64 files
Implement only one fix at a timein 76 of 1020, across 63 files
Question the architecture if three fixes failin 73 of 1020, across 59 files
Add diagnostic instrumentation at component boundariesin 68 of 1020, across 56 files
Compare broken code against working examplesin 68 of 1020, across 57 files
Write a regression test before applying the fixhere, and in 62 of 1020, across 55 files

Said here and by no other author read

trace the code path to localize the issue
document the reason for the fix

Grouped from the skills themselves: near-identical wordings counted once, and counted by distinct author, so one author publishing three of these counts once. Length counted with cl100k_base; the agent that loads this file may tokenize it differently.