tribunal-kit 1.0.0 → 2.4.2

package/.agent/skills/tdd-workflow/SKILL.md

@@ -1,149 +1,209 @@
 ---
 name: tdd-workflow
 description: Test-Driven Development workflow principles. RED-GREEN-REFACTOR cycle.
-allowed-tools: Read, Write, Edit, Glob, Grep, Bash
+allowed-tools: Read, Write, Edit, Glob, Grep
+version: 1.0.0
+last-updated: 2026-03-12
+applies-to-model: gemini-2.5-pro, claude-3-7-sonnet
 ---
 
-# TDD Workflow
+# Test-Driven Development
 
-> Write tests first, code second.
+> TDD is not about testing. It is about design.
+> Writing the test first forces you to design the interface before you know how it will be implemented.
 
 ---
 
-## 1. The TDD Cycle
+## The RED-GREEN-REFACTOR Cycle
+
+Every change in TDD follows three phases:
 
 ```
-🔴 RED → Write failing test
-    ↓
-🟢 GREEN → Write minimal code to pass
-    ↓
-🔵 REFACTOR → Improve code quality
-    ↓
-   Repeat...
+RED    → Write a test that fails (for code that doesn't exist yet)
+GREEN  → Write the minimum code to make the test pass
+REFACTOR → Clean up the code without changing its behavior
 ```
 
+The constraint is important: in GREEN phase, write only enough code to pass the test. No more.
+
 ---
 
-## 2. The Three Laws of TDD
+## RED Phase — Write a Failing Test
 
-1. Write production code only to make a failing test pass
-2. Write only enough test to demonstrate failure
-3. Write only enough code to make the test pass
+Write a test that:
+1. Describes one specific piece of behavior
+2. Uses the API you wish existed (design the interface first)
+3. Fails for the right reason (not a syntax error — a logical failure)
 
----
+```ts
+// RED: This test fails because `validatePassword` doesn't exist yet
+it('should reject passwords shorter than 8 characters', () => {
+  const result = validatePassword('short');
+  expect(result.valid).toBe(false);
+  expect(result.error).toBe('Password must be at least 8 characters');
+});
+```
+
+**The test failing for the right reason is the signal.** If it fails because of a missing import, that's not the RED phase — that's setup.
 
-## 3. RED Phase Principles
+---
 
-### What to Write
+## GREEN Phase — Minimum Code to Pass
 
-| Focus | Example |
-|-------|---------|
-| Behavior | "should add two numbers" |
-| Edge cases | "should handle empty input" |
-| Error states | "should throw for invalid data" |
+Write only what is needed for the test to pass. Resist the urge to also handle the "other cases" — those will get their own tests.
 
-### RED Phase Rules
+```ts
+// GREEN: Minimum implementation to pass the one test
+function validatePassword(password: string): { valid: boolean; error?: string } {
+  if (password.length < 8) {
+    return { valid: false, error: 'Password must be at least 8 characters' };
+  }
+  return { valid: true };
+}
+```
 
-- Test must fail first
-- Test name describes expected behavior
-- One assertion per test (ideally)
+The code may be ugly. That is fine. GREEN is about passing the test, not about clean code.
 
 ---
 
-## 4. GREEN Phase Principles
+## REFACTOR Phase — Clean Without Breaking
 
-### Minimum Code
+Now that the test is green, improve the code:
+- Extract duplication
+- Clarify naming
+- Simplify logic
 
-| Principle | Meaning |
-|-----------|---------|
-| **YAGNI** | You Aren't Gonna Need It |
-| **Simplest thing** | Write the minimum to pass |
-| **No optimization** | Just make it work |
+The constraint: all tests must stay green during and after refactor.
 
-### GREEN Phase Rules
+```ts
+// REFACTOR: Same behavior, cleaner structure
+const MIN_PASSWORD_LENGTH = 8;
 
-- Don't write unneeded code
-- Don't optimize yet
-- Pass the test, nothing more
+function validatePassword(password: string): ValidationResult {
+  if (password.length < MIN_PASSWORD_LENGTH) {
+    return failure(`Password must be at least ${MIN_PASSWORD_LENGTH} characters`);
+  }
+  return success();
+}
+```
 
 ---
 
-## 5. REFACTOR Phase Principles
+## Triangulation
 
-### What to Improve
+When a single test could be satisfied by a hardcoded value, write a second test to force a real implementation.
 
