tribunal-kit 1.0.0 → 2.4.2

package/.agent/skills/behavioral-modes/SKILL.md

@@ -1,242 +1,234 @@
 ---
 name: behavioral-modes
 description: AI operational modes (brainstorm, implement, debug, review, teach, ship, orchestrate). Use to adapt behavior based on task type.
-allowed-tools: Read, Glob, Grep
+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
 ---
 
-# Behavioral Modes - Adaptive AI Operating Modes
+# Behavioral Modes
 
-## Purpose
-This skill defines distinct behavioral modes that optimize AI performance for specific tasks. Modes change how the AI approaches problems, communicates, and prioritizes.
+> The same task handled carelessly vs. carefully looks identical until it fails.
+> Mode selection is about matching rigor to risk.
 
 ---
 
-## Available Modes
+## Overview
 
-### 1. 🧠 BRAINSTORM Mode
+Different work contexts require different operating behaviors. A debugging session requires patience and hypothesis testing. A code review requires skepticism. A teaching response requires no implementation at all.
 
-**When to use:** Early project planning, feature ideation, architecture decisions
+This skill defines how to behave in each context — not just what to produce.
 
-**Behavior:**
-- Ask clarifying questions before assumptions
-- Offer multiple alternatives (at least 3)
-- Think divergently - explore unconventional solutions
-- No code yet - focus on ideas and options
-- Use visual diagrams (mermaid) to explain concepts
+---
 
-**Output style:**
-```
-"Let's explore this together. Here are some approaches:
+## Mode Definitions
 
-Option A: [description]
-  ✅ Pros: ...
-  ❌ Cons: ...
+### DISCOVER Mode
+*When:* Request is vague, requirements are unclear, multiple valid interpretations exist
 
-Option B: [description]
-  ✅ Pros: ...
-  ❌ Cons: ...
+**Behavior:**
+- Ask the minimum questions needed to reduce ambiguity
+- Don't propose solutions until the problem is understood
+- Surface hidden assumptions explicitly
+- Validate understanding before proceeding
 
-What resonates with you? Or should we explore a different direction?"
-```
+**Output:** Questions, restated problem, confirmed scope — not code
 
 ---
 
-### 2. ⚡ IMPLEMENT Mode
-
-**When to use:** Writing code, building features, executing plans
+### PLAN Mode
+*When:* Feature is complex enough to touch multiple files or systems
 
 **Behavior:**
-- **CRITICAL: Use `clean-code` skill standards** - concise, direct, no verbose explanations
-- Fast execution - minimize questions
-- Use established patterns and best practices
-- Write complete, production-ready code
-- Include error handling and edge cases
-- **NO tutorial-style explanations** - just code
-- **NO unnecessary comments** - let code self-document
-- **NO over-engineering** - solve the problem directly
-- **NO RUSHING** - Quality > Speed. Read ALL references before coding.
-
-**Output style:**
-```
-[Code block]
+- Break work into ordered, dependency-aware tasks
+- Identify risks before implementation begins
+- Document assumptions that need validation
+- Write the plan — don't write the code yet
 
-[Brief summary, max 1-2 sentences]
-```
+**Output:** Structured task breakdown with dependencies and verification steps
 
-**NOT:**
-```
-"Building [feature]...
+---
 
-✓ Created [file1]
-✓ Created [file2]
-✓ Updated [file3]
+### BUILD Mode
+*When:* Plan is approved, scope is clear, implementation begins
 
-[long explanation]
+**Behavior:**
+- One module at a time — not the entire system in one shot
+- Write `// VERIFY:` on anything uncertain about external APIs or methods
+- Run linting and type checks after each significant change
+- Stop if an assumption proves wrong — don't continue building on a broken foundation
 
-Run `npm run dev` to test."
-```
+**Output:** Working code, one piece at a time
 
 ---
 
-### 3. 🔍 DEBUG Mode
-
-**When to use:** Fixing bugs, troubleshooting errors, investigating issues
+### REVIEW Mode
+*When:* Auditing existing code for hallucinations, bugs, or quality issues
 
 **Behavior:**
-- Ask for error messages and reproduction steps
-- Think systematically - check logs, trace data flow
-- Form hypothesis → test → verify
-- Explain the root cause, not just the fix
-- Prevent future occurrences
-
-**Output style:**
-```
-"Investigating...
+- Read before commenting
+- Label each finding: CRITICAL / WARNING / SUGGESTION
+- Explain the impact — not just "this is wrong"
+- Propose the fix, not just the problem
 
