tribunal-kit 9.0.2 → 9.2.3

package/.agents/skills/server-management/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: server-management
-description: Use when Production Linux server administration mastery. Systemd services, Nginx reverse proxy architecture, UFW firewalls, SSH key security, cron scheduling, log rotation, and server hardening. Use when configuring bare-metal, VPS instances, or reviewing deployment architecture.
+description: "Use when Production Linux server administration mastery. Systemd services, Nginx reverse proxy architecture, UFW firewalls, SSH key security, cron scheduling, log rotation, and server hardening. Use when configuring bare-metal, VPS instances, or reviewing deployment architecture."
 version: 5.0.0
 last-updated: 2026-09-13
 skills:
@@ -15,42 +15,12 @@ scripts-binding:
 
 # Server Management — Production Linux Mastery
 
-## Mandatory Pre-Flight Context Inspection
-
-Before generating, refactoring, or reviewing code in the `server-management` domain, inspect these 5 critical parameters:
-
-1. **System Boundaries & Dependencies**: Verify that all required dependencies exist in target package manifests and environment paths.
-2. **Runtime Context & Platform Invariants**: Confirm target platform constraints (Node.js, Browser, Mobile OS, Edge runtime) before applying APIs.
-3. **Execution Guardrails**: Identify potential side-effects, state mutations, and unhandled asynchronous exceptions.
-4. **Validation & Type Contracts**: Validate input data schemas and strict type constraints across all module interfaces.
-5. **Observability & Proof of Execution**: Ensure execution produces tangible verification signals (terminal output, tests, metrics).
-
-## Activation Boundaries
-
-- **Activate when:** Use when Production Linux server administration mastery. Systemd services, Nginx reverse proxy architecture, UFW firewalls, SSH key security, cron scheduling, log rotation, and server hardening. Use when configuring bare-metal, VPS instances, or reviewing deployment architecture.
-- **DO NOT activate when:** The task falls outside the `server-management` domain or is managed by a different dedicated specialist.
-
-## 🔁 Multi-Pass Execution Protocol
-
-Execute all non-trivial tasks through this 7-pass cognitive loop:
-
-| Pass | Phase | Core Action |
-|:---|:---|:---|
-| **Pass 1** | **Understand** | Deconstruct the user's explicit objective, implicit requirements, and platform constraints. |
-| **Pass 2** | **Plan** | Decompose the task into smallest logical steps; map dependencies and required tool calls. |
-| **Pass 3** | **Execute** | Implement the solution with production-grade craft, zero placeholders, and strict typing. |
-| **Pass 4** | **Verify** | Run linters, unit tests, or compiler checks to validate structural correctness. |
-| **Pass 5** | **Attack** | Perform an adversarial review searching for edge-case failures, race conditions, and traps. |
-| **Pass 6** | **Improve** | Eliminate discovered friction, optimize performance, and harden error boundaries. |
-| **Pass 7** | **Quality Gate** | Enforce Verification-Before-Completion (VBC) with concrete terminal proof before finalizing. |
-
 ---
 
 ## 🛠️ Technical Architecture & Reference Recipes
 
 ---
 
-
 ## Hallucination Traps (Read First)
 
 - ❌ Running services as root -> ✅ Create a dedicated service user with minimal permissions; never run as root