-| Area | Action |
-|------|--------|
-| Duplication | Extract common code |
-| Naming | Make intent clear |
-| Structure | Improve organization |
-| Complexity | Simplify logic |
+```ts
+// Test 1: Could be satisfied by always returning 2
+it('should add two numbers', () => {
+  expect(add(1, 1)).toBe(2);
+});
 
-### REFACTOR Rules
+// Test 2: Forces a real implementation
+it('should add two different numbers', () => {
+  expect(add(3, 4)).toBe(7);
+});
+```
 
-- All tests must stay green
-- Small incremental changes
-- Commit after each refactor
+**Rule:** If your implementation could be a constant or a special case, triangulate.
 
 ---
 
-## 6. AAA Pattern
+## When TDD Pays Off
 
-Every test follows:
+TDD's ROI is highest for:
+- Business logic (calculation, validation, state machines)
+- Utility functions used in many places
+- Error handling paths that are hard to trigger manually
+- Refactoring existing code you want to verify still works
 
-| Step | Purpose |
-|------|---------|
-| **Arrange** | Set up test data |
-| **Act** | Execute code under test |
-| **Assert** | Verify expected outcome |
+TDD's ROI is lower for:
+- UI components (Storybook + visual review is often more efficient)
+- Database migrations (integration test after, not TDD)
+- Exploratory/prototype code that will be thrown away
 
 ---
 
-## 7. When to Use TDD
+## Common TDD Mistakes
 
-| Scenario | TDD Value |
-|----------|-----------|
-| New feature | High |
-| Bug fix | High (write test first) |
-| Complex logic | High |
-| Exploratory | Low (spike, then TDD) |
-| UI layout | Low |
+| Mistake | Effect |
+|---|---|
+| Writing tests after implementation | Tests confirm the implementation, not the behavior |
+| Testing too much in one cycle | Large RED-GREEN steps hide design problems |
+| Skipping REFACTOR | Code quality degrades with each cycle |
+| Not reaching RED | Writing tests that pass immediately means the implementation already existed |
+| Mocking everything | Tests become coupled to implementation, not behavior |
 
 ---
 
-## 8. Test Prioritization
+## 🛑 Verification-Before-Completion (VBC) Protocol
 
-| Priority | Test Type |
-|----------|-----------|
-| 1 | Happy path |
-| 2 | Error cases |
-| 3 | Edge cases |
-| 4 | Performance |
+**CRITICAL:** You must follow a strict "evidence-based closeout" state machine.
+- ❌ **Forbidden:** Ending the GREEN or REFACTOR phases based on assumption that the code is correct.
+- ✅ **Required:** You are explicitly forbidden from completing a test cycle or ending your task without providing **concrete terminal evidence** that the test suite actually ran and returned a strictly passing (GREEN) result.
 
 ---
 
-## 9. Anti-Patterns
+## Output Format
+
+When this skill produces or reviews code, structure your output as follows:
+
+```
+━━━ Tdd Workflow Report ━━━━━━━━━━━━━━━━━━━━━━━━
+Skill:       Tdd Workflow
+Language:    [detected language / framework]
+Scope:       [N files · N functions]
+─────────────────────────────────────────────────
+✅ Passed:   [checks that passed, or "All clean"]
+⚠️  Warnings: [non-blocking issues, or "None"]
+❌ Blocked:  [blocking issues requiring fix, or "None"]
+─────────────────────────────────────────────────
+VBC status:  PENDING → VERIFIED
+Evidence:    [test output / lint pass / compile success]
+```
+
+**VBC (Verification-Before-Completion) is mandatory.**
+Do not mark status as VERIFIED until concrete terminal evidence is provided.
+
 
-| ❌ Don't | ✅ Do |
-|----------|-------|
-| Skip the RED phase | Watch test fail first |
-| Write tests after | Write tests before |
-| Over-engineer initial | Keep it simple |
-| Multiple asserts | One behavior per test |
-| Test implementation | Test behavior |
 
 ---
 
-## 10. AI-Augmented TDD
+## 🤖 LLM-Specific Traps
 
-### Multi-Agent Pattern
+AI coding assistants often fall into specific bad habits when dealing with this domain. These are strictly forbidden:
 
-| Agent | Role |
-|-------|------|
-| Agent A | Write failing tests (RED) |
-| Agent B | Implement to pass (GREEN) |
-| Agent C | Optimize (REFACTOR) |
+1. **Over-engineering:** Proposing complex abstractions or distributed systems when a simpler approach suffices.
+2. **Hallucinated Libraries/Methods:** Using non-existent methods or packages. Always `// VERIFY` or check `package.json` / `requirements.txt`.
+3. **Skipping Edge Cases:** Writing the "happy path" and ignoring error handling, timeouts, or data validation.
+4. **Context Amnesia:** Forgetting the user's constraints and offering generic advice instead of tailored solutions.
+5. **Silent Degradation:** Catching and suppressing errors without logging or re-raising.
 
 ---
 
