@hanzlaa/rcode 3.6.16 → 4.1.0

package/rcode/agents/rules/debugger/checkpoint-recovery.md

@@ -0,0 +1,272 @@
+# Checkpoint Recovery Protocol
+
+When resuming from a debug checkpoint (after a context reset), use this protocol to get back to productive debugging quickly without losing progress.
+
+---
+
+## Pre-Recovery Checklist
+
+Before resuming, verify:
+
+1. **Session state exists:** `.rcode/debug/session.json` present
+2. **Investigation log exists:** `.rcode/debug/investigation.md` readable
+3. **Session is valid:** Check for corrupt JSON, missing fields
+4. **Current phase is clear:** Read `"phase"` field in session.json
+
+If any are missing, create a minimal session from available evidence.
+
+---
+
+## Recovery Steps by Phase
+
+### Phase: EVIDENCE_GATHERING
+
+You were collecting facts about the bug.
+
+**Recovery:**
+
+1. **Read investigation.md** — What facts have been established?
+2. **Review facts_established array** in session.json
+3. **Pick the next fact to verify:**
+   - Have you checked the exact error message?
+   - Have you reproduced the bug consistently?
+   - Have you traced the code path where it fails?
+   - Have you checked database state, API responses, logs?
+4. **Continue gathering** — Don't re-check facts already established
+5. **Update session.json** with new facts as you discover them
+
+**When to move to next phase:** After 3-5 independent facts support a clear direction.
+
+---
+
+### Phase: HYPOTHESIS_TESTING
+
+You were testing hypotheses to identify root cause.
+
+**Recovery:**
+
+1. **Read hypotheses array** in session.json
+2. **Identify untested hypotheses:**
+   - status: "DISPROVEN" — ignore, already tested
+   - status: "UNTESTED" — test these
+   - status: "CONFIRMED" — might be the root cause
+3. **Resume testing untested hypotheses:**
+   - Pick the most likely next hypothesis
+   - Follow its "How to test" field
+   - Record result: CONFIRMED or DISPROVEN
+4. **Update session.json** with test results
+5. **If CONFIRMED hypothesis found** → move to ROOT_CAUSE phase
+
+**When to move to next phase:** When one hypothesis is CONFIRMED and others are DISPROVEN.
+
+---
+
+### Phase: ROOT_CAUSE_ANALYSIS
+
+You identified the root cause and are understanding it.
+
+**Recovery:**
+
+1. **Read root_cause field** in session.json
+2. **Verify the explanation makes sense:**
+   - Does it explain the symptom?
+   - Are there edge cases it doesn't explain?
+3. **If understanding is incomplete:**
+   - Add follow-up questions to investigation.md
+   - Dig deeper into the code
+   - Update root_cause field with new understanding
+4. **Update session.json:** Set `"root_cause_found": true`
+
+**When to move to next phase:** When you can explain the bug and HOW to fix it.
+
+---
+
+### Phase: FIX_DEVELOPMENT
+
+You were writing and testing a fix.
+
+**Recovery:**
+
+1. **Read fix_applied field** in session.json
+2. **Verify the fix is actually applied:**
+   - Open the file mentioned
+   - Check if the change is there
+   - If not, apply it now
+3. **Run verification steps:**
+   - Follow verification_steps array
+   - Reproduce bug reproducer (should now pass)
+   - Run test suite (should pass)
+4. **If verification fails:**
+   - Revert the fix
+   - Move back to HYPOTHESIS_TESTING (fix was wrong)
+   - Test different hypothesis
+5. **If verification passes:**
+   - Update session.json: `"fix_verified": true`
+   - Move to CHECKPOINT phase
+
+**When to move to next phase:** When fix is applied, tested, and verified.
+
+---
+
+### Phase: CHECKPOINT
+
+You're ready to return to the user with findings.
+
+**Recovery:**
+
+1. **Read checkpoint_reached field** in session.json
+2. **Identify checkpoint type:**
+   - ROOT_CAUSE_FOUND: Root cause identified, no fix yet
+   - DEBUG_COMPLETE: Root cause found, fix applied, verified
+   - VERIFICATION_NEEDED: Fix applied, needs user confirmation
+
+3. **Format the checkpoint message** using template below
+4. **Return the checkpoint to user**
+
+---
+
+## Checkpoint Message Template
+
+Use this template to format your return message:
+
+```markdown
+## CHECKPOINT REACHED
+
+**Type:** [ROOT_CAUSE_FOUND | DEBUG_COMPLETE | VERIFICATION_NEEDED]
+
+**Bug:** [One-line symptom from session.json]
+
+### Investigation Timeline
+- **Phase 1 (Evidence):** [What facts were established]
+- **Phase 2 (Hypotheses):** [Which were tested, which confirmed]
+- **Phase 3 (Root Cause):** [The identified cause]
+
+### Root Cause Analysis
+
+[Detailed explanation of why the bug happens]
+
+### Fix (if available)
+
+[Code change made]
+
+```javascript
+// Before
+[buggy code]
+
+// After
+[fixed code]
+```
+
+### Verification Results
+
+[What was tested and result]
+
+- [ ] Reproducer passes
+- [ ] Test suite passes
+- [ ] No new regressions
+- [ ] Root cause explained
+
+### Awaiting
+
+[What user should do next]
+```
+
+---
+
+## Mid-Phase Actions
+
+### If Facts Conflict
+
+**Situation:** You established "fact A is true" but now found evidence that contradicts it.
+
+**Action:**
+1. Don't discard the original fact
+2. Add the conflicting evidence as a new fact
+3. Update investigation.md with resolution
+4. Update session.json facts_established array
+
+**Example:**
+```
+Fact 1: "API endpoint returns 200"
+Fact 2: "But response body is empty"
+Resolution: "API returns 200 with Content-Length: 0 due to missing response body"
+```
+
+### If Hypothesis Becomes Clearer
+
+**Situation:** You're testing a hypothesis and realize it's too vague or needs refinement.
+
+**Action:**
+1. Split into more specific hypotheses
+2. Add them to hypotheses array in session.json
+3. Prioritize testing the most likely variant first
+4. Record the refinement in investigation.md
+
+**Example:**
+
+Original: "Password validation fails"
+
+Refined into:
+- H1: "Password hash is corrupted"
+- H2: "bcrypt.compare() is missing await"
+- H3: "Password encoding mismatch (UTF-8 vs ASCII)"
+
+### If New Code Change is Needed
+
+**Situation:** During investigation, you identify a secondary bug.
+
+**Action:**
+1. Document it in a separate section: "Secondary Issues Found"
+2. Don't fix it now (stay focused on primary bug)
+3. Create a new debug session for it later
+4. Add to `.rcode/debug/backlog.md` if it's not urgent
+
+---
+
+## Safety Checks Before Proceeding
+
+Before resuming investigation, ask:
+
+1. **Is the session state current?**
+   - Does last update timestamp make sense?
+   - Or has code been changed since last session?
+
+2. **Is the bug still reproducible?**
+   - Has the codebase changed?
+   - Does the exact reproduction still work?
+   - If not, update the steps
+
+3. **Are all hypotheses still valid?**
+   - Has code been changed that makes a hypothesis obsolete?
+   - Update hypotheses array if needed
+
+4. **Is the fix still appropriate?**
+   - If fix was already applied, verify it's still there
+   - Has code changed around the fix?
+   - Do tests still pass?
+
+If answers indicate significant changes, create a fresh debug session.
+
+---
+
+## Resumption Tips
+
+- **Start with the last log line** in investigation.md — it tells you exactly where you left off
+- **Reread the last 3 hypotheses** you tested — they anchor your thinking
+- **Check for "TODO" comments** you left in code or logs
+- **Verify timestamps** — Did investigation pause hours ago or days ago? Helps assess what might have changed
+- **Don't re-read everything** — Jump to the section you were working on, then read backwards to context
+
+---
+
+## When to Create a Fresh Session
+
+If any of these apply, start fresh instead of recovering:
+
+- [ ] Session.json is missing or corrupted
+- [ ] Bug symptoms have changed since original report
+- [ ] Codebase has had major changes (new commits, branch switch)
+- [ ] Investigation paused > 1 week and you're unsure if findings are still valid
+- [ ] You're unable to reproduce the bug anymore
+
+Fresh sessions let you validate assumptions rather than assume they're still true.

