tribunal-kit 5.8.2 → 5.8.4

package/.agent/skills/svg-animation/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: svg-animation
+description: SVG stroke draw-on effects, path morphing, animated icons, motion paths, and interactive vector graphics.
+version: 1.0.0
+last-updated: 2026-07-22
+applies-to-model: gemini-3-6-flash, claude-3-7-sonnet
+routing:
+  domain: Vector SVG Motion & Path Animation
+  tier: pro
+  co-requires: [morphing-icons, 60fps-animation]
+  trigger-signals:
+    strong: [svg-animation, stroke draw-on, path morphing, animated SVG, SVG stroke-dasharray, motion path]
+    weak: [svg motion, animated icon]
+---
+
+# SVG Animation — Stroke Draw-On & Path Morphing
+
+Craft crisp, resolution-independent vector animations using CSS, Framer Motion, or GSAP.
+
+---
+
+## 3 SVG Motion Techniques
+
+### 1. Pure CSS Stroke Draw-On Effect
+```css
+@keyframes draw-path {
+  from { stroke-dashoffset: 1000; }
+  to { stroke-dashoffset: 0; }
+}
+
+.draw-signature-path {
+  stroke-dasharray: 1000;
+  stroke-dashoffset: 1000;
+  animation: draw-path 1.8s cubic-bezier(0.65, 0, 0.35, 1) forwards;
+}
+```
+
+### 2. Framer Motion SVG Path Length Animation
+```tsx
+import { motion } from "framer-motion";
+
+export function DrawCheckmark() {
+  return (
+    <svg className="w-8 h-8 stroke-emerald-500 stroke-2 fill-none" viewBox="0 0 24 24">
+      <motion.path
+        d="M5 13l4 4L19 7"
+        initial={{ pathLength: 0 }}
+        animate={{ pathLength: 1 }}
+        transition={{ duration: 0.4, ease: "easeOut" }}
+      />
+    </svg>
+  );
+}
+```
+
+### 3. SVG Path Morphing (GSAP MorphSVGPlugin)
+- Morph between 2 vector paths with identical point counts or using GSAP MorphSVG:
+```javascript
+gsap.to("#start-shape", {
+  morphSVG: "#end-shape",
+  duration: 0.6,
+  ease: "power2.inOut"
+});
+```
+
+---
+
+## 🤖 LLM-Specific Traps
+
+1. **Incorrect `stroke-dasharray` Length**: Guessing path lengths without measuring `path.getTotalLength()`, resulting in clipped or incomplete draw-on animations.
+2. **Missing `fill="none"`**: Forgetting `fill="none"` on draw-on stroke paths, causing black fill shapes during path animation.
+
+---
+
+## 🏛️ Tribunal Integration (Anti-Hallucination)
+
+**Active reviewers: `frontend-reviewer` · `motion-reviewer`**
+
+### ✅ Pre-Flight Self-Audit
+
+```
+✅ Is `stroke-dasharray` calibrated to match the true SVG path length?
+✅ Is `vector-effect="non-scaling-stroke"` applied if SVG elements scale responsively?
+```
+
+### 🛑 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/swiss-design/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: swiss-design
+description: International Typographic Style (Swiss Design) principles for web interfaces. Strict grid discipline, asymmetric layouts, bold typographic contrast, flush-left un-justified text, and mathematical negative space.
+version: 1.0.0
+last-updated: 2026-07-22
+applies-to-model: gemini-3-6-flash, claude-3-7-sonnet
+routing:
+  domain: Print-Inspired UI & Swiss Typography
+  tier: pro
+  co-requires: [better-typography, baseline-ui, industrial-brutalist-ui]
+  trigger-signals:
+    strong: [swiss-design, Swiss style UI, International Typographic Style, grid discipline, Helvetica layout, print inspired web]
+    weak: [swiss layout, grid UI]
+---
+
+# Swiss Design — International Typographic Style for Web
+
+Architect pristine, print-inspired interfaces grounded in grid discipline, objective clarity, and asymmetric typographic hierarchy.
+
+---
+
+## 4 Swiss Design Pillars
+
+### 1. Strict Grid Alignment
+- Every layout element MUST align strictly to a visible or invisible 12-column grid.
+- Border dividers use thin, sharp 1px solid lines matching `--foreground` opacity (e.g. `border-color: rgba(0,0,0,0.15)`).
+
+### 2. High-Contrast Sans-Serif Typography
+- Use clean grotesque sans-serif fonts (Helvetica, Inter, Geist, Neue Haas Grotesk).
+- Pair large bold display titles (`3rem+`, `font-weight: 700`, `letter-spacing: -0.03em`) with clean flush-left, rag-right body copy (`text-align: left`).
+
+### 3. Asymmetric Structural Balance
+- Reject centered, symmetrical layouts. Align headings and content to strong left vertical axes, using generous negative space to anchor visual weight.
+
+### 4. Mathematical Numbering & Labels
+- Use small uppercase metadata badges (`SECTION 01 // OVERVIEW`) with tracking (`letter-spacing: 0.08em`) and monospace or tabular numbers (`font-variant-numeric: tabular-nums`).
+
+---
+
+## 🤖 LLM-Specific Traps
+
+1. **Justified Text Alignment**: Setting `text-align: justify` which creates uneven, ugly gaps ("rivers") between words. Use `text-align: left`.
+2. **Centered Text Overuse**: Centering body text paragraphs. Keep content strictly left-aligned.
+
+---
+
+## 🏛️ Tribunal Integration (Anti-Hallucination)
+
+**Active reviewers: `frontend-reviewer` · `ui-ux-auditor`**
+
+### ✅ Pre-Flight Self-Audit
+
+```
+✅ Are all text paragraphs aligned flush-left (`text-align: left`)?
+✅ Is layout structured on an explicit grid axis with generous negative space?
+✅ Are tabular numbers (`tabular-nums`) used for numbered section markers?
+```
+
+### 🛑 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/taste-skill/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: taste-skill
+description: Senior UI/UX frontend skill that enforces anti-slop design decisions, motion quality, visual rhythm, micro-craft, and architectural discipline.
+version: 1.0.0
+last-updated: 2026-07-22
+applies-to-model: gemini-3-6-flash, claude-3-7-sonnet
+routing:
+  domain: Design Taste & Anti-Slop Discipline
+  tier: pro
+  co-requires: [better-ui, impeccable, frontend-design]
+  trigger-signals:
+    strong: [taste-skill, design taste, anti-slop, frontend craft discipline, high taste UI]
+    weak: [taste, good design]
+---
+
+# Taste Skill — Senior Design Taste & Anti-Slop Discipline
+
+Enforce senior-level design taste, anti-slop constraints, and visual craft across every component.
+
+---
+
+## The 5 Rules of Design Taste
+
+### 1. Banned AI Visual Clichés (Zero Tolerance)
+- ❌ Purple/violet gradient backgrounds (`from-purple-600 to-indigo-600`).
+- ❌ Glowing neon borders on every card element.
+- ❌ Floating 3D spheres or generic iridescent mesh gradients.
+- ❌ Identical Bento Box 3-column grids on every page.
+
+### 2. High-Fidelity Typography
+- Typography accounts for 80% of interface perception.
+- Display headings must use negative tracking (`-0.025em`) and balanced text wrapping (`text-wrap: balance`).
+- Body text line length MUST be bounded to `65ch` max width.
+
+### 3. Spatial System Strictness
+- Never use arbitrary `px` paddings or margins (`margin-top: 17px`).
+- Enforce strict 8px spatial grid math (`4px`, `8px`, `12px`, `16px`, `24px`, `32px`, `48px`, `64px`).
+
+### 4. Tactile Micro-Feedback
+- All interactive controls MUST respond to press with `transform: scale(0.97)` on `:active` with transition duration $\le 160\text{ms}$.
+
+### 5. Multi-Layer Depth Over Flat Lines
+- Replace harsh black borders with multi-layer ambient drop shadows and subtle 8% opacity surface outlines.
+
+---
+
+## 🤖 LLM-Specific Traps
+
+1. **Defaulting to Plain Templates**: Producing boring, unstyled HTML buttons with zero hover/active states.
+2. **Ignoring Dark Mode Depth**: Leaving card backgrounds flat black (`#000000`) without surface lightness progression.
+
+---
+
+## 🏛️ Tribunal Integration (Anti-Hallucination)
+
+**Active reviewers: `frontend-reviewer` · `ui-ux-auditor`**
+
+### ✅ Pre-Flight Self-Audit
+
+```
+✅ Are generic purple gradients and glowing borders completely avoided?
+✅ Is text length bounded to 65ch max width for body paragraphs?
+✅ Do interactive elements feature tactile press feedback (`scale(0.97)`)?
+```
+
+### 🛑 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/tdd-workflow/SKILL.md

