MAIN CHAT MUST NOT WRITE CODE. This is not negotiable.

Main chat orchestrates the ralph loop. Task agents do the work:

• Investigation: Task agents read code, run tests, gather evidence
• Fixes: Task agents write regression tests and fixes

If you're about to edit code directly, STOP and delegate instead.

The Process

Unlike implementation (per-task loops), debugging uses ONE loop per bug:

1. Start ralph loop for the bug
   Skill(skill="ralph-loop:ralph-loop", args="Debug: [SYMPTOM] --max-iterations 15 --completion-promise FIXED")

2. Inside loop: spawn Task agent for investigation/fix
   → Skill(skill="workflows:dev-delegate")

3. Task agent follows 4-phase debug protocol

4. When regression test passes → output promise
   <promise>FIXED</promise>

5. Bug fixed, loop ends

Step 1: Start Ralph Loop

IMPORTANT: Avoid parentheses () in the prompt.

Skill(skill="ralph-loop:ralph-loop", args="Debug: [SYMPTOM] --max-iterations 15 --completion-promise FIXED")

Step 2: Spawn Task Agent

Use dev-delegate, but with debug-specific instructions:

Task(subagent_type="general-purpose", prompt="""
Debug [SYMPTOM] following systematic protocol.

## Context
- Read .claude/LEARNINGS.md for prior hypotheses
- Read .claude/SPEC.md for expected behavior

## Debug Protocol (4 Phases)

### Phase 1: Investigate
- Add debug logging to suspected code path
- Reproduce the bug with a test
- Document: "Reproduced with [test], output: [error]"

### Phase 2: Analyze
- Trace data flow through the code
- Compare to working code paths
- Document findings in LEARNINGS.md

### Phase 3: Hypothesize
- Form ONE specific hypothesis
- Test it with minimal change
- If wrong: document what was ruled out
- If right: proceed to fix

### Phase 4: Fix
- Write regression test FIRST (must fail before fix)
- Implement minimal fix
- Run test, see it PASS
- Run full test suite

## Output
Report:
- Hypothesis tested
- Root cause (if found)
- Regression test written
- Fix applied (or blockers)
""")

Step 3: Verify and Complete

After Task agent returns, verify:

• Regression test FAILS before fix
• Regression test PASSES after fix
• Root cause documented in LEARNINGS.md
• All existing tests still pass

If ALL pass → output the promise:

<promise>FIXED</promise>

If ANY fail → iterate (don't output promise yet).

The Four Phases

The Gate Function

Before claiming ANY bug is fixed:

1. REPRODUCE → Run test, see bug manifest
2. INVESTIGATE → Trace data flow, form hypothesis
3. TEST → Verify hypothesis with minimal change
4. FIX → Write regression test FIRST (see it FAIL)
5. VERIFY → Run fix, see regression test PASS
6. CONFIRM → Run full test suite, no regressions
7. CLAIM → Only after steps 1-6

Skipping any step is guessing, not debugging.

Rationalization Prevention

These thoughts mean STOP—you're about to skip the protocol:

Fake Fix Verification - STOP

These do NOT prove a bug is fixed:

Red Flag: If you're claiming "fixed" based on absence of errors rather than presence of correct behavior - STOP. That's symptom suppression, not bug fixing.

Red Flags - STOP If You Think:

If Max Iterations Reached

Ralph exits after max iterations. Still do NOT ask user to manually verify.

Main chat should:

1. Summarize hypotheses tested (from LEARNINGS.md)
2. Report what was ruled out and what remains unclear
3. Ask user for direction:
   • A) Start new loop with different investigation angle
   • B) Add more logging to specific code path
   • C) User provides additional context
   • D) User explicitly requests manual verification

Never default to "please verify manually". Always exhaust automation first.

When Fix Requires Substantial Changes

If root cause reveals need for significant refactoring:

1. Document root cause in LEARNINGS.md
2. Complete debug loop with <promise>FIXED</promise> for the investigation
3. Use Skill(skill="workflows:dev") for the implementation work

Debug finds the problem. The dev workflow implements the solution.

Failure Recovery Protocol

Pattern from oh-my-opencode: After 3 consecutive failures, escalate.

3-Failure Trigger

If you attempt 3 hypotheses and ALL fail:

Failure 1: Hypothesis A tested → still broken
Failure 2: Hypothesis B tested → still broken
Failure 3: Hypothesis C tested → still broken
→ TRIGGER RECOVERY PROTOCOL

Recovery Steps

1. STOP all further debugging attempts

   • No more "let me try one more thing"
   • No guessing or throwing fixes at the wall

2. REVERT to last known working state

   • git checkout <last-working-commit>
   • Or revert specific files: git checkout HEAD~N -- file.ts
   • Document what was attempted in .claude/RECOVERY.md

3. DOCUMENT what was attempted

   • All 3 hypotheses tested
   • Evidence gathered
   • Why each failed
   • What this rules out

4. CONSULT with user

   • "I've tested 3 hypotheses. All failed. Here's what I've ruled out..."
   • Present evidence from investigation
   • Request: additional context, different investigation angle, or pair debugging

5. ASK USER before proceeding

   • Option A: Start new ralph loop with different approach
   • Option B: User provides domain knowledge/context
   • Option C: Escalate to more experienced reviewer
   • Option D: Accept this as a blocker and document

NO EVIDENCE = NOT FIXED (hard rule)

Recovery Checklist

Before claiming a bug is fixed after multiple failures:

• At least 1 hypothesis succeeded (not just "stopped failing")
• Regression test exists and PASSES
• Full test suite passes (no new failures)
• Changes are minimal and targeted
• Root cause is understood (not just symptom suppressed)

Anti-Patterns After Failures

DON'T:

• Keep trying random fixes ("maybe if I change this...")
• Expand scope to "related" issues
• Make multiple changes at once
• Skip the regression test "this time"
• Claim fix without evidence

DO:

• Stop and document what failed
• Revert to clean state
• Consult before continuing
• Follow recovery protocol exactly
• Require evidence for completion

Example Recovery Flow

Attempt 1: "Bug is in parser" → Added logging → Still broken
Attempt 2: "Bug is in validator" → Fixed validation → Still broken
Attempt 3: "Bug is in transformer" → Rewrote transform → Still broken

→ RECOVERY PROTOCOL:
1. STOP (no attempt 4)
2. REVERT all changes: git checkout HEAD -- src/
3. DOCUMENT in .claude/RECOVERY.md:
   - Ruled out: parser, validator, transformer
   - Evidence: logs show data correct at each stage
   - Hypothesis: Bug might be in consumer, not producer
4. ASK USER:
   "I've ruled out the parser/validator/transformer chain.
    Logs show data is correct when it leaves our system.
    Next investigation angle: check the consumer.
    Should I:
    A) Start new loop investigating consumer
    B) Pause for your input on where else to look"