package/rcode/agents/rules/debugger/debug-session-state.md

@@ -0,0 +1,261 @@
+# Debug Session State Management
+
+Debug sessions survive context resets by maintaining state in the `.rcode/debug/` directory. This file describes the state schema and recovery protocol.
+
+---
+
+## Session State File
+
+**Location:** `.rcode/debug/session.json`
+
+**Purpose:** Persist debug progress across context resets.
+
+**Schema:**
+
+```json
+{
+  "bug_id": "bug-user-auth-fails",
+  "symptom": "User cannot log in with correct credentials",
+  "reported_at": "2025-04-14T10:30:00Z",
+  "status": "IN_PROGRESS",
+  "phase": "hypothesis-testing",
+  
+  "facts_established": [
+    "Login API endpoint responds with 401 (unauthorized)",
+    "Database query returns correct user record",
+    "Password comparison fails even with correct password",
+    "bcrypt version: 5.1.0"
+  ],
+  
+  "hypotheses": [
+    {
+      "id": "h1",
+      "claim": "Password hash is corrupted in database",
+      "status": "DISPROVEN",
+      "tested_at": "2025-04-14T10:35:00Z",
+      "evidence": "Hashes were created 2 weeks ago, no reports of earlier failures. Spot-checked 3 users' hashes — all valid format."
+    },
+    {
+      "id": "h2",
+      "claim": "bcrypt.compare() call missing await",
+      "status": "CONFIRMED",
+      "tested_at": "2025-04-14T10:45:00Z",
+      "evidence": "Found in src/auth.js line 42: const isValid = bcrypt.compare(...) without await. Comparison returns promise, not boolean."
+    }
+  ],
+  
+  "root_cause_found": true,
+  "root_cause": "Synchronous comparison of bcrypt.compare() return value (promise) treats promise as truthy, bypassing actual password verification",
+  
+  "fix_applied": "Added 'await' keyword to bcrypt.compare() call",
+  "fix_verified": true,
+  "verification_steps": [
+    "Login with correct password → succeeds",
+    "Login with wrong password → fails",
+    "Test suite passes: npm run test -- auth.test.js"
+  ],
+  
+  "checkpoint_reached": "DEBUG_COMPLETE",
+  "checkpoint_reason": "Root cause confirmed, fix verified, no regressions"
+}
+```
+
+---
+
+## Investigation Log
+
+**Location:** `.rcode/debug/investigation.md`
+
+**Purpose:** Human-readable narrative of debugging steps.
+
+**Format:**
+
+```markdown
+# Bug: [Symptom]
+
+**Reported:** [Date]
+**Status:** [IN_PROGRESS | ROOT_CAUSE_FOUND | DEBUG_COMPLETE]
+
+## Symptom
+[What user observed]
+
+## Reproduction Steps
+1. [Step 1]
+2. [Step 2]
+
+## Evidence Gathered
+- [Fact 1]
+- [Fact 2]
+
+## Hypotheses Tested
+
+### Hypothesis 1: [Claim]
+- **Status:** DISPROVEN
+- **Why:** [Reasoning that ruled it out]
+- **Tested:** 2025-04-14 10:35
+
+### Hypothesis 2: [Claim]
+- **Status:** CONFIRMED
+- **Why:** [Evidence supporting it]
+- **Tested:** 2025-04-14 10:45
+
+## Root Cause
+[Explanation of why the bug happens]
+
+## Fix Applied
+[Code change]
+
+```javascript
+[Before]
+↓
+[After]
+```
+
+## Verification
+- [ ] Bug reproducer passes
+- [ ] No regressions (test suite passes)
+- [ ] Root cause understood and documented
+```
+
+---
+
+## Checkpoint Return Format
+
+When returning from a debug session with a checkpoint:
+
+```markdown
+## CHECKPOINT REACHED
+
+**Type:** ROOT_CAUSE_FOUND | DEBUG_COMPLETE | VERIFICATION_NEEDED
+
+**Bug:** [One-line symptom]
+
+**Status:** [Summary of what's been determined]
+
+### Current Investigation
+[What has been tested, what has been ruled out]
+
+### Root Cause (if found)
+[Specific explanation of why bug happens]
+
+### Fix (if applied)
+[Code change made and verification result]
+
+### Awaiting
+[What user must do/confirm to proceed]
+```
+
+**Example:**
+
+```markdown
+## CHECKPOINT REACHED
+
+**Type:** ROOT_CAUSE_FOUND
+
+**Bug:** Login endpoint returns 401 even with correct credentials
+
+**Status:** Root cause identified and fix applied. Awaiting user verification.
+
+### Investigation Summary
+- Tested API response: returns 401 as reported
+- Tested database: user record exists with valid password hash
+- Tested password comparison logic: bcrypt.compare() was missing await
+- Result: promise treated as truthy, bypassing actual verification
+
+### Root Cause
+In `src/auth.js` line 42, the code calls `bcrypt.compare()` without `await`. The promise (always truthy) was being used as the comparison result instead of waiting for the actual boolean result.
+
+```javascript
+// Before (buggy)
+const isValid = bcrypt.compare(password, hash);  // returns Promise, treated as true
+if (isValid) { /* always true, auth bypassed */ }
+
+// After (fixed)
+const isValid = await bcrypt.compare(password, hash);  // returns boolean
+if (isValid) { /* correct behavior */ }
+```
+
+### Verification
+- ✅ Login with correct password → succeeds
+- ✅ Login with wrong password → fails
+- ✅ Test suite passes (npm run test -- auth.test.js)
+- ✅ No other calls to bcrypt.compare() without await
+
+### Awaiting
+Please confirm:
+1. The fix matches your understanding of the problem
+2. You're ready to commit and merge
+Or ask for further investigation if needed.
+```
+
+---
+
+## Session Recovery Protocol
+
+If a debug session crashes or context resets:
+
+1. **Check `.rcode/debug/session.json`** — What phase were we in?
+2. **Read investigation.md** — What's been tried and ruled out?
+3. **Resume from last phase**:
+   - If `phase: "evidence-gathering"` → Continue gathering facts
+   - If `phase: "hypothesis-testing"` → Test remaining hypotheses
+   - If `phase: "fix-verification"` → Verify the applied fix
+4. **Don't re-test disproven hypotheses** — They're ruled out
+5. **Update session state** — Record new progress
+
+---
+
+## State Cleanup
+
+After debug session completes (checkpoint reached or bug closed):
+
+**Keep `.rcode/debug/investigation.md`** — Archive for future reference
+
+**Archive `session.json`** — Rename to `session-[bug-id]-[date].json`
+
+**Example:**
+```bash
+# After debugging bug-user-auth-fails
+mv .rcode/debug/session.json \
+   .rcode/debug/archives/session-user-auth-fails-2025-04-14.json
+```
+
+---
+
+## Multi-Debug Isolation
+
+If debugging multiple bugs in parallel:
+
+Create separate directories:
+
+```
+.rcode/debug/
+  session.json          (current active debug)
+  investigation.md      (current active debug)
+  
+  bug-1/
+    session.json
+    investigation.md
+  
+  bug-2/
+    session.json
+    investigation.md
+```
+
+This prevents one bug's state from overwriting another's.
+
+---
+
+## Schema Validation
+
+Before resuming, verify session.json is valid:
+
+```bash
+# Check required fields
+grep -E "^  \"(bug_id|status|phase)\"" .rcode/debug/session.json
+
+# Validate JSON
+jq empty .rcode/debug/session.json && echo "Valid" || echo "Invalid JSON"
+```
+
+If session.json is corrupted, create a new one from investigation.md.