@@ -206,48 +176,3 @@ A server will inevitably crash when `/var/log` consumes 100% of the disk.
     copytruncate         # Copy then clear (avoids disrupting Node's open file handles)
 }
 ```
-
----
-
-## 🚨 Edge-Case & Failure Mode Matrix
-
-| Scenario | Risk | Mitigation Strategy |
-|:---|:---|:---|
-| **Empty or Null Inputs** | Unhandled exception or unexpected rendering collapse | Enforce fallback guards, optional chaining, and explicit empty state handlers |
-| **Network Timeout / Latency** | Hanging operations or duplicate side-effects | Implement bounded abort controllers, exponential backoff, and idempotency keys |
-| **Concurrency / Race Conditions** | Stale state overwrite or inconsistent data mutations | Use atomic transactions, mutex locking, or cancel-on-resubmit controls |
-| **Invalid Schema / Malformed Payload** | Downstream runtime errors or security injection | Validate boundary payloads with Zod/Pydantic schemas prior to execution |
-| **Resource / Memory Saturation** | OOM errors, frame drops, or memory leaks | Clean up listeners, cancel active timers, and enforce pagination/virtualization |
-
----
-
-## 🤖 LLM-Specific Traps Table
-
-| Anti-Pattern | What AI Commonly Does Wrong | What Is Actually Correct |
-|:---|:---|:---|
-| **Silent Pipeline Failure** | Executing shell steps without set -euo pipefail, ignoring errors | Always initialize shell scripts with set -euo pipefail and trap handlers |
-| **Unpinned Dependency Shift** | Installing packages with npm install or using :latest docker tags | Lock dependencies with npm ci / lockfiles and use immutable SHA256 image digests |
-| **Leaking Build Secrets** | Passing secrets as Docker build arguments baked into image layers | Use Docker BuildKit secret mounts (--mount=type=secret) or runtime injection |
-
----
-
-## 🏛️ Tribunal Verification & Guardrails
-
-**Active Reviewers:** `pipeline-reviewer` · `devops-engineer` · `resilience-reviewer`
-**Slash Command:** `/review` or `/tribunal-full`
-
-### ✅ Pre-Flight Self-Audit Checklist
-
-```
-✅ Are strict execution modes (set -euo pipefail) active on all scripts?
-✅ Are container images pinned to digest/immutable tags instead of "latest"?
-✅ Are deployment health checks and rollback baselines configured?
-✅ Are CI secrets masked and unexposed to untrusted pull requests?
-✅ Did I verify environment compatibility across target runtimes?
-```
-
-### 🛑 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 test suites, compiler success, or equivalent operational proof) that your output works as intended.

package/.agents/skills/shadcn-ui-expert/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: shadcn-ui-expert
-description: Use when shadcn/ui mastery. Installation, customization via tailwind.config, component extraction, state management with Radix Primitives, theme variables (CSS custom properties), dark mode implementations, and overriding default designs. Use when building or modifying shadcn/ui components in React/Next.js projects.
+description: "Use when shadcn/ui mastery. Installation, customization via tailwind.config, component extraction, state management with Radix Primitives, theme variables (CSS custom properties), dark mode implementations, and overriding default designs. Use when building or modifying shadcn/ui components in React/Next.js projects."
 version: 5.0.0
 last-updated: 2026-09-13
 skills:
@@ -15,42 +15,12 @@ scripts-binding:
 
 # shadcn/ui Expert — Component Architecture Mastery
 
-## Mandatory Pre-Flight Context Inspection
-
-Before generating, refactoring, or reviewing code in the `shadcn-ui-expert` domain, inspect these 5 critical parameters:
-
-1. **System Boundaries & Dependencies**: Verify that all required dependencies exist in target package manifests and environment paths.
-2. **Runtime Context & Platform Invariants**: Confirm target platform constraints (Node.js, Browser, Mobile OS, Edge runtime) before applying APIs.
-3. **Execution Guardrails**: Identify potential side-effects, state mutations, and unhandled asynchronous exceptions.
-4. **Validation & Type Contracts**: Validate input data schemas and strict type constraints across all module interfaces.
-5. **Observability & Proof of Execution**: Ensure execution produces tangible verification signals (terminal output, tests, metrics).
-
-## Activation Boundaries
-
-- **Activate when:** Use when shadcn/ui mastery. Installation, customization via tailwind.config, component extraction, state management with Radix Primitives, theme variables (CSS custom properties), dark mode implementations, and overriding default designs. Use when building or modifying shadcn/ui components in React/Next.js projects.
-- **DO NOT activate when:** The task falls outside the `shadcn-ui-expert` domain or is managed by a different dedicated specialist.
-
-## 🔁 Multi-Pass Execution Protocol
-
-Execute all non-trivial tasks through this 7-pass cognitive loop:
-
-| Pass | Phase | Core Action |
-|:---|:---|:---|
-| **Pass 1** | **Understand** | Deconstruct the user's explicit objective, implicit requirements, and platform constraints. |
-| **Pass 2** | **Plan** | Decompose the task into smallest logical steps; map dependencies and required tool calls. |
-| **Pass 3** | **Execute** | Implement the solution with production-grade craft, zero placeholders, and strict typing. |
-| **Pass 4** | **Verify** | Run linters, unit tests, or compiler checks to validate structural correctness. |
-| **Pass 5** | **Attack** | Perform an adversarial review searching for edge-case failures, race conditions, and traps. |
-| **Pass 6** | **Improve** | Eliminate discovered friction, optimize performance, and harden error boundaries. |
-| **Pass 7** | **Quality Gate** | Enforce Verification-Before-Completion (VBC) with concrete terminal proof before finalizing. |
-
 ---
 
 ## 🛠️ Technical Architecture & Reference Recipes
 
 ---
 
-
 ## Hallucination Traps (Read First)
 
 - ❌ `import { Button } from 'shadcn-ui'` -> ✅ shadcn/ui is NOT a package; components are copied into YOUR project. Import from `@/components/ui/button`
@@ -224,48 +194,3 @@ export default async function Page() {
   return <MyDialogComponent data={data} /> // Passes data to interactive client component
 }
 ```
