From forge
Systematic root cause analysis before proposing fixes. Reproduce, hypothesize, test, document. Three failed fixes means question the architecture.
npx claudepluginhub caseyrtalbot/forge --plugin forgeThis skill uses the workspace's default tool permissions.
Systematically identify the root cause of a bug or unexpected behavior through hypothesis-driven investigation. Do not guess at fixes. Understand the failure first, then fix it with confidence.
Verifies tests pass on completed feature branch, presents options to merge locally, create GitHub PR, keep as-is or discard; executes choice and cleans up worktree.
Guides root cause investigation for bugs, test failures, unexpected behavior, performance issues, and build failures before proposing fixes.
Writes implementation plans from specs for multi-step tasks, mapping files and breaking into TDD bite-sized steps before coding.
Systematically identify the root cause of a bug or unexpected behavior through hypothesis-driven investigation. Do not guess at fixes. Understand the failure first, then fix it with confidence.
Do NOT propose a fix until you can explain the root cause. "I think this might fix it" is not an investigation result. "The failure occurs because X calls Y with a null argument when Z is empty, as shown by this stack trace" is a root cause. Find the cause first, fix second.digraph trace_fault {
"Reproduce the failure" [shape=box];
"Reproducible?" [shape=diamond];
"Collect error output" [shape=box];
"Form hypothesis" [shape=box];
"Design test for hypothesis" [shape=box];
"Run test" [shape=box];
"Hypothesis confirmed?" [shape=diamond];
"Root cause documented" [shape=box];
"Design fix" [shape=box];
"Invoke prove-first" [shape=doublecircle];
"Reproduce the failure" -> "Reproducible?";
"Reproducible?" -> "Collect error output" [label="yes"];
"Reproducible?" -> "Reproduce the failure" [label="no, vary conditions"];
"Collect error output" -> "Form hypothesis";
"Form hypothesis" -> "Design test for hypothesis";
"Design test for hypothesis" -> "Run test";
"Run test" -> "Hypothesis confirmed?";
"Hypothesis confirmed?" -> "Root cause documented" [label="yes"];
"Hypothesis confirmed?" -> "3+ hypotheses denied?" [label="no"];
"3+ hypotheses denied?" [shape=diamond];
"3+ hypotheses denied?" -> "Form hypothesis" [label="no, next hypothesis"];
"3+ hypotheses denied?" -> "Question architecture" [label="yes"];
"Question architecture" [shape=box];
"Question architecture" -> "Present to user" [label="architectural concern"];
"Present to user" [shape=doublecircle];
"Root cause documented" -> "Design fix";
"Design fix" -> "Invoke prove-first";
}
## Hypothesis Log
### H1: [Description]
**Likelihood**: High/Medium/Low
**Test**: [What to check]
**Result**: Confirmed/Denied/[pending]
**Evidence**: [Output or observation]
### H2: [Description]
...
"Let me try changing this and see if it helps" Shotgun debugging. Each change introduces a new variable. Understand the failure, then make one targeted change.
"The error message says X so the fix is obviously Y" Error messages describe symptoms, not causes. The null pointer exception is a symptom. The missing validation three layers up is the cause.
"I fixed the test to pass" Fixing the test instead of the code means the bug is still there but the alarm is silenced. Unless the test was genuinely wrong, fix the code.
"It works now, not sure why" If you cannot explain why the fix works, you have not found the root cause. You have found a coincidence. Investigate until you can explain the causal chain.
After 3 failed fix attempts on the same bug, STOP. The bug may be architectural. Ask:
Present the architectural concern to the user before attempting a 4th fix. This is not giving up. This is recognizing that repeated symptom-level fixes on an architectural problem will never converge.
For advanced investigation techniques (defense-in-depth, condition-based-waiting, parallel investigation, architecture questioning), see techniques.md.
When the root cause is identified and a fix is designed, invoke prove-first to implement the fix with test-first discipline.