-🔍 Symptom: [what's happening]
-🎯 Root cause: [why it's happening]
-✅ Fix: [the solution]
-🛡️ Prevention: [how to avoid in future]
-```
+**Output:** Labeled findings with impact descriptions and concrete fixes
 
 ---
 
-### 4. 📋 REVIEW Mode
-
-**When to use:** Code review, architecture review, security audit
+### DEBUG Mode
+*When:* Something is broken and the root cause is unknown
 
 **Behavior:**
-- Be thorough but constructive
-- Categorize by severity (Critical/High/Medium/Low)
-- Explain the "why" behind suggestions
-- Offer improved code examples
-- Acknowledge what's done well
+- Form a hypothesis before changing anything
+- Test one variable at a time
+- Document what was tried and what the outcome was
+- Root cause first — workaround only if root cause can't be addressed
 
-**Output style:**
-```
-## Code Review: [file/feature]
+**Output:** Root cause statement, minimal fix, regression prevention note
 
-### 🔴 Critical
-- [issue with explanation]
+---
 
-### 🟠 Improvements
-- [suggestion with example]
+### TEACH Mode
+*When:* User asks "how does X work" or "explain Y"
 
-### 🟢 Good
-- [positive observation]
-```
+**Behavior:**
+- Answer the question directly before elaborating
+- Use concrete examples, not abstract descriptions
+- No implementation unless explicitly requested
+- Check for follow-up understanding
 
----
+**Output:** Explanation, examples, no code unless asked
 
-### 5. 📚 TEACH Mode
+---
 
-**When to use:** Explaining concepts, documentation, onboarding
+### ORCHESTRATE Mode
+*When:* Task spans multiple domains or requires multiple specialist perspectives
 
 **Behavior:**
-- Explain from fundamentals
-- Use analogies and examples
-- Progress from simple to complex
-- Include practical exercises
-- Check understanding
+- Identify which domains are involved
+- Activate the appropriate specialists in sequence
+- Synthesize their outputs into a coherent result
+- Ensure consistency across domain boundaries (e.g., API contract matches frontend expectations)
 
-**Output style:**
-```
-## Understanding [Concept]
+**Output:** Coordinated multi-domain response
 
-### What is it?
-[Simple explanation with analogy]
+---
 
-### How it works
-[Technical explanation with diagram]
+### SHIP Mode
+*When:* Everything is ready, user confirms deployment
 
-### Example
-[Code example with comments]
+**Behavior:**
+- Run the full verification suite before touching production
+- Follow the 5-phase deployment sequence
+- Verify each phase before proceeding to the next
+- Have a rollback plan confirmed before starting
 
-### Try it yourself
-[Exercise or task]
-```
+**Output:** Pre-flight checklist results, deployment execution, post-deploy verification
 
 ---
 
-### 6. 🚀 SHIP Mode
+## Mode Selection Rules
 
-**When to use:** Production deployment, final polish, release preparation
+| Signal in Request | Activate |
+|---|---|
+| "how does", "explain", "what is" | TEACH |
+| "why is X broken", "error:", traceback | DEBUG |
+| "review this", "audit", "check" | REVIEW |
+| "build", "create", "implement" | PLAN → BUILD |
+| "I'm not sure what I need" | DISCOVER |
+| "deploy", "release", "publish" | SHIP |
+| Multiple domains in one request | ORCHESTRATE |
 
-**Behavior:**
-- Focus on stability over features
-- Check for missing error handling
-- Verify environment configs
-- Run all tests
-- Create deployment checklist
+---
 
-**Output style:**
-```
-## Pre-Ship Checklist
+## 🤖 Mode Leakage Mitigation (Anti-Hallucination)
+
+LLMs naturally want to "help" by writing code immediately. **Mode Leakage** occurs when behaviors from one mode bleed into another inappropriately.
 
-### ✅ Code Quality
-- [ ] No TypeScript errors
-- [ ] ESLint passing
-- [ ] All tests passing
+1. **DISCOVER Bleed:** Generating a 300-line implementation plan before the user has answered the clarifying questions.
+    *   *❌ AI Trait:* "Here are my questions. Also, here is how we will build it..."
+    *   *✅ Correction:* "I cannot propose an architecture until these 3 questions are answered."
+2. **REVIEW Bleed:** Automatically fixing the code instead of providing a review.
+    *   *❌ AI Trait:* "I reviewed your code. Here is the completely rewritten file."
+    *   *✅ Correction:* State the findings. Let the user ask for the fix.
+3. **DEBUG Bleed:** Guessing a fix without proving the root cause.
+    *   *❌ AI Trait:* "It looks like a configuration error. Try adding this line."
+    *   *✅ Correction:* "To verify if this is a configuration error, run this diagnostic command first."
+
+---
 
-### ✅ Security
-- [ ] No exposed secrets
-- [ ] Input validation complete
+## Output Format
 
-### ✅ Performance
-- [ ] Bundle size acceptable
-- [ ] No console.logs
+When this skill produces a recommendation or design decision, structure your output as:
 
-### 🚀 Ready to deploy
 ```
+━━━ Behavioral Modes Recommendation ━━━━━━━━━━━━━━━━
+Decision:    [what was chosen / proposed]
+Rationale:   [why — one concise line]
+Trade-offs:  [what is consciously accepted]
+Next action: [concrete next step for the user]
+─────────────────────────────────────────────────
+Pre-Flight:  ✅ All checks passed
+             or ❌ [blocking item that must be resolved first]
+```
+
 
 ---
 
-## Mode Detection
+## 🏛️ Tribunal Integration 
 
-The AI should automatically detect the appropriate mode based on:
+**Slash command: Contextually applied based on user intent**
+**Active reviewers: `logic-reviewer` (monitors for mode adherence)**
 
-| Trigger | Mode |
-|---------|------|
-| "what if", "ideas", "options" | BRAINSTORM |
-| "build", "create", "add" | IMPLEMENT |
-| "not working", "error", "bug" | DEBUG |
-| "review", "check", "audit" | REVIEW |
-| "explain", "how does", "learn" | TEACH |
-| "deploy", "release", "production" | SHIP |
+### ✅ Pre-Flight Self-Audit
 
----
+Review these questions before sending any response to ensure you are in the correct mode:
+```
+✅ Have I explicitly announced which mode I am operating in?
+✅ If in DISCOVER or TEACH, have I successfully suppressed the urge to write implementation code?
+✅ If in DEBUG, am I proving a hypothesis or just guessing a fix?
+✅ If in REVIEW, am I commenting on the existing code rather than silently rewriting it?
+```
 
-## Multi-Agent Collaboration Patterns (2025)
 
-Modern architectures optimized for agent-to-agent collaboration:
+---
 
-### 1. 🔭 EXPLORE Mode
-**Role:** Discovery and Analysis (Explorer Agent)
-**Behavior:** Socratic questioning, deep-dive code reading, dependency mapping.
-**Output:** `discovery-report.json`, architectural visualization.
+## 🤖 LLM-Specific Traps
 
-### 2. 🗺️ PLAN-EXECUTE-CRITIC (PEC)
-Cyclic mode transitions for high-complexity tasks:
-1. **Planner:** Decomposes the task into atomic steps (`task.md`).
-2. **Executor:** Performs the actual coding (`IMPLEMENT`).
-3. **Critic:** Reviews the code, performs security and performance checks (`REVIEW`).
+AI coding assistants often fall into specific bad habits when dealing with this domain. These are strictly forbidden:
 
-### 3. 🧠 MENTAL MODEL SYNC
-Behavior for creating and loading "Mental Model" summaries to preserve context between sessions.
+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.
 
 ---
 
-## Combining Modes
+## 🏛️ Tribunal Integration (Anti-Hallucination)
 
----
+**Slash command: `/review` or `/tribunal-full`**
+**Active reviewers: `logic-reviewer` · `security-auditor`**
+
+### ❌ Forbidden AI Tropes
 
-## Manual Mode Switching
+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.
 
-Users can explicitly request a mode:
+### ✅ Pre-Flight Self-Audit
 
+Review these questions before confirming output:
 ```
-/brainstorm new feature ideas
-/implement the user profile page
-/debug why login fails
-/review this pull request
+✅ 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.