agileflow 4.0.0-alpha.2 → 4.0.0-alpha.21

package/content/plugins/debugging/skills/agileflow-debug/references/common-patterns.md

@@ -0,0 +1,350 @@
+# Common Bug Patterns Reference
+
+**Load this when:** you've isolated a bug to a general category and want to match it to known patterns, or when you want to check if the current bug is an instance of a recurring type.
+
+---
+
+## Category 1: Null and undefined errors
+
+The most common category. Almost always caused by an assumption that a value will exist.
+
+### Pattern 1.1: DB query returning null unexpectedly
+
+**Symptom:** `TypeError: Cannot read properties of null` on a field of a database result
+
+**Cause:** The record doesn't exist in the database, but the code assumed it always would.
+
+```js
+// Bug
+const user = await User.findById(req.params.id);
+return res.json({ name: user.name }); // TypeError if user is null
+
+// Fix
+const user = await User.findById(req.params.id);
+if (!user) return res.status(404).json({ error: "User not found" });
+return res.json({ name: user.name });
+```
+
+**Root cause:** Missing null check after a database lookup that can return null.
+
+### Pattern 1.2: Optional chaining pitfall
+
+**Symptom:** Code with `?.` returns `undefined` but code downstream doesn't handle it.
+
+```js
+// Bug: silently returns undefined, downstream code crashes
+const email = user?.profile?.contact?.email;
+await sendWelcome(email); // email is undefined; sendWelcome crashes or sends to undefined
+
+// Fix: guard before using the result
+const email = user?.profile?.contact?.email;
+if (!email) throw new Error(`User ${user.id} has no email address`);
+await sendWelcome(email);
+```
+
+### Pattern 1.3: Array empty result not handled
+
+```js
+// Bug: assumes at least one result
+const admins = await User.findAll({ where: { role: "admin" } });
+const primaryAdmin = admins[0]; // undefined if admins is []
+await notifyAdmin(primaryAdmin.email); // crash
+
+// Fix
+if (admins.length === 0) throw new Error("No admin users found");
+```
+
+---
+
+## Category 2: Async / Promise errors
+
+### Pattern 2.1: Missing await
+
+**Symptom:** Code behaves as if it's using a default/empty value, then later operations fail.
+
+```js
+// Bug: result is a Promise, not the actual value
+const user = User.findById(id); // missing await
+console.log(user.name); // Promise object doesn't have .name
+
+// Fix
+const user = await User.findById(id);
+```
+
+**How to spot it:** Look for property access on a variable that holds a Promise. TypeScript catches this if types are correct.
+
+### Pattern 2.2: Fire and forget (unhandled rejection)
+
+**Symptom:** Silent failure — something should happen but doesn't; sometimes shows as `UnhandledPromiseRejection` in logs.
+
+```js
+// Bug: if sendEmail rejects, nobody knows
+emailService.sendWelcome(user.email);
+
+// Fix option 1: await and handle
+await emailService.sendWelcome(user.email);
+
+// Fix option 2: intentional fire-and-forget with error logging
+emailService.sendWelcome(user.email).catch((err) => {
+  logger.error("Failed to send welcome email", { userId: user.id, err });
+});
+```
+
+### Pattern 2.3: Promise.all short-circuit
+
+**Symptom:** One of several parallel operations fails, but the error is confusing because it mentions a different operation.
+
+```js
+// Bug: if any one fails, ALL results are lost; error message may reference the wrong one
+const [orders, invoices, payments] = await Promise.all([
+  getOrders(userId),
+  getInvoices(userId),
+  getPayments(userId), // this one fails
+]);
+
+// Fix: if partial results are acceptable, use Promise.allSettled
+const results = await Promise.allSettled(
+  [getOrders, getInvoices, getPayments].map((fn) => fn(userId)),
+);
+const [orders, invoices, payments] = results.map((r) =>
+  r.status === "fulfilled" ? r.value : null,
+);
+```
+
+---
+
+## Category 3: Race conditions
+
+### Pattern 3.1: Check-then-act (TOCTOU)
+
+**Symptom:** Intermittent duplicate records or constraint violation errors.
+
+```js
+// Bug: another request can insert between the check and the insert
+const existing = await User.findByEmail(email);
+if (existing) throw new Error("Email already taken");
+await User.create({ email }); // another request may have inserted by now
+
+// Fix: use a unique constraint in the database + catch the constraint error
+try {
+  await User.create({ email });
+} catch (err) {
+  if (err.code === "ER_DUP_ENTRY" || err.constraint === "users_email_key") {
+    throw new ConflictError("Email already taken");
+  }
+  throw err;
+}
+```
+
+### Pattern 3.2: Shared in-memory state across async operations
+
+**Symptom:** Data from request A appears in request B's response.
+
+```js
+// Bug: object modified across async boundary — shared between requests
+const cache = {}; // module-level — shared across ALL requests
+
+app.get("/user/:id", async (req, res) => {
+  cache.currentUserId = req.params.id; // BUG: shared state
+  const user = await getUser(cache.currentUserId); // may get wrong ID
+  res.json(user);
+});
+
+// Fix: keep state per-request, not at module level
+app.get("/user/:id", async (req, res) => {
+  const userId = req.params.id; // request-scoped variable
+  const user = await getUser(userId);
+  res.json(user);
+});
+```
+
+### Pattern 3.3: Increment / decrement race
+
+**Symptom:** Counter or balance goes negative or to wrong value under concurrent load.
+
+```sql
+-- Bug: both requests read balance=100, both subtract 80, both update to 20
+-- instead of one update failing
+UPDATE accounts SET balance = balance - 80 WHERE id = 5;
+
+-- Fix: use a conditional update and check rows affected
+UPDATE accounts SET balance = balance - 80 WHERE id = 5 AND balance >= 80;
+-- If 0 rows updated: insufficient balance
+```
+
+---
+
+## Category 4: Type and coercion bugs
+
+### Pattern 4.1: Loose equality causing incorrect branching
+
+```js
+// Bug: 0 is falsy — empty cart treated as "no cart found"
+if (!cartCount) return res.json({ empty: true }); // fires when cartCount === 0
+
+// Fix: explicit comparison
+if (cartCount === null || cartCount === undefined)
+  return res.json({ empty: true });
+```
+
+### Pattern 4.2: String/number confusion from external input
+
+```js
+// Bug: URL param is always a string
+app.get("/items/:page", (req, res) => {
+  const page = req.params.page; // "1" (string)
+  const offset = page * 10; // "1" * 10 = 10 (works, implicit coercion)
+  const nextPage = page + 1; // "11" (string concat!) ← bug
+});
+
+// Fix: always parse external inputs
+const page = parseInt(req.params.page, 10);
+if (isNaN(page) || page < 1)
+  return res.status(400).json({ error: "Invalid page" });
+```
+
+### Pattern 4.3: JSON parse / stringify precision loss
+
+```js
+// Bug: JavaScript numbers lose precision beyond 2^53
+const id = JSON.parse('{ "id": 9007199254740993 }').id;
+console.log(id); // 9007199254740992 — wrong!
+
+// Fix: use a JSON bigint-aware parser, or return IDs as strings
+```
+
+---
+
+## Category 5: State management bugs
+
+### Pattern 5.1: Stale closure
+
+**Symptom:** A variable in an event handler or callback has the wrong (old) value.
+
+```js
+// Bug: `count` in the closure is from when the handler was created
+let count = 0;
+button.addEventListener("click", () => {
+  count++;
+  setTimeout(() => {
+    console.log(count); // always logs the count from when setTimeout was called, not when it fires
+  }, 1000);
+});
+
+// Fix: use a ref (React), use useCallback/useRef, or read from state on every access
+```
+
+### Pattern 5.2: Mutating props / arguments
+
+```js
+// Bug: mutates the input object — caller's data is changed
+function normalise(user) {
+  user.email = user.email.toLowerCase(); // ← modifies the original
+  return user;
+}
+
+// Fix: return a new object
+function normalise(user) {
+  return { ...user, email: user.email.toLowerCase() };
+}
+```
+
+---
+
+## Category 6: Date and time bugs
+
+### Pattern 6.1: Timezone mismatch
+
+**Symptom:** Timestamps off by hours; date comparisons fail in certain timezones.
+
+```js
+// Bug: new Date() uses local timezone; server and client may differ
+const today = new Date().toISOString().slice(0, 10); // '2025-01-01' in UTC but not in UTC+10
+
+// Fix: always work in UTC; use a library (date-fns, Temporal) for date arithmetic
+import { format } from "date-fns";
+import { utcToZonedTime } from "date-fns-tz";
+const today = format(utcToZonedTime(new Date(), "UTC"), "yyyy-MM-dd");
+```
+
+### Pattern 6.2: DST boundary bugs
+
+**Symptom:** Duration calculations off by 1 hour on daylight saving transition dates.
+
+```js
+// Bug: day duration calculation using milliseconds breaks at DST boundary
+const msInDay = 24 * 60 * 60 * 1000;
+const daysDiff = (end - start) / msInDay; // may be 22/23/25 hours on DST day
+
+// Fix: use a date library that handles DST
+import { differenceInDays } from "date-fns";
+const daysDiff = differenceInDays(end, start);
+```
+
+---
+
+## Category 7: Off-by-one errors
+
+### Pattern 7.1: Loop boundary
+
+```js
+// Bug: should process items 0..9 (10 items), but < vs <= is wrong
+for (let i = 0; i <= items.length; i++) { // ← goes one past the end
+  process(items[i]); // items[10] is undefined on 10-item array
+}
+
+// Fix
+for (let i = 0; i < items.length; i++) {
+```
+
+### Pattern 7.2: Slice/substring index
+
+```js
+// Bug: slice(1, n) vs slice(0, n) vs slice(0, n-1) confusion
+const first10 = str.slice(1, 10); // skips the first character!
+
+// Fix
+const first10 = str.slice(0, 10);
+```
+
+### Pattern 7.3: Pagination offset
+
+```js
+// Bug: page 1 returns items 1-10, page 2 returns 11-20... but item 1 is index 0
+const offset = page * pageSize; // page 1 → offset 10 → skips first 10 items!
+
+// Fix
+const offset = (page - 1) * pageSize; // page 1 → offset 0
+```
+
+---
+
+## Category 8: Import / module bugs
+
+### Pattern 8.1: Circular dependency
+
+**Symptom:** A module exports `undefined` or an incomplete object.
+
+```js
+// a.js imports b.js, b.js imports a.js
+// One of them will receive an incomplete module at require time
+// Symptom: SomeClass is undefined at runtime, no error at import time
+
+// Fix: break the cycle by extracting shared code into a third module
+// Or use lazy imports (import inside the function, not at the top)
+```
+
+### Pattern 8.2: Named vs default export confusion
+
+```js
+// module.js
+export const foo = () => {}; // named export
+export default function bar() {} // default export
+
+// Bug: wrong import style
+import foo from "./module"; // gets the default export (bar), not foo!
+
+// Fix
+import { foo } from "./module"; // named import
+import bar from "./module"; // default import
+```