-
----
-
-## 🚨 Edge-Case & Failure Mode Matrix
-
-| Scenario | Risk | Mitigation Strategy |
-|:---|:---|:---|
-| **Empty or Null Inputs** | Unhandled exception or unexpected rendering collapse | Enforce fallback guards, optional chaining, and explicit empty state handlers |
-| **Network Timeout / Latency** | Hanging operations or duplicate side-effects | Implement bounded abort controllers, exponential backoff, and idempotency keys |
-| **Concurrency / Race Conditions** | Stale state overwrite or inconsistent data mutations | Use atomic transactions, mutex locking, or cancel-on-resubmit controls |
-| **Invalid Schema / Malformed Payload** | Downstream runtime errors or security injection | Validate boundary payloads with Zod/Pydantic schemas prior to execution |
-| **Resource / Memory Saturation** | OOM errors, frame drops, or memory leaks | Clean up listeners, cancel active timers, and enforce pagination/virtualization |
-
----
-
-## 🤖 LLM-Specific Traps Table
-
-| Anti-Pattern | What AI Commonly Does Wrong | What Is Actually Correct |
-|:---|:---|:---|
-| **Uncontrolled Re-render Loop** | Mutating state inside render bodies or omitting hook dependencies | Wrap effects with explicit deps and isolate reactive derivations in useMemo |
-| **Accessibility Neglect** | Interactive <div> without role="button", tabIndex, or onKeyDown | Use semantic <button> or provide ARIA role, keyboard handlers, and focus ring |
-| **Layout Shift Flash** | Images/dynamic content without aspect-ratio or explicit dimensions | Enforce aspect-ratio or skeleton placeholders to guarantee zero CLS |
-
----
-
-## 🏛️ Tribunal Verification & Guardrails
-
-**Active Reviewers:** `frontend-reviewer` · `type-safety` · `ui-ux-auditor` · `complexity-reviewer`
-**Slash Command:** `/review` or `/tribunal-full`
-
-### ✅ Pre-Flight Self-Audit Checklist
-
-```
-✅ Are all component props strictly typed with zero implicit "any"?
-✅ Are responsive breakpoints, fluid typography, and optical balance verified?
-✅ Is accessibility (ARIA labels, keyboard focus, contrast) validated?
-✅ Are re-renders minimized and state lifecycles cleanly separated?
-✅ Did I verify all imported UI components and icon sets actually exist?
-```
-
-### 🛑 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 test suites, compiler success, or equivalent operational proof) that your output works as intended.