@@ -1,206 +1,77 @@
 ---
 name: tdd-workflow
 description: Test-Driven Development (TDD) mastery. Red-Green-Refactor cycles, behavior-driven design (BDD), strict mutation coverage, test doubles (mocks/stubs/spies), and avoiding test-induced design damage. Use when building complex algorithms, deep business logic, or strictly regulated systems.
-allowed-tools: Read, Write, Edit, Glob, Grep
-version: 2.0.0
-last-updated: 2026-04-02
-applies-to-model: gemini-2.5-pro, claude-3-7-sonnet
+version: 1.0.0
+last-updated: 2026-07-22
+applies-to-model: gemini-3-6-flash, claude-3-7-sonnet
 routing:
-  domain: general
-  tier: basic
+  domain: Test-Driven Development & Quality Assurance
+  tier: pro
+  co-requires: [webapp-testing, clean-code]
+  trigger-signals:
+    strong: [tdd-workflow, red green refactor, test driven development, TDD, slice by slice testing, write test first]
+    weak: [write test, unit test logic]
 ---
 
-## Hallucination Traps (Read First)
+# TDD Workflow — Red-Green-Refactor Mastery
 
-- ❌ Writing tests that test implementation details instead of behavior -> ✅ Test WHAT it does (inputs/outputs), not HOW (internal methods)
-- ❌ Skipping the Red phase (writing a failing test first) -> ✅ If the test passes before you write the code, it tests nothing
-- ❌ Refactoring during the Red or Green phase -> ✅ Red: write failing test. Green: make it pass minimally. THEN refactor. Never mix phases
+Build features and fixes one slice at a time using strict Test-Driven Development (TDD) discipline.
 
 ---
 
