@shaykec/bridge 0.4.24 → 0.4.26

package/modules/debugging-systematically/content.md

@@ -0,0 +1,139 @@
+# Systematic Debugging — From Symptom to Root Cause
+
+<!-- hint:slides topic="Systematic debugging: observe-hypothesize-test loop, binary search, reading stack traces, and cause vs symptom" slides="5" -->
+
+## The Scientific Method Applied
+
+Debugging is hypothesis-driven. You observe, hypothesize, test, and conclude — then repeat until you find the root cause.
+
+```
+Observe → Hypothesize → Test → Conclude → (repeat if needed)
+```
+
+```mermaid
+flowchart LR
+    A[Observe] --> B[Hypothesize]
+    B --> C[Predict]
+    C --> D[Test]
+    D --> E[Analyze]
+    E --> F{Found?}
+    F -->|No| B
+    F -->|Yes| G[Fix]
+```
+
+## Reproduce First
+
+Before changing anything, **reproduce the bug consistently**. If you can't reproduce it, you can't verify your fix.
+
+- Note exact steps, inputs, and environment
+- Check timing (does it only happen under load?)
+- Capture logs, screenshots, or error messages
+
+## Binary Search for the Cause
+
+Narrow the problem space efficiently:
+
+1. **Halve the input** — Does it fail with half the data? Which half?
+2. **Disable features** — Does it fail with feature X off?
+3. **Bisect history** — Which commit introduced it? (`git bisect`)
+
+```javascript
+// Instead of reading 1000 lines, binary search:
+// 1. Comment out half the code — still fails?
+// 2. Narrow to the half that matters
+// 3. Repeat until you isolate the culprit
+```
+
+## Rubber Duck Debugging
+
+Explain the problem out loud (or to a rubber duck, colleague, or AI). Often the act of explaining reveals the bug before you finish.
+
+"Why would this fail when… oh. I see. The loop starts at 1 but the array is 0-indexed."
+
+## Reading Stack Traces
+
+Stack traces show the **call path** when the error occurred:
+
+```
+Error: Cannot read property 'id' of undefined
+    at UserCard (./src/UserCard.jsx:15:22)
+    at UserList (./src/UserList.jsx:8:14)
+    at App (./src/App.jsx:12:10)
+```
+
+Read **bottom to top**: `App` rendered `UserList`, which rendered `UserCard`, where line 15 accessed `.id` on `undefined`. The bug is likely in `UserCard` (wrong prop) or `UserList` (passing undefined).
+
+## Debugger Tools
+
+### Breakpoints
+Pause execution at a line. Inspect variables, step through.
+
+```javascript
+function calculateTotal(items) {
+  let total = 0;
+  for (const item of items) {
+    total += item.price * item.quantity;  // Breakpoint here
+  }
+  return total;
+}
+```
+
+### Watches
+Monitor expressions (e.g., `item.price`, `total`) as you step.
+
+### Call Stack
+See how you got here. Click frames to jump to caller context.
+
+### Conditional Breakpoints
+Break only when a condition holds (e.g., `item.id === 42`).
+
+## Logging Strategies
+
+| Strategy | Use When |
+|----------|----------|
+| `console.log` | Quick inspection; remove after |
+| Structured logging | Production; levels (debug, info, warn, error) |
+| Correlation IDs | Tracing a request across services |
+| Minimal repro | Log only inputs and outputs around the fault |
+
+```javascript
+// Good: log enough to understand flow
+console.log('calculateTotal input:', { items, count: items.length });
+const total = calculateTotal(items);
+console.log('calculateTotal output:', total);
+```
+
+## Common Pitfalls
+
+| Pitfall | Problem |
+|---------|---------|
+| Fixing symptoms not causes | Patch hides the bug; it returns elsewhere |
+| Assuming without testing | "It must be X" — verify |
+| Changing multiple things | Can't tell what fixed it |
+| Not reproducing first | "Fixed" but bug was intermittent |
+| Giving up too soon | Systematic search almost always finds it |
+
+## Debugging Process Flow
+
+```mermaid
+flowchart TD
+    A[Observe: Symptom] --> B[Reproduce consistently]
+    B --> C[Form hypothesis]
+    C --> D[Design test]
+    D --> E{Test confirms?}
+    E -->|Yes| F[Identify root cause]
+    E -->|No| C
+    F --> G[Fix cause, not symptom]
+    G --> H[Verify fix with repro steps]
+```
+
+---
+
+## Key Takeaways
+
+1. **Reproduce first** — no fix without a reliable repro
+2. **Hypothesize and test** — don't guess randomly
+3. **Binary search** — halve the problem space
+4. **Use the debugger** — breakpoints, watches, call stack
+5. **Fix the cause** — not the symptom
+6. **Rubber duck** — explaining often reveals the answer