package/.agents/skills/shape/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: shape
-description: Use when Plan feature UX before writing code via structured Socratic design interviews. Use when a user asks to plan a new screen, onboarding flow, feature UX, or user interaction before implementation.
+description: "Use when Plan feature UX before writing code via structured Socratic design interviews. Use when a user asks to plan a new screen, onboarding flow, feature UX, or user interaction before implementation."
 version: 5.0.0
 last-updated: 2026-09-13
 skills:
@@ -16,42 +16,12 @@ scripts-binding:
 
 # Shape — Pre-Code UX & Feature Shaping
 
-## Mandatory Pre-Flight Context Inspection
-
-Before generating, refactoring, or reviewing code in the `shape` domain, inspect these 5 critical parameters:
-
-1. **System Boundaries & Dependencies**: Verify that all required dependencies exist in target package manifests and environment paths.
-2. **Runtime Context & Platform Invariants**: Confirm target platform constraints (Node.js, Browser, Mobile OS, Edge runtime) before applying APIs.
-3. **Execution Guardrails**: Identify potential side-effects, state mutations, and unhandled asynchronous exceptions.
-4. **Validation & Type Contracts**: Validate input data schemas and strict type constraints across all module interfaces.
-5. **Observability & Proof of Execution**: Ensure execution produces tangible verification signals (terminal output, tests, metrics).
-
-## Activation Boundaries
-
-- **Activate when:** Use when Plan feature UX before writing code via structured Socratic design interviews. Use when a user asks to plan a new screen, onboarding flow, feature UX, or user interaction before implementation.
-- **DO NOT activate when:** The task falls outside the `shape` domain or is managed by a different dedicated specialist.
-
-## 🔁 Multi-Pass Execution Protocol
-
-Execute all non-trivial tasks through this 7-pass cognitive loop:
-
-| Pass | Phase | Core Action |
-|:---|:---|:---|
-| **Pass 1** | **Understand** | Deconstruct the user's explicit objective, implicit requirements, and platform constraints. |
-| **Pass 2** | **Plan** | Decompose the task into smallest logical steps; map dependencies and required tool calls. |
-| **Pass 3** | **Execute** | Implement the solution with production-grade craft, zero placeholders, and strict typing. |
-| **Pass 4** | **Verify** | Run linters, unit tests, or compiler checks to validate structural correctness. |
-| **Pass 5** | **Attack** | Perform an adversarial review searching for edge-case failures, race conditions, and traps. |
-| **Pass 6** | **Improve** | Eliminate discovered friction, optimize performance, and harden error boundaries. |
-| **Pass 7** | **Quality Gate** | Enforce Verification-Before-Completion (VBC) with concrete terminal proof before finalizing. |
-
 ---
 
 ## 🛠️ Technical Architecture & Reference Recipes
 
 ---
 
-
 ---
 
 ## The 3-Step Shaping Workflow
