tribunal-kit 1.0.0 → 2.4.2

package/.agent/skills/brainstorming/SKILL.md

@@ -1,163 +1,210 @@
 ---
 name: brainstorming
 description: Socratic questioning protocol + user communication. MANDATORY for complex requests, new features, or unclear requirements. Includes progress reporting and error handling.
-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
 ---
 
-# Brainstorming & Communication Protocol
+# Brainstorming & Discovery Protocol
 
-> **MANDATORY:** Use for complex/vague requests, new features, updates.
+> The most expensive part of building software is building the wrong thing.
+> Ask the questions that prevent that.
 
 ---
 
-## 🛑 SOCRATIC GATE (ENFORCEMENT)
+## When This Skill Is Required
 
-### When to Trigger
+Activate before generating any implementation plan when:
 
-| Pattern | Action |
-|---------|--------|
-| "Build/Create/Make [thing]" without details | 🛑 ASK 3 questions |
-| Complex feature or architecture | 🛑 Clarify before implementing |
-| Update/change request | 🛑 Confirm scope |
-| Vague requirements | 🛑 Ask purpose, users, constraints |
+- A new feature or system is being created
+- The request is vague or uses words like "something like" or "maybe"
+- Multiple valid technical approaches exist and the right one depends on context
+- The user hasn't described their users, scale, or constraints
 
-### 🚫 MANDATORY: 3 Questions Before Implementation
+---
 
-1. **STOP** - Do NOT start coding
-2. **ASK** - Minimum 3 questions:
-   - 🎯 Purpose: What problem are you solving?
-   - 👥 Users: Who will use this?
-   - 📦 Scope: Must-have vs nice-to-have?
-3. **WAIT** - Get response before proceeding
+## The Socratic Method Applied to Software
 
----
+The goal is not to interrogate. It is to surface hidden assumptions before they become hard-coded decisions.
 
-## 🧠 Dynamic Question Generation
+### Discovery Questions by Layer
 
-**⛔ NEVER use static templates.** Read `dynamic-questioning.md` for principles.
+**Purpose (What problem does this solve?)**
+- What outcome does the user need — not what feature do they want?
+- What happens today without this?
+- What does success look like in 30 days?
 
-### Core Principles
+**Users (Who is this for?)**
+- Who are the actual end users?
+- What is their technical level?
+- Are there multiple user types with different needs?
 