package/modules/debugging-systematically/exercises.md

@@ -0,0 +1,91 @@
+# Systematic Debugging Exercises
+
+## Exercise 1: Write a Reproduction Recipe
+
+**Task:** A user reports: "Sometimes the export fails." Write a reproduction recipe that would help you (or a teammate) reliably reproduce the issue. Include: steps, inputs, environment, and what "fails" means.
+
+**Validation:**
+- [ ] Steps are ordered and specific
+- [ ] Inputs are concrete (e.g., "export 50+ items")
+- [ ] Environment noted (browser, OS, data state)
+- [ ] "Fails" is defined (error message, wrong output, hang)
+
+**Hints:**
+1. "Sometimes" suggests timing or data-dependent — capture those
+2. "Export" — what format? What data?
+3. Ask: when does it work vs fail?
+
+---
+
+## Exercise 2: Interpret a Stack Trace
+
+**Task:** Given this stack trace:
+
+```
+RangeError: Invalid array length
+    at Array.fill (native)
+    at createGrid (grid.js:5:12)
+    at initGame (game.js:22:8)
+```
+
+Identify: (a) where it failed, (b) the likely cause, (c) one line of code you'd inspect first.
+
+**Validation:**
+- [ ] Failure at grid.js:5, in createGrid
+- [ ] Array.fill with invalid length — probably negative or NaN
+- [ ] Would check the argument passed to createGrid (likely width/height)
+
+**Hints:**
+1. Array.fill(length) fails if length is negative or non-integer
+2. createGrid probably receives dimensions
+3. initGame calls createGrid — what does it pass?
+
+---
+
+## Exercise 3: Binary Search the Bug
+
+**Task:** A function processItems(items) fails when items has 10,000 elements but works with 100. Describe how you'd binary search to find the threshold (e.g., does 5,000 work? 7,500?).
+
+**Validation:**
+- [ ] Describes halving: try 5000, then 2500 or 7500 based on result
+- [ ] Continues until threshold is found
+- [ ] Understands this finds "when" it breaks, not necessarily "why"
+
+**Hints:**
+1. Test 5000 — pass or fail?
+2. If fail, try 2500; if pass, try 7500
+3. Repeat until you narrow to the boundary
+
+---
+
+## Exercise 4: Hypothesize and Test
+
+**Task:** Bug: "Form validation fails for emails with a '+' character." Write two hypotheses and a test for each.
+
+**Validation:**
+- [ ] Hypothesis 1 is specific (e.g., regex doesn't allow +)
+- [ ] Hypothesis 2 is different (e.g., encoding strips +)
+- [ ] Each test is concrete (e.g., input "a+b@c.com", expect pass)
+
+**Hints:**
+1. Validation could be regex, built-in validator, or backend
+2. + is valid in email local part; some regexes exclude it
+3. URL encoding could alter + if passed in query string
+
+---
+
+## Exercise 5: Cause vs Symptom
+
+**Task:** Bug: "Dashboard shows 0 for today's revenue when there are sales." Proposed fix: "If revenue is 0, display '—' instead."
+
+Explain why this might be a symptom fix. What would you investigate before or in addition to this change?
+
+**Validation:**
+- [ ] Identifies that 0 might be wrong (data/aggregation bug)
+- [ ] Suggests investigating: API response, date range, aggregation logic
+- [ ] Understands display fix can hide a data bug
+
+**Hints:**
+1. Is the data actually 0, or is it a bug in calculation?
+2. Check API, database query, timezone
+3. Display fix is OK for UX, but root cause may need fixing too

package/modules/debugging-systematically/module.yaml

@@ -0,0 +1,46 @@
+slug: debugging-systematically
+title: "Systematic Debugging — From Symptom to Root Cause"
+version: 1.0.0
+description: "Apply the scientific method to debugging: reproduce, hypothesize, test, and conclude."
+category: developer-skills
+tags: [debugging, troubleshooting, problem-solving, developer-tools, root-cause]
+difficulty: beginner
+
+xp:
+  read: 10
+  walkthrough: 30
+  exercise: 20
+  quiz: 15
+  quiz-perfect-bonus: 10
+  game: 25
+  game-perfect-bonus: 15
+
+time:
+  quick: 5
+  read: 15
+  guided: 40
+
+prerequisites: []
+related: [code-review, test-strategy]
+
+triggers:
+  - "How do I debug effectively?"
+  - "How do I find the root cause of a bug?"
+  - "What's a systematic approach to debugging?"
+  - "How do I use breakpoints and debugger tools?"
+
+visuals:
+  diagrams: [diagram-flow, diagram-mermaid]
+  quiz-types: [quiz-drag-order, quiz-timed-choice]
+  game-types: [scenario, speed-round]
+  playground: javascript
+  web-embeds: true
+  slides: true
+
+sources:
+  - url: "https://www.nickjanetakis.com/blog/debugging-9-rules-from-david-j-agans"
+    label: "Debugging — 9 Rules (David Agans summary)"
+    type: docs
+  - url: "https://www.amazon.com/Debugging-David-J-Agans/dp/0814474578"
+    label: "Debugging by David Agans (book)"
+    type: book

package/modules/debugging-systematically/quick-ref.md

@@ -0,0 +1,59 @@
+# Systematic Debugging Quick Reference
+
+## The Loop
+
+```
+Observe → Reproduce → Hypothesize → Test → Conclude → (repeat)
+```
+
+## Reproduce First
+
+| Do | Don't |
+|----|-------|
+| Get exact steps, inputs, environment | Assume you know the repro |
+| Capture logs, errors, screenshots | Fix before reproducing |
+| Note when it works vs fails | Dismiss "sometimes" as unfixable |
+
+## Binary Search
+
+| Target | How |
+|--------|-----|
+| Input/data | Halve the input; which half fails? |
+| Code | Comment out half; narrow to failing half |
+| History | `git bisect` to find introducing commit |
+
+## Stack Traces
+
+| Read | Bottom → Top |
+|------|---------------|
+| Bottom | Entry point (e.g., event handler) |
+| Top | Where it actually failed |
+| Middle | Call path from entry to failure |
+
+## Debugger Basics
+
+| Feature | Use |
+|---------|-----|
+| Breakpoint | Pause at a line |
+| Step over | Run line, stay in current function |
+| Step into | Enter function call |
+| Watches | Monitor expression values |
+| Call stack | See path to current line |
+
+## Common Pitfalls
+
+| Pitfall | Fix |
+|---------|-----|
+| Fix symptom not cause | Find root cause; fix that |
+| Assume without testing | Verify each hypothesis |
+| Change many things at once | One change, one test |
+| No repro | Get one before coding |
+| Give up | Binary search; be systematic |
+
+## Logging
+
+| When | What to log |
+|------|-------------|
+| Quick debug | Inputs and outputs around the fault |
+| Production | Structured; levels; correlation IDs |
+| Minimal repro | Only what's needed to trace the flow |

package/modules/debugging-systematically/quiz.md

@@ -0,0 +1,105 @@
+# Systematic Debugging Quiz
+
+## Question 1
+
+What is the first step in systematic debugging?
+
+A) Fix the most likely cause
+B) Reproduce the bug consistently
+C) Add more logging
+D) Ask someone else
+
+<!-- ANSWER: B -->
+<!-- EXPLANATION: Without a reliable reproduction, you can't verify that your fix works. Reproducing first ensures you understand the problem and can test hypotheses. -->
+
+## Question 2
+
+You see: `TypeError: Cannot read property 'name' of undefined at Profile.jsx:18`. Where should you look first?
+
+A) Line 18 of Profile.jsx — what is undefined?
+B) The file that imports Profile.jsx
+C) The backend API only
+D) The browser console for more errors
+
+<!-- ANSWER: A -->
+<!-- EXPLANATION: The stack trace points to Profile.jsx:18. Something there is undefined when `.name` is accessed. Check what variable or prop is undefined at that line. -->
+
+## Question 3
+
+What does "binary search" mean in debugging?
+
+A) Search for the word "binary" in the code
+B) Halve the problem space (input, code, or history) to isolate the cause
+C) Use a binary file editor
+D) Restart the program repeatedly
+
+<!-- ANSWER: B -->
+<!-- EXPLANATION: Binary search in debugging means repeatedly halving — e.g., comment out half the code, test with half the data, or use git bisect to find the introducing commit. -->
+
+## Question 4
+
+Why is "rubber duck" debugging effective?
+
+A) Ducks are good listeners
+B) Explaining the problem out loud often reveals the bug before you finish
+C) It's faster than using a debugger
+D) It only works for simple bugs
+
+<!-- ANSWER: B -->
+<!-- EXPLANATION: The act of explaining forces you to articulate assumptions and logic. Often you spot the flaw while formulating the explanation. It works for bugs of any complexity. -->
+
+## Question 5
+
+What's wrong with adding a quick fix that hides the symptom?
+
+A) Nothing — if it works, ship it
+B) The root cause may cause other bugs; you also can't verify the fix
+C) Quick fixes are always wrong
+D) It makes the code harder to read
+
+<!-- ANSWER: B -->
+<!-- EXPLANATION: Symptom fixes (e.g., fallbacks) can hide the real bug, which may surface elsewhere. Without a repro, you can't verify the fix. Find and fix the cause when possible. -->
+
+## Question 6
+
+Drag these debugging steps into the correct order:
+
+<!-- VISUAL: quiz-drag-order -->
+
+A) Reproduce → Hypothesize → Test → Conclude → Fix
+B) Fix → Test → Hypothesize → Reproduce
+C) Hypothesize → Fix → Reproduce → Test
+D) Test → Conclude → Reproduce → Hypothesize
+
+<!-- ANSWER: A -->
+<!-- EXPLANATION: Reproduce first to understand the problem. Form a hypothesis. Design and run a test. Conclude (confirm or reject). Fix the root cause. The cycle repeats if the hypothesis was wrong. -->
+
+## Question 7
+
+<!-- VISUAL: quiz-drag-order -->
+
+Put these debugging steps in the correct order:
+
+A) Conclude (confirm or reject hypothesis)
+B) Reproduce the bug consistently
+C) Fix the root cause
+D) Hypothesize the cause
+E) Test the hypothesis
+
+<!-- ANSWER: B,D,E,A,C -->
+<!-- EXPLANATION: First reproduce to understand the problem, then form a hypothesis, design and run a test, conclude based on the result, and finally fix the root cause. The cycle repeats if the hypothesis was wrong. -->
+
+## Question 8
+
+<!-- VISUAL: quiz-drag-order -->
+
+Put these hypothesis-testing steps in the correct flow:
+
+A) Observe the result
+B) Form a falsifiable hypothesis
+C) Design a test that would disprove it
+D) If disproved, form a new hypothesis
+E) If confirmed, fix the root cause
+
+<!-- ANSWER: B,C,A,D,E -->
+<!-- EXPLANATION: Form a falsifiable hypothesis, design a test that could disprove it, run the test and observe, then either form a new hypothesis if disproved or fix the root cause if confirmed. This scientific approach isolates the cause efficiently. -->