@@ -84,48 +54,3 @@ Summarize the screen contract in a concise visual outline before coding:
   ├── Secondary Actions: (e.g. Import from GitHub)
   └── Exit Point: (e.g. Redirect to /project/[id])
 ```
-
----
-
-## 🚨 Edge-Case & Failure Mode Matrix
-
-| Scenario | Risk | Mitigation Strategy |
-|:---|:---|:---|
-| **Empty or Null Inputs** | Unhandled exception or unexpected rendering collapse | Enforce fallback guards, optional chaining, and explicit empty state handlers |
-| **Network Timeout / Latency** | Hanging operations or duplicate side-effects | Implement bounded abort controllers, exponential backoff, and idempotency keys |
-| **Concurrency / Race Conditions** | Stale state overwrite or inconsistent data mutations | Use atomic transactions, mutex locking, or cancel-on-resubmit controls |
-| **Invalid Schema / Malformed Payload** | Downstream runtime errors or security injection | Validate boundary payloads with Zod/Pydantic schemas prior to execution |
-| **Resource / Memory Saturation** | OOM errors, frame drops, or memory leaks | Clean up listeners, cancel active timers, and enforce pagination/virtualization |
-
----
-
-## 🤖 LLM-Specific Traps Table
-
-| Anti-Pattern | What AI Commonly Does Wrong | What Is Actually Correct |
-|:---|:---|:---|
-| **Uncontrolled Re-render Loop** | Mutating state inside render bodies or omitting hook dependencies | Wrap effects with explicit deps and isolate reactive derivations in useMemo |
-| **Accessibility Neglect** | Interactive <div> without role="button", tabIndex, or onKeyDown | Use semantic <button> or provide ARIA role, keyboard handlers, and focus ring |
-| **Layout Shift Flash** | Images/dynamic content without aspect-ratio or explicit dimensions | Enforce aspect-ratio or skeleton placeholders to guarantee zero CLS |
-
----
-
-## 🏛️ Tribunal Verification & Guardrails
-
-**Active Reviewers:** `frontend-reviewer` · `type-safety` · `ui-ux-auditor` · `complexity-reviewer`
-**Slash Command:** `/review` or `/tribunal-full`
-
-### ✅ Pre-Flight Self-Audit Checklist
-
-```
-✅ Are all component props strictly typed with zero implicit "any"?
-✅ Are responsive breakpoints, fluid typography, and optical balance verified?
-✅ Is accessibility (ARIA labels, keyboard focus, contrast) validated?
-✅ Are re-renders minimized and state lifecycles cleanly separated?
-✅ Did I verify all imported UI components and icon sets actually exist?
-```
-
-### 🛑 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 test suites, compiler success, or equivalent operational proof) that your output works as intended.

package/.agents/skills/skill-creator/SKILL.md

@@ -1,12 +1,8 @@
 ---
 name: skill-creator
-description: Use when Meta-agent specialized in expanding the framework's procedural knowledge by creating new, highly-structured SKILL.md files.
+description: "Use when Use this skill for creating new skills and iteratively improving them via a structured workflow (draft, evaluate, review, improve)."
 version: 5.0.0
 last-updated: 2026-09-13
-skills:
-  - clean-code
-  - documentation-templates
-  - fabel-protocol
 tools: Read, Grep, Glob, Bash, Edit, Write
 scripts-binding:
   - .agent/scripts/skill_integrator.js
@@ -14,123 +10,168 @@ scripts-binding:
   - .agent/scripts/lint_runner.js
 ---
 
-# Skill Creator — Meta-Skill Builder
+# /skill-creator — Skill Creation & Iterative Improvement Engine
 
-## Mandatory Pre-Flight Context Inspection
+A specialized meta-skill workflow for creating, evaluating, and iteratively refining new AI skills. 
+This skill guides the process from capturing intent to writing the skill, testing it with baseline comparisons, and optimizing its triggering description.
 
-Before generating, refactoring, or reviewing code in the `skill-creator` domain, inspect these 5 critical parameters:
+---
 
-1. **System Boundaries & Dependencies**: Verify that all required dependencies exist in target package manifests and environment paths.
-2. **Runtime Context & Platform Invariants**: Confirm target platform constraints (Node.js, Browser, Mobile OS, Edge runtime) before applying APIs.
-3. **Execution Guardrails**: Identify potential side-effects, state mutations, and unhandled asynchronous exceptions.
-4. **Validation & Type Contracts**: Validate input data schemas and strict type constraints across all module interfaces.
-5. **Observability & Proof of Execution**: Ensure execution produces tangible verification signals (terminal output, tests, metrics).
 
-## Activation Boundaries
+---
 
-- **Activate when:** Use when Meta-agent specialized in expanding the framework's procedural knowledge by creating new, highly-structured SKILL.md files.
-- **DO NOT activate when:** The task falls outside the `skill-creator` domain or is managed by a different dedicated specialist.
+## 🔁 The Skill Creation Loop
 
-## 🔁 Multi-Pass Execution Protocol
+Execute the creation process using this high-level loop:
+1. Decide what the skill should do and how.
+2. Write a draft of the skill (`SKILL.md`).
+3. Create test prompts and run Claude with access to the skill.
+4. Help the user evaluate results (qualitatively and quantitatively).
+5. While runs happen, draft quantitative evals.
+6. Use the eval-viewer (`generate_review.py`) to show results to the user.
+7. Rewrite the skill based on feedback.
+8. Repeat until satisfied, then run the description optimizer.
 
-Execute all non-trivial tasks through this 7-pass cognitive loop:
+---
 
-| Pass | Phase | Core Action |
-|:---|:---|:---|
-| **Pass 1** | **Understand** | Deconstruct the user's explicit objective, implicit requirements, and platform constraints. |
-| **Pass 2** | **Plan** | Decompose the task into smallest logical steps; map dependencies and required tool calls. |
-| **Pass 3** | **Execute** | Implement the solution with production-grade craft, zero placeholders, and strict typing. |
-| **Pass 4** | **Verify** | Run linters, unit tests, or compiler checks to validate structural correctness. |
-| **Pass 5** | **Attack** | Perform an adversarial review searching for edge-case failures, race conditions, and traps. |
-| **Pass 6** | **Improve** | Eliminate discovered friction, optimize performance, and harden error boundaries. |
-| **Pass 7** | **Quality Gate** | Enforce Verification-Before-Completion (VBC) with concrete terminal proof before finalizing. |
+## Phase 1 — Capture Intent & Interview
 
----
+Start by understanding the skill requirements. Ask clarifying questions:
+- What should this skill enable Claude to do?
+- When should this skill trigger? (What user phrases/contexts?)
+- What's the expected output format?
+- Should we set up test cases? (Yes for objective tasks like file transforms; maybe no for subjective ones like writing style).
 
-## 🛠️ Technical Architecture & Reference Recipes
+**Research**: Check available MCPs for research via subagents or inline. Come prepared to reduce the burden on the user.
 
 ---
 
+## Phase 2 — Write the SKILL.md
 
-## The V4 Hybrid Skill Specification
+Based on the interview, draft the skill components.
 
-Every newly authored `SKILL.md` must strictly adhere to this 6-part structure:
+- **name**: Skill identifier.
+- **description**: Make it slightly "pushy". Include what it does AND specific contexts to trigger it. 
+  - *Example*: Instead of "Build a dashboard", use "Use this skill whenever the user mentions dashboards, data visualization, internal metrics, or wants to display any kind of company data, even if they don't explicitly ask for a 'dashboard'."
 
-### 1. YAML Frontmatter
-```yaml
----
-name: [skill-name]
-description: [Clear, punchy semantic description for 2-tier lazy routing]
-tools: Read, Grep, Glob, Bash, Edit, Write
-version: 4.0.0
-last-updated: 2026-09-07
-skills:
-  - [dependency-skill-1]
-  - [dependency-skill-2]
-scripts-binding:
-  - .agent/scripts/lint_runner.js
-  - .agent/scripts/verify_all.js
----
+### Anatomy of a Skill
+```text
+skill-name/
+├── SKILL.md (required - YAML frontmatter + Markdown)
+└── Bundled Resources (optional)
+    ├── scripts/    - Executable code for deterministic tasks
+    ├── references/ - Docs loaded into context as needed
+    └── assets/     - Templates, icons, fonts
 ```
 
