Scientific debugging. Reproduce → investigate → prove root cause. Finds all bugs.
From godmodenpx claudepluginhub arbazkhan971/godmodeThis skill uses the workspace's default tool permissions.
references/debug-workflow.mdDesigns and optimizes AI agent action spaces, tool definitions, observation formats, error recovery, and context for higher task completion rates.
Enables AI agents to execute x402 payments with per-task budgets, spending controls, and non-custodial wallets via MCP tools. Use when agents pay for APIs, services, or other agents.
Compares coding agents like Claude Code and Aider on custom YAML-defined codebase tasks using git worktrees, measuring pass rate, cost, time, and consistency.
/godmode:debug, "why is this happening?", "this doesn't work"Before investigation: read .godmode/lessons.md for known root causes and debugging shortcuts.
After session: append lessons about root cause patterns discovered.
failing_count = run_tests() # test_cmd (from stack detection), count failures
current_iteration = 0
skipped = 0
WHILE failing_count > 0 AND skipped < 3:
current_iteration += 1
bug = pick_highest_severity(remaining_bugs)
technique_index = 0
techniques = [stack_trace, git_bisect, state_inspection, binary_search]
# 1. REPRODUCE — run failing command 3x. Consistent failure = real bug. Intermittent = add to flaky list.
# 2. SELECT TECHNIQUE (max 5 min each):
Stack trace → Trace Analysis | "Used to work" → `git bisect` | Regression → `git log -20`
Intermittent/Wrong results → State Inspection | Unknown → Binary Search (eliminate half)
# 3. INVESTIGATE — insert print/log at suspect file:line. Log: variable name=value, caller, actual vs expected.
# 4. PROVE — state: "Bug is at {file}:{line} because {variable}={actual}, expected {expected}. Reproduce: {cmd}."
Chain: Symptom → Why? → Why? → Root cause → Fix (file:line + diff). Min 3 'why's.
# Root cause found → KEEP (fix or hand off)
# Root cause NOT found → try next technique (step 2)
# All techniques exhausted → DISCARD bug (skip++), log reason_stuck + root_cause_unknown
# 5. FIX OR HAND OFF — see Fix Handoff Protocol below
# 6. VERIFY — re-run failing test. Then run full suite to check for regressions.
# 7. APPEND .godmode/debug-findings.tsv: iteration, bug_id, symptom, root_cause, file:line, fix_commit, status(fixed/skipped), reason_stuck
# 8. STATUS every 3: "{found} found, {failing_count} remaining, {skipped} skipped"
failing_count = run_tests()
IF skipped >= 3: STOP, report partial results
IF stuck >3 iterations on same bug:
→ Discard bug, move to next
→ Log: bug_id, reason_stuck, root_cause_unknown, skipped=true
→ Max skipped bugs: 3. After 3 skipped → stop, report partial
On 3+ iterations without finding root cause:
Read all attempted techniques and their outputs.
Write diagnosis: "Techniques X, Y, Z all assume {wrong assumption}.
The actual constraint is {insight}."
Use diagnosis to select the next technique.
Max 5 min per technique:
- Stack trace: read stderr, follow call chain once
- git bisect: binary search to <10 commits, then manual
- State inspection: add 1-3 logs, reproduce 3x
If >5 min without progress → abandon technique, try next
After proving root cause at file:line:
IF one-line fix: fix it, verify, commit, log
ELSE: call /godmode:fix with proven root cause as context
Hand off SPECIFIC: "Null user.id at src/auth/login.ts:42 when session expires mid-request"
NOT vague: "auth is broken"
Print: Debug: {found} bugs found, {fixed} fixed, {remaining} remaining in {N} iterations. Skipped: {skipped_list}.
After EACH bug investigation:
KEEP if: root cause proven with file:line + actual vs expected values
DISCARD if: root cause not found after all techniques exhausted
On discard: log bug as skipped with reason_stuck. Move to next bug.
Never keep an unproven hypothesis as a root cause.
Loop until target or budget. Never ask to continue — loop autonomously.
On failure: git reset --hard HEAD~1.
STOP when FIRST of:
- target_reached: failing_count == 0 (all bugs fixed or handed off)
- budget_exhausted: max iterations reached
- diminishing_returns: 3 consecutive bugs produce no fix
- stuck: >5 skipped bugs (skipped >= 3 already triggers stop)
/godmode:fix, not vague descriptions.# Common debug commands
npm test 2>&1 | tail -20
git bisect start HEAD HEAD~20
git log --oneline -10
IF test failures > 10: prioritize by severity, fix critical first. WHEN intermittent failure (< 50% reproduce rate): add to flaky list. IF stuck > 3 iterations on one bug: skip, move to next.
test_cmd, count failures — this is the starting bug count./godmode:fix or apply one-line fix. Verify by re-running failing test + full suite./godmode:fix.| Failure | Action |
|---|---|
| Cannot reproduce the bug | Run failing command 3x. If intermittent, add to flaky list with timestamp and environment details. Move to next bug. |
git bisect fails (no good commit) | Fall back to git log -20 manual inspection. Check for config or environment drift rather than code changes. |
| Debug logs produce no useful output | Increase log granularity — log variable values, not only "reached here". Add caller info and stack depth. |
| Root cause spans multiple files | Use the "5 whys" chain. Trace data flow from symptom backward. Document each hop in the chain. |
Append to .godmode/debug-findings.tsv:
iteration bug_id symptom root_cause file_line fix_commit status reason_stuck
One row per bug investigated. Status: fixed, skipped, handed_off.
On bug SKIP: classify and append to .godmode/debug-failures.tsv with reason.
Failure classes: unreproducible, environment_dependent, insufficient_context, tooling_gap, intermittent.