@hanzlaa/rcode 2.1.0

package/rihal/agents/rules/debugger/hypothesis-templates.md

@@ -0,0 +1,330 @@
+# Hypothesis Templates for Common Bug Types
+
+When debugging, use these templates to structure hypotheses quickly. Fill in specifics for your bug.
+
+---
+
+## Template 1: Null/Undefined Reference
+
+**Symptom:** "Cannot read property X of undefined" or "TypeError: Y is not a function"
+
+**Hypothesis Template:**
+
+```
+Hypothesis: [Variable Name] is null or undefined
+
+Why it might be true:
+- [Source of variable] can return undefined
+- [Check for null handling]
+
+How to test:
+1. Add log: console.log('${variable}:', ${variable})
+2. Verify log shows null, undefined, or correct value
+3. Check if there's a null check before accessing property
+
+Expected result if true:
+- Log shows undefined or null
+- Code accesses property without checking
+```
+
+**Example:**
+
+```
+Hypothesis: user object is undefined when accessed
+
+Why it might be true:
+- fetchUser() doesn't error on 404, just returns undefined
+- No null check before accessing user.name
+
+How to test:
+1. Add log: console.log('user:', user) before line 42
+2. If user is undefined, add guard: if (user) { ... }
+
+Expected result if true:
+- Log shows "user: undefined"
+- Adding guard fixes the crash
+```
+
+---
+
+## Template 2: Async/Timing Issue
+
+**Symptom:** "Sometimes works, sometimes doesn't", "Race condition suspected"
+
+**Hypothesis Template:**
+
+```
+Hypothesis: [Operation A] starts before [Operation B] completes
+
+Why it might be true:
+- [Operation B] is async but not awaited
+- [Operation A] doesn't wait for [Operation B]'s result
+
+How to test:
+1. Add timestamps: console.time('B') and console.timeEnd('B')
+2. Verify order of logs
+3. Check if A accesses B's results before they're ready
+
+Expected result if true:
+- Logs show A happens before B finishes
+- Adding await/then() fixes the issue
+```
+
+**Example:**
+
+```
+Hypothesis: saveToDatabase() starts before fetchUser() completes
+
+Why it might be true:
+- fetchUser() is async but not awaited
+- saveToDatabase() runs immediately with incomplete data
+
+How to test:
+1. Add: console.time('fetchUser') and console.timeEnd('fetchUser')
+2. Add: console.log('About to save:', data)
+3. Verify order: does "About to save" appear before "fetchUser" completes?
+
+Expected result if true:
+- Logs show saveToDatabase runs before user data loads
+- Adding await fetchUser() fixes inconsistency
+```
+
+---
+
+## Template 3: State Mutation / Reference Sharing
+
+**Symptom:** "Changing A affects B", "Undo doesn't work", "Array modified unexpectedly"
+
+**Hypothesis Template:**
+
+```
+Hypothesis: [Variable A] is a reference to [Variable B], not a copy
+
+Why it might be true:
+- [Variable A] was assigned from [Variable B] directly
+- No copy operation (spread, slice, clone) was used
+
+How to test:
+1. Add: console.log('A before:', A)
+2. Modify A
+3. Add: console.log('B after:', B)
+4. If B changed too, it's a shared reference
+
+Expected result if true:
+- B also changes when A is modified
+- Creating a copy (spread operator, Object.assign) fixes it
+```
+
+**Example:**
+
+```
+Hypothesis: newUsers array is a reference to users array
+
+Why it might be true:
+- const newUsers = users (no spread or copy)
+- Modifying newUsers affects original users
+
+How to test:
+1. console.log('users before:', users)
+2. newUsers[0].name = 'Updated'
+3. console.log('users after:', users)
+4. If users[0].name is 'Updated' too, shared reference confirmed
+
+Expected result if true:
+- users array is modified when newUsers is modified
+- Fix: const newUsers = [...users]
+```
+
+---
+
+## Template 4: Logic Error / Conditional Bug
+
+**Symptom:** "Code takes wrong branch", "Condition never true", "Loop doesn't execute"
+
+**Hypothesis Template:**
+
+```
+Hypothesis: Condition [EXPRESSION] evaluates incorrectly
+
+Why it might be true:
+- [Type comparison issue: == vs ===]
+- [Truthy/falsy misunderstanding]
+- [Logic operator order (AND vs OR)]
+
+How to test:
+1. Add: console.log('[EXPRESSION]:', [EXPRESSION])
+2. Verify actual value vs expected
+3. Check operator precedence
+
+Expected result if true:
+- Log shows condition is false when it should be true
+- Fixing operator or type comparison resolves issue
+```
+
+**Example:**
+
+```
+Hypothesis: Loop condition i < items.length - 1 skips last item
+
+Why it might be true:
+- Loop uses i < items.length - 1 instead of i < items.length
+- Off-by-one error in boundary
+
+How to test:
+1. Add: console.log('Loop at i:', i, 'items.length:', items.length)
+2. Verify if loop stops before processing last item
+3. Count iterations
+
+Expected result if true:
+- Last item is skipped in loop
+- Removing "- 1" processes all items
+```
+
+---
+
+## Template 5: External Dependency Issue
+
+**Symptom:** "Library doesn't work as expected", "API returns wrong format", "Function call fails"
+
+**Hypothesis Template:**
+
+```
+Hypothesis: [Library/API] [does not work / changed behavior] due to [version/configuration]
+
+Why it might be true:
+- Version mismatch between package.json and installed version
+- Configuration was not set
+- API changed in new version
+
+How to test:
+1. Check version: npm list [library]
+2. Check documentation for [version]
+3. Test library in isolation: [test code]
+4. Verify configuration is applied
+
+Expected result if true:
+- Version mismatch or config missing
+- Updating version or config fixes issue
+```
+
+**Example:**
+
+```
+Hypothesis: bcrypt.compare() doesn't work due to missing await
+
+Why it might be true:
+- bcrypt.compare() returns a Promise
+- Code doesn't await the promise
+
+How to test:
+1. Check bcrypt docs: confirm it's async
+2. Test in isolation: const result = await bcrypt.compare(...)
+3. Verify result is boolean, not Promise
+
+Expected result if true:
+- Without await, result is Promise (truthy)
+- With await, result is actual boolean
+```
+
+---
+
+## Template 6: Environment/Configuration Issue
+
+**Symptom:** "Works locally, fails in production", "Missing env variable", "Wrong configuration loaded"
+
+**Hypothesis Template:**
+
+```
+Hypothesis: [Configuration/Env Variable] is missing or incorrect in [Environment]
+
+Why it might be true:
+- Variable not set in [Environment]'s .env file
+- Fallback not provided
+- Wrong value loaded
+
+How to test:
+1. Check: console.log('Config:', process.env.[VAR_NAME])
+2. Verify against .env files
+3. Check if code handles missing config gracefully
+
+Expected result if true:
+- Log shows undefined or wrong value
+- Adding to .env fixes issue
+```
+
+**Example:**
+
+```
+Hypothesis: API_URL is missing in production environment
+
+Why it might be true:
+- .env file not deployed to production
+- Environment variable not set on server
+- Fallback URL doesn't exist
+
+How to test:
+1. SSH to production: echo $API_URL
+2. If empty, environment variable not set
+3. Check if code has fallback for missing API_URL
+
+Expected result if true:
+- $API_URL is empty or unset
+- Setting it in production environment fixes requests
+```
+
+---
+
+## Template 7: Data Format Mismatch
+
+**Symptom:** "Data validation fails", "Type error on valid data", "Parsing fails"
+
+**Hypothesis Template:**
+
+```
+Hypothesis: Input data format [ACTUAL] does not match expected format [EXPECTED]
+
+Why it might be true:
+- API response changed format
+- Database schema doesn't match expectations
+- Type conversion not happening
+
+How to test:
+1. Log the actual data: console.log('Raw input:', JSON.stringify(input, null, 2))
+2. Compare against expected schema
+3. Check parsing/conversion logic
+
+Expected result if true:
+- Log shows format mismatch
+- Adding parsing/validation layer fixes issue
+```
+
+**Example:**
+
+```
+Hypothesis: API returns timestamp as string, code expects number
+
+Why it might be true:
+- API changed response format
+- Timestamp parsing was removed
+- Code assumes number but API returns ISO string
+
+How to test:
+1. Log response: console.log('Timestamp:', response.timestamp, typeof response.timestamp)
+2. Verify API documentation
+3. Check conversion logic
+
+Expected result if true:
+- typeof timestamp is 'string', not 'number'
+- Parsing with new Date(timestamp).getTime() fixes calculations
+```
+
+---
+
+## Using These Templates
+
+1. **Pick the template** matching your symptom
+2. **Fill in specifics** for your bug
+3. **Follow the testing steps** to confirm/disprove
+4. **Record the result** in investigation.md
+
+Don't use hypotheses as crutches — they should guide testing, not replace actual investigation.

package/rihal/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 `.rihal/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.