-### 2. Mandatory Pre-Flight Context Inspection
-Provide 3-4 numbered, actionable checkpoints requiring inspection of target config files (`package.json`, `tsconfig.json`, `pyproject.toml`) or architectural invariants before code generation.
+### Writing Rules:
+- Keep `SKILL.md` under 500 lines. Use progressive disclosure (references) for larger files.
+- **Principle of Lack of Surprise**: No malware, no exploit code, no unauthorized access.
+- Use imperative form. Explain *why* things are important instead of rigid, heavy-handed MUSTs.
+- Include clear input/output examples.
+- **Look for repeated work**: If test cases show subagents independently writing similar helper scripts (e.g. `create_docx.py`), bundle that script into `scripts/` and instruct the skill to use it!
 
-### 3. Activation Boundaries
-Explicitly define:
-- `- **Activate when:** [Exact stack, problem type, or file pattern]`
-- `- **DO NOT activate when:** [Out-of-scope scenarios; specify which specialist/skill to defer to]`
-
-### 4. 2026 Performance & Logic Invariants
-Provide 3-5 hard technical invariants for the domain (e.g., O(1) lookups, streaming backpressure, React 19 direct ref, Python 3.12 PEP 695 generics, zero `.unwrap()` in Rust).
+---
 
-### 5. Hallucination Trap Table (Read First)
-Provide concrete `❌ BAD (Deprecated / Inefficient)` vs `✅ GOOD (2026 Standard)` patterns. Never use abstract advice.
+## Phase 3 — Test Cases & Evaluation
+
+After drafting, create 2-3 realistic test prompts and share them with the user.
+
+Save prompts to `evals/evals.json` (draft assertions later):
+```json
+{
+  "skill_name": "example-skill",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "User's task prompt",
+      "expected_output": "Description of expected result",
+      "files": []
+    }
+  ]
+}
+```
 