-| Principle | Meaning |
-|-----------|---------|
-| **Questions Reveal Consequences** | Each question connects to an architectural decision |
-| **Context Before Content** | Understand greenfield/feature/refactor/debug context first |
-| **Minimum Viable Questions** | Each question must eliminate implementation paths |
-| **Generate Data, Not Assumptions** | Don't guess—ask with trade-offs |
+**Scope (What is and isn't included?)**
+- What is explicitly out of scope for this version?
+- What data already exists vs. what needs to be created?
+- Are there integrations with other systems?
 
-### Question Generation Process
+**Market & Psychology (Why will they use it?)**
+- Who are the current competitors or alternatives, and how are we different?
+- What is the launch strategy and monetization approach?
+- What emotional state is the user in when they need this product?
 
-```
-1. Parse request → Extract domain, features, scale indicators
-2. Identify decision points → Blocking vs. deferable
-3. Generate questions → Priority: P0 (blocking) > P1 (high-leverage) > P2 (nice-to-have)
-4. Format with trade-offs → What, Why, Options, Default
-```
+**Superpowers & Creative Constraints (Breaking the mold)**
+- If we had to solve this without writing any code, how would we do it?
+- What is the most unconventional, "fun", or high-leverage way to achieve this outcome?
+- Can we leverage existing external super-APIs (LLMs, edge networks, managed integrations) to bypass traditional development?
 
-### Question Format (MANDATORY)
+**Constraints (What limits the design?)**
+- Existing tech stack?
+- Performance requirements? (users, requests/sec, data volume)
+- Deadline?
+- Budget for paid services?
 
-```markdown
-### [PRIORITY] **[DECISION POINT]**
+---
+
+## Question Protocol
 
-**Question:** [Clear question]
+For complex requests: ask **minimum 3 strategic questions** before proposing anything.
 
-**Why This Matters:**
-- [Architectural consequence]
-- [Affects: cost/complexity/timeline/scale]
+For simple but vague requests: ask **1 focused question** on the most blocking unknown.
+
+**Format:**
+```
+Before I propose a solution, a few questions:
 
-**Options:**
-| Option | Pros | Cons | Best For |
-|--------|------|------|----------|
-| A | [+] | [-] | [Use case] |
+1. [Most critical unknown]
+2. [Second most important]
+3. [Clarifies scope or constraints]
 
-**If Not Specified:** [Default + rationale]
+[Optional: brief note on why these matter]
 ```
 
-**For detailed domain-specific question banks and algorithms**, see: `dynamic-questioning.md`
+**Rules:**
+- Ask about one topic per question — not compound questions (`and`/`or` in a question = split it)
+- Numbered list, not a wall of text
+- Never more than 5 questions at once
+- Always inject at least one highly creative, out-of-the-box alternative approach ("Superpower Option") when proposing paths.
+- If answers create new unknowns, ask a follow-up round
 
 ---
 
-## Progress Reporting (PRINCIPLE-BASED)
+## Anti-Patterns in Discovery
 
-**PRINCIPLE:** Transparency builds trust. Status must be visible and actionable.
+**What to avoid:**
 
-### Status Board Format
+| Pattern | Why It's Harmful |
+|---|---|
+| Assuming the tech stack | Leads to architecture that fits you, not the project |
+| Solving the stated feature, not the problem | User asks for X but needs Y — you build X |
+| Treating "I want a dashboard" as a spec | Dashboards have hundreds of valid forms |
+| Jumping to implementation to seem helpful | Wastes both parties' time if direction is wrong |
+| Asking leading questions | "Should we use Next.js?" vs "What matters most for deployment?" |
 
-| Agent | Status | Current Task | Progress |
-|-------|--------|--------------|----------|
-| [Agent Name] | ✅🔄⏳❌⚠️ | [Task description] | [% or count] |
+---
+
+## Reporting During Complex Work
 
-### Status Icons
+When working on multi-step tasks, report progress proactively.
 
-| Icon | Meaning | Usage |
-|------|---------|-------|
-| ✅ | Completed | Task finished successfully |
-| 🔄 | Running | Currently executing |
-| ⏳ | Waiting | Blocked, waiting for dependency |
-| ❌ | Error | Failed, needs attention |
-| ⚠️ | Warning | Potential issue, not blocking |
+**Status update format:**
+```
+✅ [Completed step]
+🔄 [Current step — what you're doing right now]
+⏳ [Next step]
+```
+
+Report at natural breakpoints — not after every file edit.
 
 ---
 
-## Error Handling (PRINCIPLE-BASED)
+## Error Handling During Implementation
 
-**PRINCIPLE:** Errors are opportunities for clear communication.
+When something fails or an assumption is proven wrong mid-task:
 
-### Error Response Pattern
+1. Stop immediately — don't continue building on a broken assumption
+2. State what was expected vs. what was found
+3. Propose 2–3 corrected approaches with trade-offs
+4. Ask which direction to proceed
 
 ```
-1. Acknowledge the error
-2. Explain what happened (user-friendly)
-3. Offer specific solutions with trade-offs
-4. Ask user to choose or provide alternative
-```
+❌ Found an issue:
+   Expected: users table has an `email` column
+   Found: email is in a separate `user_contacts` table
 
-### Error Categories
+Options:
+   A) Join through user_contacts (correct but slower queries)
+   B) Denormalize email onto users table (faster, requires migration)
+   C) Ask what the schema decision was intended to be
 
-| Category | Response Strategy |
-|----------|-------------------|
-| **Port Conflict** | Offer alternative port or close existing |
-| **Dependency Missing** | Auto-install or ask permission |
-| **Build Failure** | Show specific error + suggested fix |
-| **Unclear Error** | Ask for specifics: screenshot, console output |
+Which should I proceed with?
+```
 
 ---
 
-## Completion Message (PRINCIPLE-BASED)
+## File Index
 
-**PRINCIPLE:** Celebrate success, guide next steps.
+| File | Covers | Load When |
+|---|---|---|
+| `dynamic-questioning.md` | Advanced question frameworks by domain | Discovery for complex systems |
 
-### Completion Structure
+---
+
+## Output Format
+
+When this skill produces a recommendation or design decision, structure your output as:
 
 ```
-1. Success confirmation (celebrate briefly)
-2. Summary of what was done (concrete)
-3. How to verify/test (actionable)
-4. Next steps suggestion (proactive)
+━━━ Brainstorming 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]
 ```
 
+
+
 ---
 
-## Communication Principles
+## 🤖 LLM-Specific Traps
+
+AI coding assistants often fall into specific bad habits when dealing with this domain. These are strictly forbidden:
 
-| Principle | Implementation |
-|-----------|----------------|
-| **Concise** | No unnecessary details, get to point |
-| **Visual** | Use emojis (✅🔄⏳❌) for quick scanning |
-| **Specific** | "~2 minutes" not "wait a bit" |
-| **Alternatives** | Offer multiple paths when stuck |
-| **Proactive** | Suggest next step after completion |
+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.
 
 ---
 
-## Anti-Patterns (AVOID)
+## 🏛️ Tribunal Integration (Anti-Hallucination)
 
-| Anti-Pattern | Why |
-|--------------|-----|
-| Jumping to solutions before understanding | Wastes time on wrong problem |
-| Assuming requirements without asking | Creates wrong output |
-| Over-engineering first version | Delays value delivery |
-| Ignoring constraints | Creates unusable solutions |
-| "I think" phrases | Uncertainty → Ask instead |
+**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/brainstorming/dynamic-questioning.md

@@ -88,6 +88,7 @@ INPUT: User request + Context (greenfield/feature/refactor/debug)
     ├── What: Clear question
     ├── Why: Impact on implementation
     ├── Options: Trade-offs (not just A vs B)
+    ├── Fun/Superpower Option: Inject at least one highly creative, unconventional approach
     └── Default: What happens if user doesn't answer
 ```
 
@@ -131,6 +132,15 @@ INPUT: User request + Context (greenfield/feature/refactor/debug)
 | **Media Handling?** | Upload endpoints, storage, optimization | +Features, -Development time |
 | **Multi-language?** | i18n tables, translation UI, fallback logic | +Reach, -Complexity |
 
+### Business & Product Strategy
+
+| Question | Why It Matters | Trade-offs |
+|----------|----------------|------------|
+| **Monetization Approach?** | Freemium vs. Paywall vs. Ads affects user flow | +Revenue, -User Acquisition |
+| **Onboarding CRO?** | Wizard vs. self-serve dictates state management | +Activation, -Dev Time |
+| **Competitor Differentiator?** | Must highlight this UI feature above all else | +Standout, -Standardization |
+| **Marketing Psychology?** | FOMO (urgency) vs. Trust (social proof) layout | +Conversion, -Aesthetics |
+
 ---
 
 ## 📐 Dynamic Question Template