@hanzlaa/rcode 3.6.16 → 4.1.0

package/rcode/agents/rules/debugger/investigation-protocol.md

@@ -0,0 +1,298 @@
+# Investigation Protocol for Systematic Debugging
+
+When debugging, follow a structured protocol that combines multiple investigation techniques. Pick the right technique for each phase of the investigation.
+
+---
+
+## Phase 1: Evidence Gathering
+
+**Goal:** Establish facts before forming hypotheses.
+
+### Technique: Reading the Error
+
+Start with the **exact error message**, trace, or symptom.
+
+**Steps:**
+1. Find the exact error (not paraphrased, not guessed)
+2. Read every line of the traceback
+3. Note the file, line number, and function name
+4. Copy the error verbatim — don't sanitize
+
+**Example:**
+- ✅ "TypeError: Cannot read property 'map' of undefined at processUsers (src/api.js:42)"
+- ❌ "The code crashed when processing users"
+
+### Technique: Code Review (Focused)
+
+Read the **exact code** mentioned in the error.
+
+**Steps:**
+1. Open the file at the line mentioned
+2. Read the entire function (not just the line)
+3. Read imports/dependencies
+4. Look for obvious issues (missing null checks, typos, logic errors)
+
+### Technique: Reproduce the Bug
+
+Get the bug to happen consistently.
+
+**Steps:**
+1. Follow the exact steps user described
+2. Document what triggers it (specific input, state, timing)
+3. Try variations (does it happen always, or only sometimes?)
+4. If intermittent, investigate timing/concurrency
+
+**Red Flag:** "I can't reproduce it" = you haven't understood the trigger yet. Keep trying.
+
+---
+
+## Phase 2: Hypothesis Formation
+
+**Goal:** Generate 3+ independent hypotheses before investigating.
+
+### Rule: Write Down Your Hypotheses
+
+Don't hold them in your head. Write them explicitly.
+
+**Format:**
+```
+Hypothesis 1: [Specific claim about root cause]
+Evidence for: [Facts that support this]
+Evidence against: [Facts that contradict this]
+How to test: [Automated check that proves/disproves]
+
+Hypothesis 2: ...
+```
+
+### Rule: Generate Multiple Hypotheses
+
+Generate at least 3 before picking one to test. Why?
+- First hypothesis is often wrong (confirmation bias)
+- Multiple hypotheses prevent tunnel vision
+- Testing one hypothesis can eliminate others
+
+**Example: "Login button doesn't work"**
+
+Hypothesis 1: Network request failing
+- Check: Network tab shows request status
+- Test: Mock API endpoint
+
+Hypothesis 2: Form validation blocking submission
+- Check: Console logs show validation error
+- Test: Fill form with valid data, retry
+
+Hypothesis 3: Click handler not registered
+- Check: Console logs from click event
+- Test: Add debug logs to handler function
+
+---
+
+## Phase 3: Systematic Testing
+
+### Technique: Binary Search (for "which component")
+
+When unsure which piece is broken, use binary search.
+
+**Example: "Payments work, but shipping calculation is wrong"**
+```
+Test 1: Does shipping API respond at all?
+  → Yes
+Test 2: Is the shipping calc using correct input?
+  → No — it's using stale address
+Test 3: Where does stale address come from?
+  → Form component not clearing on checkout start
+```
+
+Each test eliminates half the problem space.
+
+### Technique: Rubber Duck Debugging
+
+Explain the code out loud to an imaginary duck (or your screen).
+
+**Process:**
+1. Read code line by line
+2. State what you expect each line to do
+3. When you find a mismatch, you've found the bug
+
+**Example:**
+- Line 1: `const user = getUserFromId(id)` — "Get user by ID"
+- Line 2: `return user.name` — "Return the user's name"
+- Line 3: `if (user.is_admin)` — Wait, we checked `.name` on line 2, but line 3 assumes `user` exists. But what if `id` doesn't exist? `getUserFromId` might return `null`.
+
+### Technique: Add Logging Strategically
+
+Don't spam logs everywhere. Place them to test specific hypotheses.
+
+**Strategic Logging:**
+1. Log inputs to a suspicious function
+2. Log the result/return value
+3. Log control flow decisions (if branches)
+
+**Example: "Login fails sometimes"**
+```javascript
+// Before login attempt
+console.log('loginAttempt', { email, hasPassword: !!password });
+
+// In login function
+console.log('apiCall', { url, method });
+console.log('apiResponse', { status, body });
+
+// After response
+console.log('loginSuccess', { tokenLength, userId });
+```
+
+Then check logs to see which step fails.
+
+---
+
+## Phase 4: Root Cause Confirmation
+
+### Rule: One Change at a Time
+
+Fix one hypothesized issue, test, observe.
+
+**Why:** Multiple changes mask which one worked (or if any did).
+
+**Example:**
+- ❌ "I added a null check AND updated the API call AND refactored the loop"
+- ✅ "I added a null check. Testing now. If it fixes the issue, I'll commit. If not, I'll revert and try the next hypothesis."
+
+### Rule: Verify the Fix Works
+
+Fix is confirmed when:
+1. **Bug reproducer now passes** — The exact steps that broke it now work
+2. **No regressions** — Tests that passed before still pass
+3. **Root cause is understood** — You can explain WHY the bug happened
+
+**Red Flag:** "I made a change and the bug went away, but I don't know why" = Not fixed, just lucky. Revert and investigate properly.
+
+---
+
+## Common Investigation Patterns
+
+### Pattern 1: Null/Undefined Reference
+
+**Symptoms:** "Cannot read property X of undefined"
+
+**Investigation:**
+1. Find the line that crashed
+2. What variable was being accessed?
+3. Where did that variable come from?
+4. What could make it null/undefined?
+
+**Example:**
+```
+Error: Cannot read property 'name' of undefined at getUserDisplay
+
+Line: return user.name
+
+Where did `user` come from?
+→ const user = fetchUser(id)
+
+What if fetchUser fails?
+→ It returns undefined (no error thrown)
+
+Fix: Check if user exists before accessing user.name
+```
+
+### Pattern 2: Off-by-One Error
+
+**Symptoms:** "Wrong item selected", "loop processes 1 less than expected"
+
+**Investigation:**
+1. Identify the loop or index operation
+2. Trace what indices it uses
+3. Print the range (start, end, count)
+4. Verify it matches expectations
+
+**Example:**
+```
+for (let i = 0; i < items.length - 1; i++) {
+  // This skips the last item!
+  process(items[i]);
+}
+
+Fix: Remove the "- 1"
+```
+
+### Pattern 3: Async/Timing Issues
+
+**Symptoms:** "Sometimes it works, sometimes it doesn't", "Order of events is wrong"
+
+**Investigation:**
+1. Identify all async operations (API calls, timeouts, promises)
+2. Trace the exact order they execute
+3. Identify what SHOULD happen and what ACTUALLY happens
+4. Add timestamps to logs
+
+**Example:**
+```
+// Bad: Race condition
+updateUser(data);  // async
+saveToLocalStorage(data);  // sync, runs before updateUser finishes
+
+// Fixed: Wait for async to finish
+await updateUser(data);
+saveToLocalStorage(data);
+```
+
+### Pattern 4: State Mutation
+
+**Symptoms:** "Changing A affects B somehow", "Undo doesn't work", "Component renders wrong"
+
+**Investigation:**
+1. Find where state is mutated
+2. Check if it's mutated directly or a copy
+3. Verify unrelated changes don't affect state
+
+**Example:**
+```
+// Bad: Mutates shared reference
+const newUsers = users;
+newUsers[0].name = "Updated";  // Also changes original `users`
+
+// Fixed: Create copy
+const newUsers = [...users];
+newUsers[0] = { ...newUsers[0], name: "Updated" };
+```
+
+---
+
+## When to Stop & Restart
+
+After 30 minutes with no progress, consider restarting:
+
+1. **Close all files** — Fresh eyes
+2. **Write down facts** — What you KNOW is true
+3. **Write down ruled-out hypotheses** — What you've eliminated
+4. **Generate NEW hypotheses** — Different from before
+5. **Begin evidence gathering again**
+
+Restarting is not giving up — it's getting unstuck.
+
+---
+
+## Documentation as You Go
+
+Maintain a log in `.rcode/debug/investigation.md`:
+
+```markdown
+## Bug: [Symptom]
+Date: [When investigated]
+
+### Evidence
+- [Fact 1]
+- [Fact 2]
+
+### Hypotheses Tested
+1. [Hypothesis] → DISPROVEN because [evidence]
+2. [Hypothesis] → CONFIRMED because [evidence]
+
+### Root Cause
+[Explanation of why the bug happens]
+
+### Fix
+[Code change + test verification]
+```
+
+This log survives context resets and helps if you return to the bug later.