-### 6. Actionable Implementation Rules & Code Blocks
-Provide copy-paste ready, production-grade code snippets showcasing idiomatic modern patterns.
+### Evaluation Execution Protocol (Crucial!)
+1. **Spawn All Runs at Once**: Spawn both with-skill AND baseline subagents in the *same turn*. Save outputs to `<workspace>/iteration-<N>/eval-<ID>/with_skill/outputs/` and `without_skill/outputs/` (or `old_skill/outputs/`).
+2. **Draft Assertions While Running**: While runs are ongoing, draft quantitative assertions. Good assertions are objectively verifiable and have descriptive names. Update `eval_metadata.json` and `evals/evals.json`.
+3. **Capture Timing Data**: Capture `total_tokens` and `duration_ms` from task notifications immediately to `timing.json` inside the run directory.
+4. **Grade and Aggregate**: 
+   - Grade each run using an automated grading agent. Save to `grading.json`.
+   - Aggregate into benchmark: `python -m scripts.aggregate_benchmark <workspace>/iteration-N --skill-name <name>`
+5. **Launch Eval Viewer**:
+   ```bash
+   nohup python <skill-creator-path>/eval-viewer/generate_review.py \
+     <workspace>/iteration-N \
+     --skill-name "my-skill" \
+     --benchmark <workspace>/iteration-N/benchmark.json \
+     > /dev/null 2>&1 &
+   VIEWER_PID=$!
+   ```
+   *For iteration 2+, add `--previous-workspace <workspace>/iteration-<N-1>`.*
 
 ---
 
-## 🚨 Edge-Case & Failure Mode Matrix
+## Phase 4 — Review & Improve
 
-| Scenario | Risk | Mitigation Strategy |
-|:---|:---|:---|
-| **Empty or Null Inputs** | Unhandled exception or unexpected rendering collapse | Enforce fallback guards, optional chaining, and explicit empty state handlers |
-| **Network Timeout / Latency** | Hanging operations or duplicate side-effects | Implement bounded abort controllers, exponential backoff, and idempotency keys |
-| **Concurrency / Race Conditions** | Stale state overwrite or inconsistent data mutations | Use atomic transactions, mutex locking, or cancel-on-resubmit controls |
-| **Invalid Schema / Malformed Payload** | Downstream runtime errors or security injection | Validate boundary payloads with Zod/Pydantic schemas prior to execution |
-| **Resource / Memory Saturation** | OOM errors, frame drops, or memory leaks | Clean up listeners, cancel active timers, and enforce pagination/virtualization |
+1. Read user feedback from `feedback.json` once the user clicks "Submit All Reviews".
+2. **Improve**: Generalize from the feedback. Don't overfit to specific examples. Keep the prompt lean. Explain the *why* behind your instructions.
+3. Rerun the iteration loop (apply improvements, rerun tests, launch reviewer) until the user is satisfied or feedback is empty.
+4. Kill the viewer server when done: `kill $VIEWER_PID 2>/dev/null`
 
 ---
 
