tribunal-kit 9.2.4 → 9.2.5

package/skills/systematic-debugging/SKILL.md

@@ -1,129 +1,129 @@
----
-name: systematic-debugging
-description: "Use when Systematic debugging framework. Root-cause isolation, 4-phase methodology, hypothesis testing, log tracing, avoiding shotgun-surgery, memory allocation analysis, and empirical evidence gathering. Use when debugging complex, highly-coupled, or elusive bugs across mixed execution environments."
-version: 5.0.0
-last-updated: 2026-09-13
-skills:
-  - diagnosing-bugs
-  - test-result-analyzer
-  - clean-code
-tools: Read, Grep, Glob, Bash, Edit, Write
-scripts-binding:
-  - .agent/scripts/test_runner.js
-  - .agent/scripts/verify_all.js
-  - .agent/scripts/lint_runner.js
----
-
-# Systematic Debugging — Root Cause Mastery
-
----
-
-## 🛠️ Technical Architecture & Reference Recipes
-
----
-
-## Hallucination Traps (Read First)
-
-- ❌ Changing multiple things at once to fix a bug -> ✅ Change ONE variable at a time; multiple changes make it impossible to identify the fix
-- ❌ Assuming the bug is where the error message points -> ✅ The error location is often downstream; trace UP the call stack to find root cause
-- ❌ Not reproducing the bug before attempting a fix -> ✅ If you cannot reproduce it reliably, you cannot verify your fix works
-
----
-
----
-
-## 1. The 4-Phase Debugging Methodology
-
-Never jump straight into modifying code when a bug is reported.
-
-### Phase 1: Replication & Isolation
-
-**Goal:** Prove the bug exists continuously and isolate the execution path.
-
-1. Write a failing deterministic unit/integration test that replicates the exact condition.
-2. Strip away all unnecessary layers (If the UI button fails to delete a user, curl the endpoint directly. Does the API fail? If yes, UI is fine, bug is in the backend/database).
-
-### Phase 2: Hypothesis Generation
-
-**Goal:** Formulate logical explanations for the anomaly based on data, not guesses.
-
-- "Because the log shows `auth: false` even after successful token parse, the RBAC middleware must be overwriting the session."
-
-### Phase 3: Evidence-Based Testing (The Probe)
-
-**Goal:** Prove or disprove the hypothesis without mutating the actual program functionality.
-
-- Insert strict logging probes: `logger.debug("Executing line 45. User.permissions:", user.permissions)`.
-- If the logs match your hypothesis, proceed. If they do not, discard the hypothesis.
-
-### Phase 4: Resolution & Verification
-
-**Goal:** Apply the minimal surgical change required, then verify via tests.
-
-- Re-run the deterministic failing test created in Phase 1. It must now pass.
-
----
-
-## 2. Specialized Diagnostic Techniques
-
-When debugging intricate or elusive bugs, reference these specialized technique guides:
-
-- **Root Cause Tracing (`./root-cause-tracing.md`):** Trace backwards up the call stack to identify where invalid data originated, rather than fixing where the error appears.
-- **Condition-Based Waiting (`./condition-based-waiting.md`):** Eliminate flaky tests and timing bugs by waiting for specific deterministic state conditions instead of arbitrary `setTimeout` or `sleep` calls.
-- **Defense in Depth (`./defense-in-depth.md`):** Add validation and runtime assertions at multiple component boundaries.
-
----
-
-## 3. Advanced Diagnostic Vectors
-
-When pure logic errors are ruled out, look for environmental factors.
-
-**1. Race Conditions / Timing Bugs**
-
-- _Symptom:_ The bug only happens 30% of the time, or depends on network speed.
-- _Cause:_ Missing `await` statements, relying on asynchronous callbacks returning in a specific order, or concurrent database transacting.
-
-**2. State Leakage**
-
-- _Symptom:_ The first operation works perfectly. The second consecutive operation fails mysteriously.
-- _Cause:_ Global variables, cached HTTP clients, or React state lacking proper cleanup functions between unmounts.
-
-**3. Silent Failures (Swallowed Errors)**
-
-- _Symptom:_ The application stops processing midway through an operation, but nothing is in the error logs.
-- _Cause:_ Empty `catch (e) {}` blocks, unhandled promise rejections, or frontend elements conditionally rendering `null` on missing datasets.
-
----
-
-## 3. The Bisection Method (Git Bisect)
-
-When a catastrophic bug appears in production but worked fine last week, use algorithmic isolation across the git history.
-
-```bash
-git bisect start
-git bisect bad HEAD           # The current state is broken
-git bisect good v1.4.0        # It worked fine in the last release
-
-# Git will now jump you exactly halfway between those commits.
-# Run your tests...
-git bisect bad   # (If it failed)
-# Or...
-git bisect good  # (If it passed)
-
-# Git will isolate the exact commit that introduced the bug in O(log N) steps.
-```
-
----
-
-## 4. Reading the Stack Trace Properly
-
-Do not skim. Stack traces tell the exact sequence of destruction.
-
-1. **Top line:** The final fatal blow (e.g., `TypeError: Cannot read properties of undefined (reading 'map')`).
-2. **First Application Function:** Scroll down past `node_modules` and framework internals. Find the absolute top-most function call that YOU wrote (e.g., `at UserList (src/components/UserList.tsx:45)`).
-3. **The Parameter Conclusion:** Therefore, line 45 invoked `.map` on a variable that was `undefined`. Why did the parent layer pass `undefined` instead of `[]`?
-
-
-## Integration with Durable Session Log
-
-When debugging fails, the agent MUST read the `.agent/.tribunal/session.jsonl` durable log to understand exactly where the previous wave crashed. Do not guess; read the event trace to see the exact sequence of tool calls and errors that led to the crash. You can grep this file or parse it to extract the latest `ErrorEncountered` or failed `ToolCompleted` events.
+---
+name: systematic-debugging
+description: "Use when Systematic debugging framework. Root-cause isolation, 4-phase methodology, hypothesis testing, log tracing, avoiding shotgun-surgery, memory allocation analysis, and empirical evidence gathering. Use when debugging complex, highly-coupled, or elusive bugs across mixed execution environments."
+version: 5.0.0
+last-updated: 2026-09-13
+skills:
+  - diagnosing-bugs
+  - test-result-analyzer
+  - clean-code
+tools: Read, Grep, Glob, Bash, Edit, Write
+scripts-binding:
+  - .agent/scripts/test_runner.js
+  - .agent/scripts/verify_all.js
+  - .agent/scripts/lint_runner.js
+---
+
+# Systematic Debugging — Root Cause Mastery
+
+---
+
+## 🛠️ Technical Architecture & Reference Recipes
+
+---
+
+## Hallucination Traps (Read First)
+
+- ❌ Changing multiple things at once to fix a bug -> ✅ Change ONE variable at a time; multiple changes make it impossible to identify the fix
+- ❌ Assuming the bug is where the error message points -> ✅ The error location is often downstream; trace UP the call stack to find root cause
+- ❌ Not reproducing the bug before attempting a fix -> ✅ If you cannot reproduce it reliably, you cannot verify your fix works
+
+---
+
+---
+
+## 1. The 4-Phase Debugging Methodology
+
+Never jump straight into modifying code when a bug is reported.
+
+### Phase 1: Replication & Isolation
+
+**Goal:** Prove the bug exists continuously and isolate the execution path.
+
+1. Write a failing deterministic unit/integration test that replicates the exact condition.
+2. Strip away all unnecessary layers (If the UI button fails to delete a user, curl the endpoint directly. Does the API fail? If yes, UI is fine, bug is in the backend/database).
+
+### Phase 2: Hypothesis Generation
+
+**Goal:** Formulate logical explanations for the anomaly based on data, not guesses.
+
+- "Because the log shows `auth: false` even after successful token parse, the RBAC middleware must be overwriting the session."
+
+### Phase 3: Evidence-Based Testing (The Probe)
+
+**Goal:** Prove or disprove the hypothesis without mutating the actual program functionality.
+
+- Insert strict logging probes: `logger.debug("Executing line 45. User.permissions:", user.permissions)`.
+- If the logs match your hypothesis, proceed. If they do not, discard the hypothesis.
+
+### Phase 4: Resolution & Verification
+
+**Goal:** Apply the minimal surgical change required, then verify via tests.
+
+- Re-run the deterministic failing test created in Phase 1. It must now pass.
+
+---
+
+## 2. Specialized Diagnostic Techniques
+
+When debugging intricate or elusive bugs, reference these specialized technique guides:
+
+- **Root Cause Tracing (`./root-cause-tracing.md`):** Trace backwards up the call stack to identify where invalid data originated, rather than fixing where the error appears.
+- **Condition-Based Waiting (`./condition-based-waiting.md`):** Eliminate flaky tests and timing bugs by waiting for specific deterministic state conditions instead of arbitrary `setTimeout` or `sleep` calls.
+- **Defense in Depth (`./defense-in-depth.md`):** Add validation and runtime assertions at multiple component boundaries.
+
+---
+
+## 3. Advanced Diagnostic Vectors
+
+When pure logic errors are ruled out, look for environmental factors.
+
+**1. Race Conditions / Timing Bugs**
+
+- _Symptom:_ The bug only happens 30% of the time, or depends on network speed.
+- _Cause:_ Missing `await` statements, relying on asynchronous callbacks returning in a specific order, or concurrent database transacting.
+
+**2. State Leakage**
+
+- _Symptom:_ The first operation works perfectly. The second consecutive operation fails mysteriously.
+- _Cause:_ Global variables, cached HTTP clients, or React state lacking proper cleanup functions between unmounts.
+
+**3. Silent Failures (Swallowed Errors)**
+
+- _Symptom:_ The application stops processing midway through an operation, but nothing is in the error logs.
+- _Cause:_ Empty `catch (e) {}` blocks, unhandled promise rejections, or frontend elements conditionally rendering `null` on missing datasets.
+
+---
+
+## 3. The Bisection Method (Git Bisect)
+
+When a catastrophic bug appears in production but worked fine last week, use algorithmic isolation across the git history.
+
+```bash
+git bisect start
+git bisect bad HEAD           # The current state is broken
+git bisect good v1.4.0        # It worked fine in the last release
+
+# Git will now jump you exactly halfway between those commits.
+# Run your tests...
+git bisect bad   # (If it failed)
+# Or...
+git bisect good  # (If it passed)
+
+# Git will isolate the exact commit that introduced the bug in O(log N) steps.
+```
+
+---
+
+## 4. Reading the Stack Trace Properly
+
+Do not skim. Stack traces tell the exact sequence of destruction.
+
+1. **Top line:** The final fatal blow (e.g., `TypeError: Cannot read properties of undefined (reading 'map')`).
+2. **First Application Function:** Scroll down past `node_modules` and framework internals. Find the absolute top-most function call that YOU wrote (e.g., `at UserList (src/components/UserList.tsx:45)`).
+3. **The Parameter Conclusion:** Therefore, line 45 invoked `.map` on a variable that was `undefined`. Why did the parent layer pass `undefined` instead of `[]`?
+
+
+## Integration with Durable Session Log
+
+When debugging fails, the agent MUST read the `.agent/.tribunal/session.jsonl` durable log to understand exactly where the previous wave crashed. Do not guess; read the event trace to see the exact sequence of tool calls and errors that led to the crash. You can grep this file or parse it to extract the latest `ErrorEncountered` or failed `ToolCompleted` events.