package/rcode/agents/rules/debugger/scientific-method.md

@@ -0,0 +1,317 @@
+# rcode Debugger: Scientific Method for Bug Investigation
+
+## The Scientific Method in Debugging
+
+Debugging is empirical investigation, not guessing. Follow the scientific method:
+
+1. **Observation** — Describe precisely what happens
+2. **Question** — What could cause this?
+3. **Hypothesis** — Make a specific, testable claim
+4. **Experiment** — Test the hypothesis
+5. **Analysis** — What does the result tell us?
+6. **Conclusion** — Is the hypothesis supported?
+
+---
+
+## Phase 1: Observation (Precise Description)
+
+**Bad observation:** "It's broken"
+**Good observation:** "Login button click does nothing, no error message, form stays visible"
+
+### Documenting Observations
+
+```
+Symptom: User login fails intermittently
+Expected: Form submits, shows loading state, redirects to dashboard
+Actual: Form doesn't submit, button click has no effect
+Frequency: Happens ~30% of the time, not consistent
+When started: Today after deployment, worked yesterday
+Environment: Chrome, macOS, localhost:3000
+Error message: None visible (checked console too)
+```
+
+### Complete Reading Protocol
+
+Read ENTIRE functions, not just "relevant" lines:
+- Read the full function body (not just the error line)
+- Read all imports (missing dependency?)
+- Read function signature (wrong params?)
+- Read calling code (are you using it right?)
+- Read error handler (is it catching too broadly?)
+
+Skimming misses crucial details like:
+```javascript
+// You spot the error here:
+const user = getUserById(userId);  // userId might be undefined
+
+// But you missed this earlier in the function:
+if (someCondition) {
+  userId = null;  // Aha! This sets it to null
+}
+```
+
+---
+
+## Phase 2: Question (What Could Cause This?)
+
+For each observation, list EVERY possible cause (don't judge yet):
+
+**Observation:** Form doesn't submit when clicking button
+
+**Possible causes:**
+1. Click handler never fires (listener not attached)
+2. Click handler fires but form validation fails silently
+3. API call doesn't happen (async issue)
+4. API call fails (network error)
+5. API response causes error (bad data)
+6. Button is disabled (CSS display: none?)
+7. Async/await missing (call doesn't wait)
+8. Event prevention (stopPropagation?)
+9. Race condition (another handler removes button)
+10. Browser issue (console errors hidden)
+
+Write them all down. You'll test them later.
+
+---
+
+## Phase 3: Hypothesis Formation
+
+Transform each possibility into a testable, specific claim:
+
+**Bad (unfalsifiable):**
+- "Something is wrong with the form"
+- "The timing is off"
+- "There's a race condition"
+
+**Good (falsifiable):**
+- "Click handler doesn't fire because addEventListener() wasn't called"
+- "Form validation fails silently because error handler catches all exceptions"
+- "API call completes after unmount, causing state update on unmounted component"
+
+**The difference:** Specificity. Good hypotheses make claims you can test.
+
+### Hypothesis Template
+```
+Hypothesis: [Specific, testable claim]
+
+If TRUE, I should observe:
+  - [Observable evidence 1]
+  - [Observable evidence 2]
+
+If FALSE, I should observe:
+  - [Contradicting evidence]
+
+How to test:
+  - [Specific test steps]
+```
+
+### Example:
+```
+Hypothesis: Click handler doesn't fire because addEventListener() was never called
+
+If TRUE, I should observe:
+  - console.log() inside click handler never executes
+  - Breakpoint in handler never hits
+
+If FALSE, I should observe:
+  - Handler runs but something else prevents submission
+
+How to test:
+  1. Add console.log('Button clicked') at start of handler
+  2. Click button
+  3. Check browser console for log message
+```
+
+---
+
+## Phase 4: Experiment (Design and Run Test)
+
+For each hypothesis, design ONE experiment that tests it:
+
+### Experimental Design Template
+
+```
+Hypothesis: [Claim]
+
+Prediction: If H is true, I will observe [X]
+
+Test Setup:
+  1. [Precondition]
+  2. [Precondition]
+
+Action:
+  1. [Do this]
+  2. [Do that]
+
+Measurement:
+  - What exactly am I measuring?
+  - How do I know if X occurred?
+
+Success Criteria:
+  - Result supports hypothesis: [What would prove it true?]
+  - Result contradicts hypothesis: [What would prove it false?]
+
+Expected Outcome:
+  [What I think will happen]
+
+Actual Outcome:
+  [What actually happened]
+
+Conclusion:
+  [Does this support or refute the hypothesis?]
+```
+
+### Example Test
+
+```
+Hypothesis: Click handler doesn't execute because addEventListener wasn't called
+
+Prediction: console.log inside handler never runs
+
+Test Setup:
+  1. Open browser DevTools Console
+  2. Navigate to login page
+
+Action:
+  1. Click the Login button
+
+Measurement:
+  I'm looking for a console message "Button clicked"
+
+Success if:
+  - No message appears → Handler didn't run → Hypothesis TRUE
+  - Message appears → Handler ran → Hypothesis FALSE
+
+Expected: No message (I think the handler isn't attached)
+
+Actual: Message DOES appear "Button clicked"
+
+Conclusion: Hypothesis is FALSE. Handler DOES execute. Problem is elsewhere.
+```
+
+---
+
+## Phase 5: Analysis (What Does Evidence Tell Us?)
+
+After each experiment:
+
+1. **Record the result** — Exactly what happened, not what you expected
+2. **Compare to prediction** — Did reality match expectation?
+3. **Assess evidence quality** — Strong or weak?
+4. **Extract learning** — What did this rule out? What's new?
+5. **Update mental model** — Based on evidence, what's likely now?
+
+### Evidence Quality
+
+**Strong evidence:**
+- Directly observable (I see X in logs)
+- Repeatable (X happens every time)
+- Unambiguous (Definitely X, not Y)
+- Independent (X happens even without Y)
+
+**Weak evidence:**
+- Hearsay (I think I saw X once)
+- Non-repeatable (X failed once, can't replicate)
+- Ambiguous (Maybe X, could be Y)
+- Confounded (X happened after A AND B AND C)
+
+---
+
+## Phase 6: Hypothesis Refinement
+
+When a hypothesis is **refuted:**
+
+```
+Hypothesis: Click handler doesn't run
+Result: Handler DOES run (console.log proved it)
+
+What this rules out:
+  - addEventListener() missing ✓ (handler runs, so it exists)
+  - Event listener detached ✓
+
+What this reveals:
+  - Handler executes successfully
+  - Problem is AFTER handler, not in handler
+  - Next place: form submission or API call
+
+New hypothesis to test:
+  Form.submit() doesn't actually submit (event default prevented? form validation fail?)
+```
+
+When a hypothesis is **supported:**
+
+```
+Hypothesis: API call fails with 401 error
+Result: Network tab shows POST /api/login returns 401
+
+What this confirms:
+  - Authentication failing (could be: token expired, wrong creds, header missing)
+
+What to test next:
+  - Is Authorization header present?
+  - Is token valid/non-expired?
+  - Are credentials correct?
+```
+
+---
+
+## The Debugging Loop
+
+```
+┌─ Observation (What's broken?)
+│
+├─ Questions (What could cause this?)
+│
+├─ Hypothesis (Specific testable claim)
+│
+├─ Experiment (Test the claim)
+│
+├─ Analysis (What does evidence show?)
+│
+├─ Refine Hypothesis (Based on analysis)
+│
+└─ Repeat until root cause found
+```
+
+---
+
+## Common Mistakes in Scientific Method
+
+### Mistake 1: Falling in Love with First Hypothesis
+**Problem:** You form one hypothesis and spend hours defending it.
+**Fix:** Generate 3+ independent hypotheses before investigating any.
+
+### Mistake 2: Confirmation Bias
+**Problem:** You only look for evidence supporting your hypothesis.
+**Fix:** Actively seek disconfirming evidence. "What would prove me wrong?"
+
+### Mistake 3: Testing Multiple Variables at Once
+**Problem:** You change three things and it works. Which one fixed it?
+**Fix:** Test ONE hypothesis at a time. Change one variable per experiment.
+
+### Mistake 4: Acting on Weak Evidence
+**Problem:** "It seems like maybe this could be..." → You change code.
+**Fix:** Wait for strong, unambiguous evidence before acting.
+
+### Mistake 5: Abandoning Rigor Under Pressure
+**Problem:** "Just let me try this..." without hypothesis/experiment.
+**Fix:** Double down on method when pressure increases. Speed comes from efficiency, not skipping steps.
+
+---
+
+## When to Restart
+
+Consider starting fresh when:
+
+1. **2+ hours, no progress** — You're likely tunnel-visioned
+2. **3+ "fixes" that didn't work** — Your mental model is wrong
+3. **Can't explain current behavior** — Don't layer changes on confusion
+4. **Debugging the debugger** — Something fundamental is wrong
+5. **Fix works but you don't know why** — This isn't fixed, it's luck
+
+Restart protocol:
+1. Close all files and terminals
+2. Write down what you KNOW for certain (not guesses)
+3. Write down what you've RULED OUT
+4. List NEW hypotheses (different from before)
+5. Begin again from Observation phase