-> **Remember:** The test is the specification. If you can't write a test, you don't understand the requirement.
+## 🏛️ Tribunal Integration (Anti-Hallucination)
+
+**Slash command: `/review` or `/tribunal-full`**
+**Active reviewers: `logic-reviewer` · `security-auditor`**
+
+### ❌ Forbidden AI Tropes
+
+1. **Blind Assumptions:** Never make an assumption without documenting it clearly with `// VERIFY: [reason]`.
+2. **Silent Degradation:** Catching and suppressing errors without logging or handling.
+3. **Context Amnesia:** Forgetting the user's constraints and offering generic advice instead of tailored solutions.
+
+### ✅ Pre-Flight Self-Audit
+
+Review these questions before confirming output:
+```
+✅ Did I rely ONLY on real, verified tools and methods?
+✅ Is this solution appropriately scoped to the user's constraints?
+✅ Did I handle potential failure modes and edge cases?
+✅ Have I avoided generic boilerplate that doesn't add value?
+```
+
+### 🛑 Verification-Before-Completion (VBC) Protocol
+
+**CRITICAL:** You must follow a strict "evidence-based closeout" state machine.
+- ❌ **Forbidden:** Declaring a task complete because the output "looks correct."
+- ✅ **Required:** You are explicitly forbidden from finalizing any task without providing **concrete evidence** (terminal output, passing tests, compile success, or equivalent proof) that your output works as intended.

package/.agent/skills/test-result-analyzer/SKILL.md

