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

package/content/plugins/debugging/skills/agileflow-debug/workflows/debug-issue.md

@@ -0,0 +1,187 @@
+# Workflow: Debug Issue
+
+**Triggers:** "debug", "not working", "error", "bug", "something's wrong", user pastes a stack trace or describes unexpected behaviour
+
+**Goal:** Identify the root cause of a bug using the scientific method, fix it, and prevent regression.
+
+---
+
+## Inputs needed
+
+| Input                            | Required  | How to get it                                                        |
+| -------------------------------- | --------- | -------------------------------------------------------------------- |
+| Bug description or error message | Yes       | User provides; or ask "What's happening vs what should happen?"      |
+| Stack trace / error output       | Preferred | Ask user to paste the full error                                     |
+| Steps to reproduce               | Preferred | Ask: "How do I make this fail consistently?"                         |
+| Relevant source files            | Yes       | Read the files mentioned in the stack trace or described by the user |
+| Recent changes                   | No        | Ask: "Did this start failing after a recent change?"                 |
+
+---
+
+## Steps
+
+### Step 1: Understand the expected vs actual behaviour
+
+Before looking at any code, get precise answers to:
+
+- **What should happen?** (the expected outcome)
+- **What actually happens?** (the actual outcome)
+- **When did it start failing?** (helps decide if it's a regression)
+- **Is it consistent or intermittent?**
+
+If any of these are unclear, ask. A vague "it doesn't work" makes debugging take 5x longer.
+
+### Step 2: Read and understand the error message
+
+If there's an error or stack trace:
+
+1. Find the first frame in application code (ignore framework frames)
+2. Read the error message literally
+3. Cross-reference with `references/common-patterns.md` — does this match a known pattern?
+
+If there's no error message, ask:
+
+- "Is there anything in the logs or browser console?"
+- "Does the network request return an error status?"
+
+### Step 3: Reproduce the bug
+
+Before forming hypotheses, confirm you can reproduce:
+
+- Read the steps the user described
+- Trace through the code mentally with the given inputs
+- Can you explain why the error occurs with what you know?
+
+If you can reproduce it mentally, skip ahead to Step 4.
+
+If you can't reproduce it:
+
+- Ask for more specific steps
+- Ask if the bug is environment-specific (local? staging? specific browser?)
+- Suggest adding temporary logs to gather more data
+
+### Step 4: Isolate the location
+
+Use binary search to narrow the bug to a specific function or line:
+
+1. Identify where the input enters the system (definitely correct)
+2. Identify where the wrong output appears (definitely wrong)
+3. Find the midpoint of the code path
+4. Would the data be correct or wrong at the midpoint?
+
+If the code path is short (<50 lines), read every line carefully instead.
+
+### Step 5: Form 1–3 hypotheses
+
+Write explicit hypotheses in the format:
+
+> "I believe [X] is causing [Y] because [Z]"
+
+Examples:
+
+- "I believe the user ID is null because the session expires before the redirect completes"
+- "I believe the total is wrong because the discount is applied after tax instead of before"
+- "I believe the test is flaky because `Date.now()` is used without fake timers"
+
+Rank them: most likely first.
+
+### Step 6: Test the most likely hypothesis
+
+Do NOT change production code to test a hypothesis. Instead:
+
+- Add a temporary log statement to check the value at the suspected point
+- Write a failing unit test that would prove the hypothesis
+- Add an assertion before the suspected line
+
+If the hypothesis is proved: go to Step 7.
+If disproved: go back to Step 5 and form the next hypothesis.
+
+### Step 7: Identify the root cause
+
+The root cause is the deepest causal link — not the symptom.
+
+| Symptom                   | Root cause (usually)                                |
+| ------------------------- | --------------------------------------------------- |
+| Null pointer at line 47   | Missing null check at the DB query 20 lines earlier |
+| Wrong total               | Arithmetic applied in wrong order                   |
+| Test fails intermittently | Shared state between tests (not isolated)           |
+| 500 error on POST         | Unhandled exception escaping the try/catch          |
+
+Do not fix the symptom — fix the root cause.
+
+### Step 8: Fix
+
+Apply the minimum change to fix the root cause:
+
+1. Don't refactor while fixing — that's a separate step
+2. Don't change function signatures unless the bug is in the contract
+3. If the fix requires a structural change, note it but implement the safe minimal fix first
+
+### Step 9: Verify
+
+After applying the fix:
+
+1. Confirm the original symptom is gone
+2. Check for related code paths that might have the same bug
+3. Run the test suite (or the specific test that was failing)
+
+### Step 10: Prevent regression
+
+Write a test that would have caught this bug:
+
+```
+Test name: '{specific behaviour that was broken}'
+What it tests: The exact path that produced the bug
+Assertions: Verify the correct output, not just that no error occurs
+```
+
+If no test is possible (e.g. a configuration bug), add a comment explaining the gotcha.
+
+### Step 11: Offer next steps
+
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "Root cause found and fixed. {one-sentence summary of the bug and fix}.",
+  "header": "Next step",
+  "multiSelect": false,
+  "options": [
+    {"label": "Write the regression test (Recommended)", "description": "I'll add a test that would have caught this bug"},
+    {"label": "Check if this bug exists elsewhere in the codebase", "description": "I'll search for similar patterns that could fail the same way"},
+    {"label": "Explain the root cause in detail", "description": "Full explanation of why this happened and what the fix does"},
+    {"label": "That's fixed — move on", "description": "No further investigation needed"}
+  ]
+}]</parameter>
+</invoke>
+```
+
+---
+
+## Escalation: when the standard flow isn't enough
+
+If after 2–3 hypothesis cycles you haven't found the cause:
+
+1. **Add comprehensive logging** — log every state change in the suspicious area and ask the user to run and paste the output
+2. **Suggest a minimal reproduction** — follow `workflows/reproduce-bug.md` to create an isolated test case
+3. **Check if it's an environment issue** — ask the user to verify versions, environment variables, and whether it fails consistently in all environments
+4. **Ask if something recently changed** — run `git log --oneline --since="1 week ago"` to see recent commits
+
+---
+
+## Fallbacks
+
+**If AskUserQuestion is unavailable:**
+
+Present findings as numbered options:
+
+```
+Root cause identified: {summary}.
+
+To proceed:
+1. Apply the fix now — I'll write the corrected code
+2. Write a regression test first, then fix
+3. Show me the full explanation before changing anything
+4. Check if this pattern exists elsewhere in the codebase
+
+Reply with a number.
+```

package/content/plugins/debugging/skills/agileflow-debug/workflows/reproduce-bug.md

@@ -0,0 +1,194 @@
+# Workflow: Reproduce Bug
+
+**Triggers:** "I can't reproduce this", "it's intermittent", "happens on production not locally", user needs to file a bug report, or the debugging flow is stuck because the bug won't reproduce consistently
+
+**Goal:** Create a minimal, reliable reproduction case that makes the bug fail consistently and in isolation.
+
+---
+
+## Why minimal reproduction matters
+
+A minimal reproduction:
+
+1. Removes noise — confirms which code is actually causing the bug
+2. Enables sharing — can be given to another developer or submitted as a bug report
+3. Enables regression tests — the reproduction becomes the basis for a test
+4. Forces clarity — the act of creating it often reveals the root cause
+
+---
+
+## Inputs needed
+
+| Input                           | Required  | How to get it                                     |
+| ------------------------------- | --------- | ------------------------------------------------- |
+| Description of the bug          | Yes       | What happens vs what should happen                |
+| Steps that sometimes trigger it | Yes       | Ask: "What sequence of actions produces the bug?" |
+| Environment where it occurs     | Yes       | Local, staging, production? Browser? OS?          |
+| Frequency                       | Preferred | Always? 1 in 10? Only at certain times?           |
+| Recent changes                  | No        | `git log --oneline` since it started              |
+
+---
+
+## Steps
+
+### Step 1: Write down the exact preconditions
+
+The bug may require specific state to occur. List:
+
+- What data must exist in the database?
+- What user must be authenticated?
+- What must have happened just before (previous requests, state changes)?
+- What time of day, day of week, or timezone?
+- What browser, OS, or runtime version?
+
+### Step 2: Reduce to the minimum trigger
+
+Start with the full sequence that produces the bug. Then remove steps one at a time:
+
+1. Does the bug still occur without step N?
+   - Yes → step N is not required; remove it
+   - No → step N is required; keep it
+
+Repeat until you have the minimum sequence.
+
+### Step 3: Reduce to the minimum code
+
+Identify the smallest code path involved in the bug:
+
+1. Write a standalone script or test that calls only the suspected function
+2. Use hard-coded inputs (no HTTP, no session, no middleware)
+3. Does it still fail? If yes — you have a minimal reproduction
+4. If no — the bug requires context from the wider system; add back pieces one at a time
+
+**Example minimal reproduction script:**
+
+```js
+// repro.js — standalone, no server, no middleware
+import { calculateDiscount } from "./src/pricing/discount.js";
+
+// These are the exact inputs that reproduce the bug
+const result = calculateDiscount({
+  basePrice: 100,
+  couponCode: "SAVE10",
+  userRole: "premium",
+});
+
+console.log("Expected: 85");
+console.log("Actual:", result.finalPrice);
+// Run: node repro.js
+```
+
+### Step 4: Add assertions to make the failure explicit
+
+Turn the reproduction into a failing test:
+
+```js
+import { describe, it, expect } from "vitest";
+import { calculateDiscount } from "./src/pricing/discount.js";
+
+describe("calculateDiscount — regression test for #issue-123", () => {
+  it("applies the SAVE10 coupon correctly for premium users", () => {
+    const result = calculateDiscount({
+      basePrice: 100,
+      couponCode: "SAVE10",
+      userRole: "premium",
+    });
+    expect(result.finalPrice).toBe(85); // BUG: currently returns 90
+  });
+});
+```
+
+This test will fail until the bug is fixed. Once fixed, it becomes the regression test.
+
+### Step 5: For intermittent bugs — find the trigger condition
+
+If the bug is intermittent, the goal is to make it fail consistently. Strategies:
+
+#### 5a: Add tight retry loops
+
+```js
+// Run the suspected operation 1000 times — race conditions will appear
+for (let i = 0; i < 1000; i++) {
+  await suspectedRaceCondition();
+}
+```
+
+#### 5b: Add concurrent execution
+
+```js
+// Run 50 concurrent requests to expose race conditions
+await Promise.all(
+  Array.from({ length: 50 }, () =>
+    request(app).post("/api/orders").send(payload),
+  ),
+);
+```
+
+#### 5c: Remove timeouts and sleep
+
+Intermittent bugs often depend on timing. Replace any `setTimeout` or `sleep` with synchronous equivalents to make the state explicit.
+
+#### 5d: Fake the time
+
+```js
+// If the bug depends on a specific time of day or elapsed time
+vi.useFakeTimers();
+vi.setSystemTime(new Date("2025-03-09T02:00:00Z")); // DST change day
+// ... reproduce the bug
+vi.useRealTimers();
+```
+
+#### 5e: Run tests in different order
+
+```bash
+# Vitest — randomise order
+vitest --sequence.shuffle
+
+# Jest
+jest --randomize
+
+# If a specific test fails only when run after another:
+# Run the suspicious pair together and confirm
+vitest path/to/test-a.test.js path/to/test-b.test.js
+```
+
+### Step 6: Document the reproduction
+
+Write a short summary:
+
+```
+Bug: calculateDiscount returns 90 instead of 85 for premium users with SAVE10 coupon
+
+Minimal reproduction:
+  Input:  { basePrice: 100, couponCode: 'SAVE10', userRole: 'premium' }
+  Expected: { finalPrice: 85 }
+  Actual:   { finalPrice: 90 }
+
+File: repro.js (attached) — run with: node repro.js
+Test: tests/pricing/discount.regression.test.js
+
+Root cause hypothesis: The premium discount (15%) and coupon (10%) are applied
+additively instead of the coupon being applied first then the role discount.
+```
+
+### Step 7: Hand off the reproduction to the debug workflow
+
+Once the bug is reproducible, follow `workflows/debug-issue.md` from Step 4 (isolate) using the minimal reproduction as the starting point. The root cause is usually obvious once the noise is removed.
+
+---
+
+## Fallbacks
+
+**If the bug cannot be reproduced locally:**
+
+1. Add verbose logging to the production/staging path and ask for logs
+2. Check if the issue is data-specific (a particular user ID or record)
+3. Ask: "Does this happen for all users or only specific accounts?"
+4. Request a copy of the production data (sanitised) to reproduce locally
+
+**If the bug cannot be reproduced at all (user reports it but you can't confirm):**
+
+1. Ask for a screen recording or screenshot
+2. Ask which browser, OS, and app version they are using
+3. Ask if it happened more than once and if any colleagues can reproduce it
+4. It may be a caching issue — ask them to hard-reload or clear cache