-## 🤖 LLM-Specific Traps Table
+## Phase 5 — Description Optimization (Triggering)
+
+Optimize the `description` to ensure Claude triggers the skill correctly.
+
+1. **Generate Eval Queries**: Create 20 queries (10 should-trigger, 10 should-not-trigger) in JSON format.
+   - *Should-trigger*: Concrete, specific, messy real-world prompts (e.g. "my boss sent me this xlsx...").
+   - *Should-not-trigger*: Near-misses, adjacent domains, genuinely tricky cases.
+2. **Review with User**: Use the `assets/eval_review.html` template. Replace placeholders and open in browser. Wait for the user to export `eval_set.json` (check `~/Downloads/`).
+3. **Run Optimization Loop** (in background):
+   ```bash
+   python -m scripts.run_loop \
+     --eval-set <path-to-trigger-eval.json> \
+     --skill-path <path-to-skill> \
+     --model <model-id-powering-this-session> \
+     --max-iterations 5 \
+     --verbose
+   ```
+4. Apply the `best_description` from the output to the skill's frontmatter.
+
+---
 
-| Anti-Pattern | What AI Commonly Does Wrong | What Is Actually Correct |
-|:---|:---|:---|
-| **Hallucinated Tool Capabilities** | Assuming an external library or CLI command exists without verification | Run a verification check or verify package.json before referencing tools |
-| **Premature Completion Claim** | Declaring a task finished because code was generated without verification | Execute tests, linters, or terminal commands to provide concrete proof |
-| **Context Bloat Dumping** | Pasting entire multi-thousand-line files into prompt context | Extract targeted excerpts, symbols, and signatures to preserve tokens |
+## Final Step — Package & Present
+
+If the `present_files` tool is available:
+```bash
+python -m scripts.package_skill <path/to/skill-folder>
+```
+Present the `.skill` file path to the user for installation.
 
 ---
 
-## 🏛️ Tribunal Verification & Guardrails
+## Claude.ai / Cowork Specific Adaptations
 
-**Active Reviewers:** `orchestrator` · `agent-organizer` · `logic-reviewer`
-**Slash Command:** `/review` or `/tribunal-full`
+- **Claude.ai (No Subagents)**: Do test cases yourself serially. Skip baseline runs. Skip the browser reviewer—present results directly in chat. Skip description optimization (requires CLI).
+- **Cowork**: You have subagents. Use `--static <output_path>` for `generate_review.py` to write standalone HTML, as there is no browser display. Provide the HTML link to the user.
+  - **CRITICAL**: GENERATE THE EVAL VIEWER BEFORE evaluating inputs yourself. You want to get them in front of the human ASAP!
+
+---
 
-### ✅ Pre-Flight Self-Audit Checklist
+## 🚨 Guardrails & Hallucination Traps
 
 ```
-✅ Did I deconstruct the root objective before proposing architecture?
-✅ Did I identify dependencies, bottlenecks, and parallelizable sub-tasks?
-✅ Did I avoid over-engineering and select the simplest effective pattern?
-✅ Did I verify assumptions with concrete file reads instead of speculation?
-✅ Did I establish measurable verification criteria before completion?
+❌ Never stop partway through the evaluation sequence.
+❌ Never spawn with-skill runs and baselines in separate turns.
+❌ Never write "ALWAYS" or "NEVER" in all caps if you can explain the reasoning instead.
+❌ Never use simple/trivial queries for trigger evals (e.g., "format data").
+✅ Always generate the eval viewer for the human to look at examples before revising the skill yourself.
 ```
 
-### 🛑 Verification-Before-Completion (VBC) Protocol
+## 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 test suites, compiler success, or equivalent operational proof) that your output works as intended.
+**Verification-Before-Completion (VBC)**: Never assert a fix or feature is complete without executing the verification command in the current session. Evidence before claims always.
+1. Run `python -m scripts.run_loop --eval-set <eval.json>` to verify description triggers.
+2. Produce HTML viewer and get human approval before finishing.