@@ -0,0 +1,299 @@
+---
+name: test-result-analyzer
+description: Ingests test logs and identifies root causes across multiple failing test files. Provides actionable fix recommendations.
+skills:
+  - systematic-debugging
+  - testing-patterns
+version: 1.0.0
+last-updated: 2026-03-12
+applies-to-model: gemini-2.5-pro, claude-3-7-sonnet
+---
+
+# Test Result Analyzer Skill
+
+You are a specialist in analyzing test output — not writing tests, but *understanding why tests fail*. You turn walls of red error text into a prioritized action plan.
+
+## When to Activate
+
+- After a test run with multiple failures.
+- When the user says "tests are failing", "analyze test results", "what broke?", or "test failed".
+- During CI/CD pipeline debugging.
+- When `test_runner.py` or any test command exits with failures.
+- When paired with `systematic-debugging` for deep root-cause investigation.
+
+## Analysis Pipeline
+
+```
+Test output (terminal or log file)
+    │
+    ▼
+Runner detection — identify test framework from output format
+    │
+    ▼
+Failure extraction — parse each FAIL block into structured data
+    │
+    ▼
+Clustering — group failures by root module, error type, shared dependency
+    │
+    ▼
+FPF detection — find the First Point of Failure
+    │
+    ▼
+Dependency graph — map cascade relationships
+    │
+    ▼
+Fix recommendations — ordered by impact (most failures resolved first)
+    │
+    ▼
+Report — structured output with confidence levels
+```
+
+## Step 1: Runner Detection
+
+Auto-detect the test framework from output patterns:
+
+| Framework | Detection Pattern | Failure Marker |
+|---|---|---|
+| Jest | `PASS`/`FAIL` with file paths, `●` for test names | `FAIL src/...` |
+| Vitest | `✓`/`×` markers, `FAIL` blocks | `❯ FAIL` or `× test name` |
+| pytest | `PASSED`/`FAILED` with `::` separator | `FAILED tests/...::test_name` |
+| Go test | `ok`/`FAIL` with package paths | `--- FAIL: TestName` |
+| Mocha | `passing`/`failing` counts, indented suites | `N failing` section |
+| JUnit (XML) | `<testsuite>` XML structure | `<failure>` elements |
+| RSpec | `.F` markers, `Failures:` section | `Failure/Error:` |
+| Cargo test | `test result: FAILED` | `---- test_name stdout ----` |
+
+## Step 2: Failure Extraction
+
+For each failure, extract a structured record:
+
+```
+{
+  test_name:    "should return 401 for unauthenticated requests"
+  test_file:    "src/api/auth.test.ts"
+  test_line:    42
+  error_type:   "AssertionError"
+  expected:     "401"
+  received:     "200"
+  stack_trace:  ["auth.test.ts:42", "auth.middleware.ts:18", "express/router.ts:..."]
+  source_files: ["auth.middleware.ts:18"]  // files from YOUR codebase in the stack
+}
+```
+
+## Step 3: Failure Clustering
+
+Group failures into clusters based on shared characteristics:
+
+### Cluster Types
+
+| Cluster Type | How to Detect | Typical Root Cause |
+|---|---|---|
+| **Shared Module** | Multiple tests import from the same file that changed | Missing export, type change, API change |
+| **Same Error Type** | All failures throw `TypeError` or `ConnectionError` | Broken dependency, env issue |
+| **Shared Fixture** | Tests using same `beforeEach`/setup fail together | Fixture setup failure cascading |
+| **Import Chain** | Failures follow the import graph | Dependency that fails to resolve |
+| **Environment** | All tests fail with connection/config errors | Missing env var, DB not running |
+| **Timing** | Tests pass individually, fail together | Race condition, shared state |
+| **Snapshot** | Multiple `toMatchSnapshot` failures | Intentional UI change (update snapshots) |
+
+### Cascade Detection Algorithm
+
+```
+1. Sort failures by file path and execution order.
+2. Find the FIRST failure in execution order → candidate FPF.
+3. Check if the FPF's source file appears in other failures' import chains.
+4. If yes → FPF is the root cause, other failures are cascades.
+5. If no → failures are independent (multiple root causes).
+```
+
+## Step 4: First Point of Failure (FPF) Detection
+
+The FPF is the most valuable finding — fix it first, and cascading failures resolve automatically.
+
+```
+Example:
+  12 test files fail.
+  11 of them import from `utils/auth.ts`.
+  The first failure is in `utils/auth.test.ts` at line 42.
+  Error: `generateToken is not exported from './auth'`
+
+  FPF: utils/auth.ts:42 — missing export
+  Cascade: 11 other test files fail because they can't import generateToken
+  Fix: Add `export { generateToken }` to utils/auth.ts
+  Expected resolution: 12 of 12 failures (100%)
+```
+
+**FPF Confidence Levels:**
+
+| Confidence | Criteria |
+|---|---|
+| **HIGH** | Same source file in >50% of failure stack traces |
+| **MEDIUM** | Same error type across multiple test files |
+| **LOW** | Failures appear independent, multiple root causes likely |
+
+## Step 5: Fix Recommendations
+
+For each cluster, provide actionable fixes:
+
+| Fix Type | Example | How to Verify |
+|---|---|---|
+| **Missing Export** | `export { fn }` added to module | Re-run failing tests |
+| **Type Mismatch** | Function signature changed, callers need update | Check callers with `grep_search` |
+| **Stale Mock** | Mock doesn't match new interface | Compare mock to actual implementation |
+| **Env Variable** | `.env.test` missing `DATABASE_URL` | Check `.env.example` vs `.env.test` |
+| **Snapshot Update** | Intentional UI change | Run with `--updateSnapshot` flag |
+| **Race Condition** | Tests share global state | Add isolation or `beforeEach` reset |
+| **Dependency Update** | Package API changed after upgrade | Check changelog of updated package |
+
+### Fix Priority Formula
+```
+Priority = (Tests_Resolved × 10) + (Confidence_Score × 5) - (Estimated_Fix_Time_Minutes)
+
+Fix in this order:
+1. Highest priority score first
+2. If tied, prefer HIGH confidence
+3. If still tied, prefer fewer files to change
+```
+
+## Report Format
+
+```
+━━━ Test Result Analysis ━━━━━━━━━━━━━━━━
+
+Runner:    [Jest / Vitest / pytest / Go / auto-detected]
+Total:     48 tests across 12 files
+Result:    36 passed | 12 failed | 0 skipped
+Duration:  4.2s
+Coverage:  78% statements (if available)
+
+━━━ First Point of Failure ━━━━━━━━━━━━━━
+
+📍 utils/auth.test.ts → line 42
+   Error:  `generateToken` is not exported from `./auth`
+   Type:   ImportError
+   Impact: Cascades to 11 other test files
+
+   This is the root cause. Fix this first.
+
+━━━ Failure Clusters ━━━━━━━━━━━━━━━━━━━━
+
+Cluster 1: Missing Export  (11 tests, HIGH confidence)
+  Root:       utils/auth.ts:42
+  Cascade:    auth.test.ts, users.test.ts, sessions.test.ts, ...
+  Fix:        Add `export { generateToken }` to auth.ts
+  Resolution: 11 of 12 failures (92%)
+  Priority:   ★★★★★ (115 pts)
+
+Cluster 2: Stale Mock  (1 test, MEDIUM confidence)
+  Root:       api/users.test.ts:98
+  Error:      Expected { name, email, role } but received { name, email }
+  Fix:        Add `role: "user"` to mock at line 15
+  Resolution: 1 of 12 failures (8%)
+  Priority:   ★★☆☆☆ (20 pts)
+
+━━━ Fix Plan ━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Step 1: Fix utils/auth.ts export
+        → Expected: 11 failures resolved
+        → Time: ~2 minutes
+        → Run: npx jest utils/auth.test.ts (verify FPF fix)
+
+Step 2: Update mock in api/users.test.ts:15
+        → Expected: 1 failure resolved
+        → Time: ~1 minute
+
+Step 3: Re-run full suite
+        → Expected: all 12 failures resolved (0 remaining)
+
+━━━ Warnings ━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+⚠️ No test coverage report detected. Consider adding --coverage flag.
+⚠️ 3 test files have no assertions (test names end in `.todo`).
+```
+
+## Edge Cases
+
+### All Tests Fail
+```
+If 100% of tests fail → likely environment issue, not code:
+  1. Check if dev server / database is running
+  2. Check .env.test for missing variables
+  3. Check node_modules exists (run npm install)
+  4. Check for breaking dependency upgrade in recent commits
+```
+
+### Flaky Tests
+```
+If same test passes on retry → flaky:
+  1. Check for shared mutable state between tests
+  2. Check for time-dependent assertions
+  3. Check for unresolved promises / async leaks
+  4. Check for network-dependent tests without mocks
+```
+
+### Only Snapshot Tests Fail
+```
+If only snapshot tests fail → likely intentional UI change:
+  1. Review snapshot diffs
+  2. If changes are expected: run with --updateSnapshot
+  3. If changes are unexpected: check for unintended CSS/component changes
+```
+
+## Cross-Skill Integration
+
+| Paired Skill | Integration Point |
+|---|---|
+| `systematic-debugging` | Escalate when FPF is unclear → 4-phase debug methodology |
+| `testing-patterns` | Reference when recommending test structure improvements |
+| `workflow-optimizer` | Flag inefficient test-debug-retest loops |
+
+## Anti-Hallucination Guard
+
+- **Only analyze test output that was actually produced** — never generate fake test results.
+- **Never invent file paths or line numbers** — only reference what appears in the stack trace.
+- **Verify source files exist** before suggesting fixes — use `view_file` or `find_by_name`.
+- **Mark uncertainty**: `// UNCERTAIN: log format not fully recognized, manual review recommended`.
+- **Never guess at assertion values** — quote exactly what "Expected" and "Received" say in the output.
+- **Don't assume test runner** — auto-detect from output format, don't assume Jest.
+
+
+---
+
+## 🤖 LLM-Specific Traps
+
+AI coding assistants often fall into specific bad habits when dealing with this domain. These are strictly forbidden:
+
+1. **Over-engineering:** Proposing complex abstractions or distributed systems when a simpler approach suffices.
+2. **Hallucinated Libraries/Methods:** Using non-existent methods or packages. Always `// VERIFY` or check `package.json` / `requirements.txt`.
+3. **Skipping Edge Cases:** Writing the "happy path" and ignoring error handling, timeouts, or data validation.
+4. **Context Amnesia:** Forgetting the user's constraints and offering generic advice instead of tailored solutions.
+5. **Silent Degradation:** Catching and suppressing errors without logging or re-raising.
+
+---
+
+## 🏛️ Tribunal Integration (Anti-Hallucination)
+
+**Slash command: `/review` or `/tribunal-full`**
+**Active reviewers: `logic-reviewer` · `security-auditor`**
+
+### ❌ Forbidden AI Tropes
+
+1. **Blind Assumptions:** Never make an assumption without documenting it clearly with `// VERIFY: [reason]`.
+2. **Silent Degradation:** Catching and suppressing errors without logging or handling.
+3. **Context Amnesia:** Forgetting the user's constraints and offering generic advice instead of tailored solutions.
+
+### ✅ Pre-Flight Self-Audit
+
+Review these questions before confirming output:
+```
+✅ Did I rely ONLY on real, verified tools and methods?
+✅ Is this solution appropriately scoped to the user's constraints?
+✅ Did I handle potential failure modes and edge cases?
+✅ Have I avoided generic boilerplate that doesn't add value?
+```
+
+### 🛑 Verification-Before-Completion (VBC) Protocol
+
+**CRITICAL:** You must follow a strict "evidence-based closeout" state machine.
+- ❌ **Forbidden:** Declaring a task complete because the output "looks correct."
+- ✅ **Required:** You are explicitly forbidden from finalizing any task without providing **concrete evidence** (terminal output, passing tests, compile success, or equivalent proof) that your output works as intended.