-# Test-Driven Development (TDD) — Defect-Free Execution Mastery
+## The 3-Phase TDD Cycle
 
----
-
-## 1. The Red-Green-Refactor Cycle
-
-TDD is a strict, irrevocable discipline. Do not write the implementation first.
-
-### Step 1: RED (Write the failing test)
-
-Write the test as if the API already exists exactly how you _wish_ it were designed.
-Run the test. It MUST fail (because the function doesn't exist, or returns the wrong value). If it passes, the test is useless.
-
-```typescript
-// 1. The failing test
-import { calculateDiscount } from "./pricing";
-
-test("Should apply 10% discount for orders over $100", () => {
-  expect(calculateDiscount(150)).toBe(135);
-});
-// ❌ FAILS: calculateDiscount is not defined
 ```
-
-### Step 2: GREEN (Make it pass exactly)
-
-Write the absolute minimum, dumbest code required to make the test pass. Do not over-engineer.
-
-```typescript
-// 2. The minimum implementation
-export function calculateDiscount(subtotal: number): number {
-  if (subtotal >= 100) return subtotal * 0.9;
-  return subtotal;
-}
-// ✅ PASSES.
+[ 1. RED ]    Write a failing behavioral test for the minimal next requirement.
+                  ↓
+[ 2. GREEN ]  Write the simplest production code to make the test pass.
+                  ↓
+[ 3. REFACTOR ] Clean up code & duplicate logic while ensuring tests stay green.
 ```
 
-### Step 3: REFACTOR
-
-Now wrap the implementation in clean architectural principles. The tests guarantee you haven't broken the behavior while you optimize.
-
-```typescript
-// 3. The Refactor
-const DISCOUNT_THRESHOLD = 100;
-const DISCOUNT_RATE = 0.9;
-
-export function calculateDiscount(subtotal: number): number {
-  return subtotal >= DISCOUNT_THRESHOLD ? subtotal * DISCOUNT_RATE : subtotal;
-}
-// ✅ STILL PASSES. Safe to commit.
-```
-
----
-
-## 2. Test Doubles (Mocks, Stubs, Spies)
-
-Knowing _how_ to mock separates amateurs from professionals. Over-mocking destroys architectural integrity.
-
-| Type      | When to use                                          | Example                                                  |
-| :-------- | :--------------------------------------------------- | :------------------------------------------------------- |
-| **Dummy** | Filler objects passed but never used                 | `processOrder(new UserDummy(), payload)`                 |
-| **Stub**  | Hardcodes a specific response                        | `db.getUser.mockResolvedValue({ id: 1 })`                |
-| **Spy**   | Records how many times a function was called         | `expect(emailService.send).toHaveBeenCalledTimes(1)`     |
-| **Mock**  | A spy with predefined expectations of exact payloads | `expect(logger.info).toHaveBeenCalledWith('Authorized')` |
-
-### The Mocking Rule
-
-**Only mock at the architectural boundaries (Database, Network, External FileSystem).**
-NEVER mock internal business logic or child pure-functions. If function A calls function B, test A by allowing it to genuinely call B.
-
 ---
 
-## 3. Anti-Pattern: Testing Implementation Details
+## 4 TDD Rules
 
-Tests should verify the _behavior_ output, not the underlying code structure.
+### 1. Test Behavior, Not Implementation Details
+- Assert GIVEN / WHEN / THEN behavior results, NOT private class methods or internal variables.
 
 ```typescript
-class Account {
-  private balance = 0;
-  deposit(amount: number) {
-    this.balance += amount;
-  }
-  getBalance() {
-    return this.balance;
-  }
-}
-
-// ❌ BAD: Testing internal state (Fragile)
-test("Deposit updates the internal balance variable", () => {
-  const acc = new Account();
-  acc.deposit(50);
-  expect(acc["balance"]).toBe(50); // Intrusive test breaks if variable is renamed
-});
-
-// ✅ GOOD: Testing external behavior contract
-test("Deposit makes the funds available via getBalance", () => {
-  const acc = new Account();
-  acc.deposit(50);
-  expect(acc.getBalance()).toBe(50); // Tests the public API only
-});
-```
+// ❌ BAD: Coupling test to internal state
+expect(calculator._memoryBuffer).toBe(42);
 
----
-
----
-
-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.
-
----
-
-**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.
-
-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?
+// ✅ GOOD: Asserting public behavior contract
+expect(calculator.add(40, 2)).toBe(42);
 ```
 
-### 🛑 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.
+### 2. The Minimal Green Rule
+- In Step 2 (GREEN), write ONLY the minimal code required to pass the test—even if it's hardcoding a return value initially. This forces you to write the next test that proves the hardcoded value inadequate.
 
-## Pre-Flight Checklist
+### 3. Mock Only External Boundaries
+- Never mock internal domain entities or utility functions. Mock ONLY un-owned external boundaries (database IO, network APIs, payment gateways).
 
-- [ ] Have I reviewed the user's specific constraints and requests?
-- [ ] Have I checked the environment for relevant existing implementations?
-
-## VBC Protocol (Verification-Before-Completion)
-
-You MUST verify existing code signatures and variables before attempting to modify or call them. No hallucination is permitted.
+### 4. Triangulation Strategy
+- When uncertain about algorithm logic, write 2 or more tests with different inputs to force general implementation.
 
 ---
 
 ## 🤖 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.
+1. **Writing Code First, Tests Later**: Generating 200 lines of implementation code and adding tests as an afterthought.
+2. **Fragile Mock Over-use**: Mocking every internal dependency, creating brittle tests that break during refactoring.
 
 ---
 
 ## 🏛️ 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.
+**Active reviewers: `test-engineer` · `logic-reviewer`**
 
 ### ✅ 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?
+✅ Was the failing test written and verified BEFORE writing implementation code?
+✅ Does the test assert external behavior rather than internal private state?
+✅ Are mocks restricted strictly to external IO boundaries?
 ```
 
 ### 🛑 Verification-Before-Completion (VBC) Protocol

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

@@ -21,7 +21,7 @@ You are a specialist in analyzing test output — not writing tests, but _unders
 - 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 `test_runner.js` or any test command exits with failures.
 - When paired with `systematic-debugging` for deep root-cause investigation.
 
 ## Analysis Pipeline

package/.agent/skills/thermo-nuclear-code-quality-review/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: thermo-nuclear-code-quality-review
+description: Run an extremely strict maintainability review for abstraction quality, giant files, spaghetti-condition growth, and architectural debt.
+version: 1.0.0
+last-updated: 2026-07-22
+applies-to-model: gemini-3-6-flash, claude-3-7-sonnet
+routing:
+  domain: Ultra-Strict Code Quality Review
+  tier: pro
+  co-requires: [clean-code, codebase-design, code-review-checklist]
+  trigger-signals:
+    strong: [thermo-nuclear-code-quality-review, strict code review, maintainability audit, spaghetti code review, giant file audit, strict maintainability]
+    weak: [deep review, strict audit]
+---
+
+# Thermo-Nuclear Code Quality Review — Zero-Tolerance Maintainability Audit
+
+Execute a ruthless, zero-tolerance code maintainability audit targeting abstraction leaks, file bloat, and spaghetti conditionals.
+
+---
+
+## 5 Zero-Tolerance Audit Rules
+
+### 1. File Size Hard Limit (Max 300 Lines)
+- Flag ANY single file exceeding 300 lines of code. Demand decomposition into modular helper components or sub-packages.
+
+### 2. Cyclomatic Complexity & Nested Conditionals (Max 3 Levels)
+- Flag any function with nested conditionals deeper than 3 levels (`if -> if -> if -> for`). Require early guard clause returns.
+
+```typescript
+// ❌ REJECTED: Deep nested spaghetti
+function processOrder(order: Order) {
+  if (order) {
+    if (order.isValid) {
+      if (order.items.length > 0) {
+        // Business logic hidden 4 levels deep
+      }
+    }
+  }
+}
+
+// ✅ APPROVED: Early guard returns
+function processOrder(order: Order) {
+  if (!order || !order.isValid) return;
+  if (order.items.length === 0) return;
+  // Business logic at top indentation level
+}
+```
+
+### 3. Magic Values & String Literals
+- Hardcoded status strings (`"PENDING_APPROVAL_V2"`) or raw numbers (`86400000`) outside central `const` or `enum` declarations trigger immediate failure.
+
+### 4. Direct Dependency Coupling
+- Modules importing concrete database models or vendor SDKs directly inside domain business logic instead of interface adapters are rejected.
+
+---
+
+## 🤖 LLM-Specific Traps
+
+1. **Permissive Approvals**: Giving "looks good to me" approvals on 800-line monolithic files with nested conditionals.
+2. **Superficial Formatting Fixes**: Focusing on trailing commas instead of architectural complexity and file bloat.
+
+---
+
+## 🏛️ Tribunal Integration (Anti-Hallucination)
+
+**Active reviewers: `complexity-reviewer` · `logic-reviewer` · `type-safety`**
+
+### ✅ Pre-Flight Self-Audit
+
+```
+✅ Are all files under the 300-line size threshold?
+✅ Has cyclomatic nesting depth been reduced to $\le 3$ levels via guard clauses?
+✅ Are all magic numbers and status strings extracted into typed constants?
+```
+
+### 🛑 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/to-spring-or-not-to-spring/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: to-spring-or-not-to-spring
+description: Audit and decide when to use physics-based spring animations (stiffness, damping, mass) vs duration-based cubic-bezier easing curves.
+version: 1.0.0
+last-updated: 2026-07-22
+applies-to-model: gemini-3-6-flash, claude-3-7-sonnet
+routing:
+  domain: Motion Physics & Animation Decisions
+  tier: pro
+  co-requires: [emil-design-eng, framer-motion-expert]
+  trigger-signals:
+    strong: [to-spring-or-not-to-spring, spring physics, spring animation vs cubic bezier, stiffness damping mass, motion physics decision]
+    weak: [spring animation, spring vs easing]
+---
+
+# To Spring or Not to Spring — Motion Physics Decision Matrix
+
+Decide when to use physics-driven spring models (Framer Motion / Reanimated) vs duration-based cubic-bezier easing curves.
+
+---
+
+## Spring vs Duration Decision Matrix
+
+| Motion Scenario | Use Spring Physics? | Recommended Parameters / Curve |
+| --- | --- | --- |
+| **Interruptible Gestures** (Drag, Swipe, Sheet pull) | ✅ **ALWAYS** | `type: "spring", stiffness: 300, damping: 30` (adapts to drag velocity) |
+| **Button Press Feedback** (`:active`) | ❌ **NO (Use Curve)** | `transition: transform 120ms cubic-bezier(0.2, 0, 0, 1)` |
+| **Modal / Dialog Entrance** | ❌ **NO (Use Curve)** | `transition: all 220ms cubic-bezier(0.16, 1, 0.3, 1)` |
+| **Badge Bouncing / Celebration** | ✅ **YES** | `type: "spring", stiffness: 400, damping: 15` (intentional overshoot bounce) |
+| **Page / Route Transitions** | ❌ **NO (Use Curve)** | `transition: opacity 200ms ease-out` |
+| **Toggle Switch Flip** | ✅ **YES** | `type: "spring", stiffness: 500, damping: 35` (crisp snap without wobble) |
+
+---
+
+## 3 Core Spring Parameters
+
+1. **Stiffness** (Rigidity): High stiffness ($400+$) = snappy and tight; Low stiffness ($100$) = slow and lazy.
+2. **Damping** (Friction): High damping ($30+$) = zero overshoot bounce; Low damping ($10$) = heavy oscillating bounce.
+3. **Mass** (Weight): Higher mass ($2.0$) = feels heavy with momentum inertia.
+
+---
+
+## 🤖 LLM-Specific Traps
+
+1. **Bouncy Springs on Modals**: Adding low-damping bouncy springs to popovers or modals, making popovers wobble on screen.
+2. **Fixed Duration Springs**: Setting `duration: 0.5` alongside `type: "spring"` in Framer Motion, which overrides natural spring physics.
+
+---
+
+## 🏛️ Tribunal Integration (Anti-Hallucination)
+
+**Active reviewers: `motion-reviewer`**
+
+### ✅ Pre-Flight Self-Audit
+
+```
+✅ Are spring physics restricted to gestures, toggles, drag targets, and playful badges?
+✅ Are modals, dropdowns, and route transitions using deterministic cubic-bezier curves?
+```
+
+### 🛑 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.