package/skills/systematic-debugging/condition-based-waiting.md

@@ -1,120 +1,120 @@
-# Condition-Based Waiting
-
-## Overview
-
-Flaky tests often guess at timing with arbitrary delays. This creates race conditions where tests pass on fast machines but fail under load or in CI.
-
-**Core principle:** Wait for the actual condition you care about, not a guess about how long it takes.
-
-## When to Use
-
-```dot
-digraph when_to_use {
-    "Test uses setTimeout/sleep?" [shape=diamond];
-    "Testing timing behavior?" [shape=diamond];
-    "Document WHY timeout needed" [shape=box];
-    "Use condition-based waiting" [shape=box];
-
-    "Test uses setTimeout/sleep?" -> "Testing timing behavior?" [label="yes"];
-    "Testing timing behavior?" -> "Document WHY timeout needed" [label="yes"];
-    "Testing timing behavior?" -> "Use condition-based waiting" [label="no"];
-}
-```
-
-**Use when:**
-
-- Tests have arbitrary delays (`setTimeout`, `sleep`, `time.sleep()`)
-- Tests are flaky (pass sometimes, fail under load)
-- Tests timeout when run in parallel
-- Waiting for async operations to complete
-
-**Don't use when:**
-
-- Testing actual timing behavior (debounce, throttle intervals)
-- Always document WHY if using arbitrary timeout
-
-## Core Pattern
-
-```typescript
-// ❌ BEFORE: Guessing at timing
-await new Promise(r => setTimeout(r, 50));
-const result = getResult();
-expect(result).toBeDefined();
-
-// ✅ AFTER: Waiting for condition
-await waitFor(() => getResult() !== undefined);
-const result = getResult();
-expect(result).toBeDefined();
-```
-
-## Quick Patterns
-
-| Scenario          | Pattern                                              |
-| ----------------- | ---------------------------------------------------- |
-| Wait for event    | `waitFor(() => events.find(e => e.type === 'DONE'))` |
-| Wait for state    | `waitFor(() => machine.state === 'ready')`           |
-| Wait for count    | `waitFor(() => items.length >= 5)`                   |
-| Wait for file     | `waitFor(() => fs.existsSync(path))`                 |
-| Complex condition | `waitFor(() => obj.ready && obj.value > 10)`         |
-
-## Implementation
-
-Generic polling function:
-
-```typescript
-async function waitFor<T>(
-  condition: () => T | undefined | null | false,
-  description: string,
-  timeoutMs = 5000,
-): Promise<T> {
-  const startTime = Date.now();
-
-  while (true) {
-    const result = condition();
-    if (result) return result;
-
-    if (Date.now() - startTime > timeoutMs) {
-      throw new Error(`Timeout waiting for ${description} after ${timeoutMs}ms`);
-    }
-
-    await new Promise(r => setTimeout(r, 10)); // Poll every 10ms
-  }
-}
-```
-
-See `condition-based-waiting-example.ts` in this directory for complete implementation with domain-specific helpers (`waitForEvent`, `waitForEventCount`, `waitForEventMatch`) from actual debugging session.
-
-## Common Mistakes
-
-**❌ Polling too fast:** `setTimeout(check, 1)` - wastes CPU
-**✅ Fix:** Poll every 10ms
-
-**❌ No timeout:** Loop forever if condition never met
-**✅ Fix:** Always include timeout with clear error
-
-**❌ Stale data:** Cache state before loop
-**✅ Fix:** Call getter inside loop for fresh data
-
-## When Arbitrary Timeout IS Correct
-
-```typescript
-// Tool ticks every 100ms - need 2 ticks to verify partial output
-await waitForEvent(manager, 'TOOL_STARTED'); // First: wait for condition
-await new Promise(r => setTimeout(r, 200)); // Then: wait for timed behavior
-// 200ms = 2 ticks at 100ms intervals - documented and justified
-```
-
-**Requirements:**
-
-1. First wait for triggering condition
-2. Based on known timing (not guessing)
-3. Comment explaining WHY
-
-## Real-World Impact
-
-From debugging session (2025-10-03):
-
-- Fixed 15 flaky tests across 3 files
-- Pass rate: 60% → 100%
-- Execution time: 40% faster
-- No more race conditions
+# Condition-Based Waiting
+
+## Overview
+
+Flaky tests often guess at timing with arbitrary delays. This creates race conditions where tests pass on fast machines but fail under load or in CI.
+
+**Core principle:** Wait for the actual condition you care about, not a guess about how long it takes.
+
+## When to Use
+
+```dot
+digraph when_to_use {
+    "Test uses setTimeout/sleep?" [shape=diamond];
+    "Testing timing behavior?" [shape=diamond];
+    "Document WHY timeout needed" [shape=box];
+    "Use condition-based waiting" [shape=box];
+
+    "Test uses setTimeout/sleep?" -> "Testing timing behavior?" [label="yes"];
+    "Testing timing behavior?" -> "Document WHY timeout needed" [label="yes"];
+    "Testing timing behavior?" -> "Use condition-based waiting" [label="no"];
+}
+```
+
+**Use when:**
+
+- Tests have arbitrary delays (`setTimeout`, `sleep`, `time.sleep()`)
+- Tests are flaky (pass sometimes, fail under load)
+- Tests timeout when run in parallel
+- Waiting for async operations to complete
+
+**Don't use when:**
+
+- Testing actual timing behavior (debounce, throttle intervals)
+- Always document WHY if using arbitrary timeout
+
+## Core Pattern
+
+```typescript
+// ❌ BEFORE: Guessing at timing
+await new Promise(r => setTimeout(r, 50));
+const result = getResult();
+expect(result).toBeDefined();
+
+// ✅ AFTER: Waiting for condition
+await waitFor(() => getResult() !== undefined);
+const result = getResult();
+expect(result).toBeDefined();
+```
+
+## Quick Patterns
+
+| Scenario          | Pattern                                              |
+| ----------------- | ---------------------------------------------------- |
+| Wait for event    | `waitFor(() => events.find(e => e.type === 'DONE'))` |
+| Wait for state    | `waitFor(() => machine.state === 'ready')`           |
+| Wait for count    | `waitFor(() => items.length >= 5)`                   |
+| Wait for file     | `waitFor(() => fs.existsSync(path))`                 |
+| Complex condition | `waitFor(() => obj.ready && obj.value > 10)`         |
+
+## Implementation
+
+Generic polling function:
+
+```typescript
+async function waitFor<T>(
+  condition: () => T | undefined | null | false,
+  description: string,
+  timeoutMs = 5000,
+): Promise<T> {
+  const startTime = Date.now();
+
+  while (true) {
+    const result = condition();
+    if (result) return result;
+
+    if (Date.now() - startTime > timeoutMs) {
+      throw new Error(`Timeout waiting for ${description} after ${timeoutMs}ms`);
+    }
+
+    await new Promise(r => setTimeout(r, 10)); // Poll every 10ms
+  }
+}
+```
+
+See `condition-based-waiting-example.ts` in this directory for complete implementation with domain-specific helpers (`waitForEvent`, `waitForEventCount`, `waitForEventMatch`) from actual debugging session.
+
+## Common Mistakes
+
+**❌ Polling too fast:** `setTimeout(check, 1)` - wastes CPU
+**✅ Fix:** Poll every 10ms
+
+**❌ No timeout:** Loop forever if condition never met
+**✅ Fix:** Always include timeout with clear error
+
+**❌ Stale data:** Cache state before loop
+**✅ Fix:** Call getter inside loop for fresh data
+
+## When Arbitrary Timeout IS Correct
+
+```typescript
+// Tool ticks every 100ms - need 2 ticks to verify partial output
+await waitForEvent(manager, 'TOOL_STARTED'); // First: wait for condition
+await new Promise(r => setTimeout(r, 200)); // Then: wait for timed behavior
+// 200ms = 2 ticks at 100ms intervals - documented and justified
+```
+
+**Requirements:**
+
+1. First wait for triggering condition
+2. Based on known timing (not guessing)
+3. Comment explaining WHY
+
+## Real-World Impact
+
+From debugging session (2025-10-03):
+
+- Fixed 15 flaky tests across 3 files
+- Pass rate: 60% → 100%
+- Execution time: 40% faster
+- No more race conditions