Debug

Activate When

• /godmode:debug, "why is this happening?", "this doesn't work"

Lessons Integration

Before investigation: read .godmode/lessons.md for known root causes and debugging shortcuts. After session: append lessons about root cause patterns discovered.

The Loop

failing_count = run_tests()  # test_cmd (from stack detection), count failures
current_iteration = 0
skipped = 0

WHILE failing_count > 0 AND skipped = 3: STOP, report partial results

Stuck Criteria

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

Reflective Diagnosis on Stuck

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.

Timeout Per Technique

Max 5 min per technique:
  - Stack trace: read stderr, follow call chain once
  - git bisect: binary search to 5 min without progress → abandon technique, try next

Fix Handoff Protocol

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"

Output Format

Print: Debug: {found} bugs found, {fixed} fixed, {remaining} remaining in {N} iterations. Skipped: {skipped_list}.

Keep/Discard Discipline

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.

Stop Conditions

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)

Hard Rules

1. Reproduce before investigating — no reproduce = no bug. Run the code, read stdout+stderr.
2. Evidence required: file:line + actual vs expected values + reproduce command.
3. One bug at a time. If stuck 3 iterations on same bug, skip it and move on.
4. Max 5 min per technique. All techniques exhausted on a bug = discard it.
5. Hand off specific root causes to /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 ( 3 iterations on one bug: skip, move to next.

Workflow

1. Run test_cmd, count failures — this is the starting bug count.
2. Pick highest-severity bug, reproduce it 3x to confirm it is real (not flaky).
3. Select investigation technique: stack trace, git bisect, state inspection, or binary search.
4. Prove root cause with "5 whys" chain — minimum 3 levels. State file:line, actual vs expected.
5. Hand off to /godmode:fix or apply one-line fix. Verify by re-running failing test + full suite.

Rules

1. Reproduce before investigating. No reproduce = no bug. Run the code, read stdout+stderr, paste the output.
2. Evidence: file:line + actual vs expected values + reproduce command. Found root cause → /godmode:fix.
3. One bug at a time. Don't fix during debug (one-line fixes excepted). If stuck 3 iterations on same bug, skip it.
4. Max 5 min per technique. No progress → abandon technique, try next. All techniques exhausted → discard bug.
5. Hand off specific root causes, not vague descriptions. Include file:line, variable state, and reproduce steps.

Error Recovery

| 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. |

Success Criteria

1. Every reported bug has a proven root cause with file:line and actual-vs-expected values.
2. Fix verified by re-running the originally failing test/command.
3. Full test suite passes after all fixes (no regressions introduced).
4. Skipped bugs documented with reasonstuck and rootcause_unknown.

TSV Logging

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.

Failure Classification

On bug SKIP: classify and append to .godmode/debug-failures.tsv with reason. Failure classes: unreproducible, environment_dependent, insufficient_context, tooling_gap, intermittent.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: arbazkhan971
• Source: arbazkhan971/godmode
• License: MIT

Install and usage instructions live in the source repository linked above.