package/modules/debugging-systematically/resources.md

@@ -0,0 +1,42 @@
+# Systematic Debugging — Resources
+
+## Videos
+
+- [Debugging: The #1 Skill Most Developers Lack](https://www.youtube.com/watch?v=7jPXOLdYXpg) — Fun Fun Function, ~25 min. Practical debugging mindset and tools.
+- [Debugging with Chrome DevTools](https://developer.chrome.com/docs/devtools/) — Google. Breakpoints, step-through, profiling.
+- [JavaScript Debugging Crash Course](https://www.youtube.com/watch?v=H0XScE08k8U) — Traversy Media. Console, debugger, common patterns.
+
+## Articles and Readings
+
+- [Debugging — David J. Agans (Book Summary)](https://www.nickjanetakis.com/blog/debugging-9-rules-from-david-j-agans) — Nick Janetakis. The 9 rules: understand the system, make it fail, quit thinking and look, divide and conquer, change one thing at a time, keep an audit trail, check the plug, get a fresh view, and if you didn't fix it, it isn't fixed.
+- [Chrome DevTools JavaScript Debugging](https://developer.chrome.com/docs/devtools/javascript/) — Breakpoints, stepping, watch expressions.
+- [JavaScript Debugging Guide (MDN)](https://developer.mozilla.org/en-US/docs/Learn/Common_questions/What_is_browser_developer_tools#javascript_console) — Console and debugger usage.
+- [Git Bisect](https://git-scm.com/docs/git-bisect) — Binary search through commit history to find the bug-introducing commit.
+
+## Books
+
+- **Debugging: The 9 Indispensable Rules for Finding Even the Most Elusive Software and Hardware Problems** by David J. Agans — Classic framework: understand the system, make it fail, quit thinking and look, divide and conquer, and more.
+- **Why Programs Fail** by Andreas Zeller — Systematic debugging, delta debugging, and automated fault localization.
+
+## Tools and Playgrounds
+
+- [Chrome DevTools](https://developer.chrome.com/docs/devtools/) — Breakpoints, step-through, network, profiling. Essential for web debugging.
+- [VS Code Debugger](https://code.visualstudio.com/docs/editor/debugging) — Node.js and browser debugging from the editor.
+- [Git Bisect](https://git-scm.com/docs/git-bisect) — Find the commit that introduced a bug via binary search.
+
+## Podcasts
+
+- [Software Engineering Radio — Debugging Episodes](https://www.se-radio.net/) — Technical discussions on debugging strategies and tooling.
+- [Changelog — Debugging Stories](https://changelog.com/podcast) — Real-world war stories from developers tracking down hard bugs.
+- [CoRecursive — Debugging Tales](https://corecursive.com/) — Long-form stories about memorable bugs and how they were found.
+
+## Interactive and Visual
+
+- [Chrome DevTools — What's New](https://developer.chrome.com/blog/) — Latest debugging features with visual walkthroughs.
+- [Replay.io](https://www.replay.io/) — Time-travel debugger for JavaScript — record, replay, and inspect any point in execution.
+- [Python Tutor](https://pythontutor.com/) — Visualize code execution step-by-step (supports JS, Python, Java, C++).
+
+## Courses
+
+- [Google — Chrome DevTools (free)](https://developer.chrome.com/docs/devtools/overview/) — Comprehensive guides and tutorials on browser debugging.
+- [freeCodeCamp — Debugging Course](https://www.freecodecamp.org/learn/javascript-algorithms-and-data-structures/#debugging) — Free interactive debugging exercises in JavaScript.

package/modules/debugging-systematically/walkthrough.md

@@ -0,0 +1,84 @@
+# Systematic Debugging Walkthrough — Learn by Doing
+
+## Step 1: Reproduce Before You Fix
+
+You hear "the app crashes when I click Submit." You haven't seen it yourself.
+
+**Task:** Before writing any code, what would you do? List at least 3 concrete steps to get a reliable reproduction.
+
+**Question:** Why is "it crashes sometimes" harder to debug than "it crashes when I click Submit with an empty email field"? What changes when you have a precise repro?
+
+**Checkpoint:** The user should list: get exact steps, environment (browser, data), try to reproduce themselves, capture error/logs. They understand that a reliable repro is the foundation.
+
+---
+
+## Step 2: Read a Stack Trace
+
+You see:
+
+```
+TypeError: items.forEach is not a function
+    at processOrder (orderService.js:12:8)
+    at handleCheckout (cart.js:45:22)
+    at onClick (CheckoutButton.jsx:8:15)
+```
+
+**Task:** Interpret this stack trace. Where did the error occur? What's the likely cause? What would you check first?
+
+**Question:** Why does the top of the stack (orderService.js:12) matter more than the bottom? How does the call path help you?
+
+**Checkpoint:** The user identifies: error at `orderService.js:12`, `items` is not an array (maybe null/undefined or wrong type). They'd check what's passed to `processOrder` and where it comes from. They understand bottom = entry, top = failure.
+
+---
+
+## Step 3: Form a Hypothesis
+
+The bug: "Paginated list shows wrong items on page 3." You haven't looked at the code yet.
+
+<!-- hint:card type="tip" title="A testable hypothesis: specific, falsifiable, and suggests a check" -->
+
+**Task:** Write two possible hypotheses. For each, state (a) what you'd check, and (b) a test that would confirm or refute it.
+
+**Question:** What makes a hypothesis "testable"? Why is "maybe it's a bug" not useful?
+
+**Checkpoint:** User's hypotheses are specific (e.g., "off-by-one in page index" or "API returns wrong offset"). Their tests are concrete (inspect API response, log page index). They understand testable = can verify with a check.
+
+---
+
+## Step 4: Binary Search in Code
+
+You have a 200-line function. The bug appears when processing "order #1234" but not "order #1233."
+
+<!-- hint:buttons type="single" prompt="What's your first move to isolate the bug?" options="Bisect by order ID,Comment out half the function,Read line by line from top" -->
+
+**Task:** Describe how you'd use binary search to isolate the problem. What would you try first? Second?
+
+**Question:** Why is binary search faster than reading line-by-line from the top? When might it not work?
+
+**Checkpoint:** User suggests: bisect by order ID range, or comment out half the function and test. They understand that halving reduces search time. They note it may not work if the bug depends on complex interaction.
+
+---
+
+## Step 5: Use the Debugger
+
+You're debugging a function that calculates a total. The total is wrong for a specific input.
+
+**Embed:** https://developer.chrome.com/docs/devtools/javascript/
+
+**Task:** Describe how you'd use breakpoints to find the bug. Where would you set them? What would you inspect? What's the difference between "step over" and "step into"?
+
+**Question:** When is `console.log` enough vs when do you need a real debugger?
+
+**Checkpoint:** User would set a breakpoint in the calculation loop, inspect variables (item, total), step through. Step over = run current line without entering; step into = go inside a function call. Console.log works for simple cases; debugger for loops, async, complex state.
+
+---
+
+## Step 6: Distinguish Cause from Symptom
+
+The bug: "User profile page shows 'undefined' for the avatar." Someone suggests: "Just add a fallback: `avatar || 'default.png'`."
+
+**Task:** Why might that fix be addressing the symptom instead of the cause? What would you investigate before (or in addition to) adding a fallback?
+
+**Question:** When is a defensive fix (like a fallback) acceptable vs when must you fix the root cause?
+
+**Checkpoint:** User recognizes: the real bug could be that the API isn't returning the avatar, or the wrong field is read. A fallback hides the symptom; the underlying bug might cause other issues. Defensive fixes are OK for resilience; root cause should still be found and fixed when possible.