package/content/plugins/debugging/skills/agileflow-debug/references/debugging-strategies.md

@@ -0,0 +1,328 @@
+# Debugging Strategies Reference
+
+**Load this when:** choosing how to approach a specific type of bug, picking the right tools for the environment, or deciding between debugging strategies.
+
+---
+
+## Strategy selection guide
+
+| Symptom                                | Best strategy                                          |
+| -------------------------------------- | ------------------------------------------------------ |
+| Clear error message with stack trace   | Error analysis → trace the call stack                  |
+| "Works on my machine"                  | Environment diff → compare configs, versions, env vars |
+| Intermittent / flaky                   | Race condition analysis or timing investigation        |
+| Regression (worked before, broken now) | Git bisect / diff against last known good commit       |
+| Performance issue                      | Profiling → find the hot path                          |
+| Failing test                           | Test isolation → run single test, add verbose output   |
+| Black box (no source access)           | Network inspection, log analysis                       |
+
+---
+
+## Strategy 1: Stack trace analysis
+
+**When:** You have an error message with a stack trace.
+
+**Steps:**
+
+1. Find the first frame that is YOUR code (not framework, not node_modules)
+2. Open that file and go to that line
+3. Read the error message literally — it tells you what was wrong at that point
+4. Ask: "What should the value have been here?"
+5. Trace backward through the call chain to find where the value became wrong
+
+**Frame filtering guide:**
+
+```
+// Ignore these frames (they're framework internals):
+at Object.Module._extensions..js (node:internal/modules/cjs/loader:1217:10)
+at Module.load (node:internal/modules/cjs/loader:1033:32)
+at Router.handle (express/lib/router/index.js:284:7)
+
+// This is YOUR code — start here:
+at UserService.getUser (src/services/user-service.js:47:23)
+at async UserController.handleGet (src/controllers/user.js:22:18)
+```
+
+**Error message translations:**
+
+```
+TypeError: Cannot read properties of undefined (reading 'id')
+→ Some object you expected to exist is undefined.
+→ Find the variable named just before .id — what should it have contained?
+
+ReferenceError: X is not defined
+→ Variable X is used before it was declared, or is out of scope
+→ Check imports / const declarations
+
+UnhandledPromiseRejection: ...
+→ An async function threw and no .catch() or try/catch caught it
+→ Find the Promise chain and add error handling
+
+ENOENT: no such file or directory
+→ File path is wrong — log the full path value and check if the file actually exists
+→ Check working directory assumptions: paths may be relative to unexpected root
+
+SyntaxError: Unexpected token '<'
+→ Usually means the server returned HTML (error page) where JSON was expected
+→ Check the HTTP response status and body before parsing as JSON
+```
+
+---
+
+## Strategy 2: Binary search (divide and conquer)
+
+**When:** The bug is somewhere in a large code path and you don't know where.
+
+**Steps:**
+
+1. Mark the **start** — a point where the data is definitely correct
+2. Mark the **end** — a point where the data is definitely wrong
+3. Add a probe (log statement or assertion) at the **midpoint** of the path
+4. Run and check: is the data correct at the midpoint?
+   - Correct → bug is in the second half (move start to midpoint)
+   - Wrong → bug is in the first half (move end to midpoint)
+5. Repeat until the range narrows to 1–2 lines
+
+**Example:**
+
+```
+Input: { userId: 5 }        ← correct here
+  │
+  │ ← bug is somewhere in here
+  │
+Output: { userId: null }    ← wrong here
+
+Binary search:
+  Step 1: Add log at middleware (middle of stack)
+          → userId: 5 ← correct at midpoint
+          → Bug is in the bottom half (controller/service layer)
+
+  Step 2: Add log at service entry
+          → userId: 5 ← still correct
+          → Bug is in the query or return path
+
+  Step 3: Log the DB query result
+          → Row: { id: 5, name: 'Alice' } ← correct
+          → Log the mapped output: { userId: null } ← wrong here
+          → Bug is in the mapper function
+```
+
+---
+
+## Strategy 3: Git bisect (regression isolation)
+
+**When:** Something worked before and is broken now; you know the last good commit.
+
+```bash
+# Start bisect
+git bisect start
+
+# Mark current (broken) state
+git bisect bad
+
+# Mark the last known good commit
+git bisect good v1.2.0   # or specific commit hash
+
+# Git will checkout a midpoint commit
+# Test whether the bug exists
+npm test  # or run the app and reproduce manually
+
+# Tell git the result
+git bisect bad    # still broken
+# or
+git bisect good   # works here
+
+# Repeat until git identifies the commit
+# Git will say: "abc123 is the first bad commit"
+
+# When done
+git bisect reset
+```
+
+**Once you have the commit:**
+
+- Read the commit diff: `git show abc123`
+- The bug is introduced by one of those changes
+- If it's not obvious, read each changed file
+
+---
+
+## Strategy 4: Environment comparison
+
+**When:** "Works on my machine" — local works, staging or production doesn't.
+
+**Diff checklist:**
+
+| Category                         | Check                                                               |
+| -------------------------------- | ------------------------------------------------------------------- |
+| Node / Python / language version | `node --version` on both environments                               |
+| Dependencies                     | `npm ls` or `pip freeze` — are versions pinned?                     |
+| Environment variables            | Compare `.env` vs production env vars (without values)              |
+| Database state                   | Is the data different? Is there a migration that didn't run?        |
+| File permissions                 | Does the app have the right permissions in production?              |
+| Memory / CPU limits              | Is the app hitting resource limits in production?                   |
+| External services                | Is the external API configured differently (sandbox vs production)? |
+| Timezone                         | Server timezone may differ; check date calculations                 |
+| Network                          | Is there a proxy or firewall in production?                         |
+
+---
+
+## Strategy 5: Rubber duck debugging
+
+**When:** You're stuck and can't form a hypothesis.
+
+Talk (or write) through the problem as if explaining it to someone who doesn't know the code:
+
+1. "The function `getUserOrders` takes a `userId` and should return..."
+2. "It works when the user has orders, but fails when..."
+3. "Looking at line 47, it does X, which assumes Y..."
+4. "Wait — it assumes Y, but Y might not be true if..."
+
+The act of articulating the problem in full sentences often reveals the assumption that's wrong.
+
+---
+
+## Strategy 6: Logging strategy
+
+**When:** You need to understand the state of the system at runtime without a debugger.
+
+**The three-point log pattern:**
+
+```js
+// 1. Log at entry: what went in?
+console.log("[getUser] input:", { userId, context });
+
+// 2. Log at decision points: what path is being taken?
+console.log("[getUser] cache_hit:", cacheHit, "cache_key:", cacheKey);
+
+// 3. Log at exit: what came out?
+console.log("[getUser] result:", result, "duration_ms:", Date.now() - start);
+```
+
+**Structured logging for easier grep:**
+
+```js
+// Add a prefix so you can grep just your debug lines
+logger.debug({ event: "get_user", userId, hit: cacheHit });
+```
+
+**Remove debug logs before committing.** Add a `// DEBUG` comment if you're not sure — makes them easy to find and delete.
+
+---
+
+## Strategy 7: Profiling (performance bugs)
+
+**When:** The app is slow and you need to find the bottleneck.
+
+**Node.js profiling:**
+
+```bash
+# CPU profile
+node --prof app.js            # generates isolate-*.log
+node --prof-process isolate-*.log > profile.txt
+# Look for functions with high "self" time
+
+# Or use clinic.js for easier output
+npx clinic flame -- node app.js
+```
+
+**Database profiling:**
+
+```sql
+-- PostgreSQL: find slow queries
+SELECT query, calls, mean_exec_time, total_exec_time
+FROM pg_stat_statements
+ORDER BY total_exec_time DESC
+LIMIT 20;
+
+-- Explain a specific query
+EXPLAIN ANALYZE SELECT * FROM orders WHERE user_id = 5;
+-- Look for: Seq Scan (missing index), high actual rows vs estimated rows
+```
+
+**Python profiling:**
+
+```python
+import cProfile
+import pstats
+
+with cProfile.Profile() as pr:
+    result = slow_function()
+
+stats = pstats.Stats(pr)
+stats.sort_stats('cumulative')
+stats.print_stats(20)  # top 20 by cumulative time
+```
+
+---
+
+## Strategy 8: Network / HTTP debugging
+
+**When:** The bug involves an API call or network request.
+
+**Tools:**
+
+```bash
+# Inspect actual HTTP request/response
+curl -v https://api.example.com/users/1 \
+  -H "Authorization: Bearer ${TOKEN}"
+# -v shows request headers and response headers
+
+# With timing breakdown
+curl -w "@curl-format.txt" -o /dev/null -s https://api.example.com/
+# curl-format.txt: time_namelookup, time_connect, time_appconnect, etc.
+
+# Node: log HTTP requests with debug flag
+DEBUG=axios* node app.js   # for axios
+NODE_DEBUG=http node app.js # for built-in http module
+```
+
+**In browser DevTools:**
+
+1. Network tab → find the failing request
+2. Click it → check: Status code, Response body, Request headers
+3. Common: `401` (auth token expired or missing), `400` (request body malformed), `500` (server error — check server logs)
+
+---
+
+## Debugger usage (interactive)
+
+**Node.js (built-in debugger):**
+
+```bash
+# Start with debugger
+node --inspect-brk src/index.js
+
+# Then open Chrome → chrome://inspect → click "Open dedicated DevTools for Node"
+# Set breakpoints in source files
+# Use the call stack panel to see the state at any point
+```
+
+**VS Code launch.json:**
+
+```json
+{
+  "type": "node",
+  "request": "launch",
+  "name": "Debug current file",
+  "program": "${file}",
+  "runtimeArgs": ["--inspect-brk"],
+  "skipFiles": ["<node_internals>/**", "node_modules/**"]
+}
+```
+
+**Python pdb:**
+
+```python
+import pdb; pdb.set_trace()  # drop into interactive debugger
+# or in Python 3.7+:
+breakpoint()
+
+# pdb commands:
+# n — next line
+# s — step into function
+# c — continue until next breakpoint
+# p variable_name — print value
+# l — list source around current line
+# q — quit
+```