tribunal-kit 2.4.6 → 3.0.0

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

@@ -1,210 +1,104 @@
----
-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, 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 & Discovery Protocol
-
-> The most expensive part of building software is building the wrong thing.
-> Ask the questions that prevent that.
-
----
-
-## When This Skill Is Required
-
-Activate before generating any implementation plan when:
-
-- 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
-
----
-
-## The Socratic Method Applied to Software
-
-The goal is not to interrogate. It is to surface hidden assumptions before they become hard-coded decisions.
-
-### Discovery Questions by Layer
-
-**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?
-
-**Users (Who is this for?)**
-- Who are the actual end users?
-- What is their technical level?
-- Are there multiple user types with different needs?
-
-**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?
-
-**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?
-
-**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?
-
-**Constraints (What limits the design?)**
-- Existing tech stack?
-- Performance requirements? (users, requests/sec, data volume)
-- Deadline?
-- Budget for paid services?
-
----
-
-## Question Protocol
-
-For complex requests: ask **minimum 3 strategic questions** before proposing anything.
-
-For simple but vague requests: ask **1 focused question** on the most blocking unknown.
-
-**Format:**
-```
-Before I propose a solution, a few questions:
-
-1. [Most critical unknown]
-2. [Second most important]
-3. [Clarifies scope or constraints]
-
-[Optional: brief note on why these matter]
-```
-
-**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
-
----
-
-## Anti-Patterns in Discovery
-
-**What to avoid:**
-
-| 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?" |
-
----
-
-## Reporting During Complex Work
-
-When working on multi-step tasks, report progress proactively.
-
-**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 During Implementation
-
-When something fails or an assumption is proven wrong mid-task:
-
-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
-
-```
-❌ Found an issue:
-   Expected: users table has an `email` column
-   Found: email is in a separate `user_contacts` table
-
-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
-
-Which should I proceed with?
-```
-
----
-
-## File Index
-
-| File | Covers | Load When |
-|---|---|---|
-| `dynamic-questioning.md` | Advanced question frameworks by domain | Discovery for complex systems |
-
----
-
-## Output Format
-
-When this skill produces a recommendation or design decision, structure your output as:
-
-```
-━━━ 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]
-```
-
-
-
----
-
-## 🤖 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.
+---
+name: brainstorming
+description: Socratic methodology, ideation, and architectural exploration mastery. Generating extensive feature options, analyzing trade-offs, questioning assumptions, mind-mapping components, and delaying execution. Use when evaluating new features, defining project goals, or guiding users through ambiguous design spaces.
+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
+---
+
+# Brainstorming — Socratic Exploration Mastery
+
+> Writing code is expensive. Deleting code is dangerous.
+> Thinking is cheap. Explore the permutation space rigorously before committing to an architecture.
+
+---
+
+## 1. The Socratic Protocol (Mandatory Delay)
+
+When a user provides a vague or complex prompt like *"I want to build a marketplace app,"* DO NOT start generating boilerplate code or database schemas. 
+
+**You must act as a Socratic filter.**
+1. Acknowledge the ambition of the goal.
+2. Provide 3-5 distinct architectural/functional pathways the user could take.
+3. Pause execution. Demand the user makes definitive decisions regarding the permutations before proceeding.
+
+### Example Socratic Prompting:
+Instead of: *"Here is the React code for your marketplace,"*
+Output: *"Before we write the code, we must lock down the payment flow. Do you want to: A) Handle escrow directly (High liability, complex payout logic), B) Use Stripe Connect (Easy routing, strict KYC requirements), or C) Operate free-listing only (Zero liability, requires external monetization)?"*
+
+---
+
+## 2. Multi-Dimensional Tradeoff Analysis
+
+Every design choice has drawbacks. The brainstorming agent must illuminate the implicit consequences of the user's requests.
+
+When comparing options, strict tabular formatting clarifies friction:
+
+| Approach | Speed to Market | Operational Cost | Latency / UX | Maintenance Burden |
+|:---|:---|:---|:---|:---|
+| **Serverless Functions** | Very high | Low initially (pay-per-use) | Cold starts (500ms delay) | Complex local testing |
+| **Monolithic Node VPS** | Moderate | Flat ($10/mo fixed) | Extremely fast (0ms start) | Requires manual OS patching |
+| **Edge Compute (V8)** | Low | Moderate | Global low-latency | Strict 1MB limits / V8 restrictions |
+
+*Result:* The user chooses the approach mapped to their business reality, not a generic AI default.
+
+---
+
+## 3. Lateral Expansion (The "What If?" Matrix)
+
+Users frequently suffer from tunnel-vision regarding their requested feature. The Brainstormer introduces lateral features the user hasn't considered yet to solidify the schema boundaries.
+
+If user asks for: **"A habit tracking calendar."**
+*Expand laterally:*
+- "What if a user crosses timezones frequently? Do streaks break?"
+- "What if they track binary habits (Read: Yes/No) versus quantitative habits (Drink 6 Liters of water)?"
+- "What if they require offline capability while on airplanes?"
+
+---
+
+## 4. Distilling Decisions into Assertions
+
+Brainstorming is useless if it does not produce an actionable blueprint.
+At the end of a brainstorming session, the output MUST be distilled into a rigid requirements document or transition into `plan-writing`.
+
+```markdown
+# Final Brainstorming Assertions
+1. **Architecture:** Next.js SSR Monolith
+2. **Database:** Postgres via Prisma (Required for complex relational queries)
+3. **Payment:** Stripe Connect (Subverted liability)
+4. **Auth:** NextAuth (Google Provider only for MVP)
+```
+
+---
+
+## 🤖 LLM-Specific Traps (Brainstorming)
+
+1. **Premature Execution:** The AI receives a vague feature idea and immediately dumps 600 lines of unproven boilerplate code, creating enormous context waste and confusing the user.
+2. **Yes-Man Syndrome:** Agreeing with a user's terrible, insecure, or archaic technical proposal blindly. If a user asks to "store passwords in base64," the Brainstormer MUST aggressively intervene and correct the user.
+3. **Analysis Paralysis:** Asking the user 25 minute unanswerable questions at once (e.g., "What will your AWS scaling limits be?"). Keep Socratic questions limited to 3-5 high-impact, immediate blockers.
+4. **Binary Fallacy:** Trapping the user into "You must either use Python or JavaScript" scenarios, neglecting hybrid architectures or novel edge deployments.
+5. **Ignoring The "Why":** Solving for the requested feature execution without asking *why* the user needs it. (e.g., User asks to build a complex PDF parser to extract totals. Ask if the vendor has a CSV/JSON API first).
+6. **Framework Zealotry:** Defaulting exclusively to React/Next.js for simple static blogs instead of proposing Astro or Eleventy tradeoffs. Evaluate based on the precise domain.
+7. **Scale Hallucination:** Architecting a system designed for 10 million DAU utilizing Kubernetes microservices when the user is explicitly building a local internal tool for 5 warehouse employees.
+8. **Forgetting State Continuity:** Conducting a brilliant 10-message brainstorm session, and then beginning the implementation phase entirely forgetting the 3 tradeoff decisions the user made in message #2.
+9. **Monolithic Summaries:** Providing a dense, impenetrable wall of text. Use bullet points, bolded keywords, and markdown tables to highlight divergent permutations.
+10. **The Echo Chamber:** Repeating the user's prompt back to them in a slightly modified structure without adding any lateral expansion, novelty, or tradeoff friction.
+
+---
+
+## 🏛️ Tribunal Integration
+
+### ✅ Pre-Flight Self-Audit
+```
+✅ Have I explicitly delayed code generation until unambiguous requirements are approved?
+✅ Did I outline 3-5 structural pathways with explicit, balanced tradeoff comparisons?
+✅ Were lateral considerations (edge cases, scale caps, timezones) introduced rigorously?
+✅ Have Socratic questions been capped at ~3 digestible choices to avoid analysis paralysis?
+✅ Did I aggressively correct any fundamentally insecure or anti-pattern directives from the user?
+✅ Are architectural suggestions appropriately matched to the user's actual predicted traffic scale?
+✅ Did I use structured tables to map divergent consequences efficiently?
+✅ Are the user's business objectives deeply represented in the proposed technical choices?
+✅ Is the final output distilled into rigorous functional assertions transitioning to execution?
+✅ Has conversational "Yes-man" echo-looping been strictly expelled from the dialogue?
+```

package/.agent/skills/building-native-ui/SKILL.md

@@ -1,75 +1,174 @@
 ---
 name: building-native-ui
-description: Cross-platform App UI expert specialized in React Native and Expo. Focuses on safe areas, keyboard handling, layout performance, and platform-specific heuristics.
+description: Cross-platform Native UI mastery (React Native / Expo). Building seamless, 60fps mobile interfaces, handling safe areas, navigation architectures (Expo Router), native modules, gestures/animations (Reanimated), and platform-specific styling. Use when building React Native or Expo mobile apps.
 allowed-tools: Read, Write, Edit, Glob, Grep
-version: 1.0.0
-last-updated: 2026-03-30
-applies-to-model: claude-3-7-sonnet, gemini-2.5-pro
+version: 2.0.0
+last-updated: 2026-04-02
+applies-to-model: gemini-2.5-pro, claude-3-7-sonnet
 ---
 
-# Building Native UI (React Native / Expo)
-
-You are an expert Mobile Frontend Engineer. You understand the profound differences between building a website and building a fluid, responsive native application for iOS and Android.
-
-## Core Directives
-
-1. **Environmental Safety First:**
-   - Always wrap root navigational components or edge-touching screens in `SafeAreaView` (from `react-native-safe-area-context`).
-   - Any screen containing text inputs MUST utilize `KeyboardAvoidingView` or `KeyboardAwareScrollView` to prevent the software keyboard from occluding input fields.
-
-2. **Platform Tropes:**
-   - Rely heavily on `Platform.OS` or `Platform.select()` to gracefully adapt UI components. 
-   - Shadows on iOS (`shadowOpacity`, `shadowRadius`) do not work the same stringently on Android (`elevation`). Provide robust fallback implementations to both.
-
-3. **Performance Boundaries:**
-   - Never use deeply generic or unbound nested `.map()` loops for massive UI layouts. Always use `FlatList` or `FlashList` for heavy lists to optimize memory via view recycling.
-   - Avoid massive functional component re-renders. Use standard `useMemo` strictly for expensive list data formatting.
-
-4. **Animations & Gestures:**
-   - Use `react-native-reanimated` instead of standard `Animated` for anything complex. Run animations completely natively on the UI thread without dropping JS bridge frames.
-   - Pair interactive swipes/drags directly with `react-native-gesture-handler`. 
-
-## Execution
-When outputting React Native application markup, always default to importing high-performance primitives (`Pressable` over `TouchableOpacity`, `FlashList` over `ScrollView(map)`).
-
-
----
-
-## 🤖 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.
+# Building Native UI — React Native & Expo Mastery
+
+> A mobile app isn't a website confined to a small screen.
+> 60 FPS is not a goal; it is a rigid requirement. The JS thread is a fragile bottleneck.
+
+---
+
+## 1. The Expo Router Architecture
+
+File-based routing replaces legacy imperative React Navigation boilerplates.
+
+```typescript
+// Directory structure dictates routes
+// app/
+// ├── _layout.tsx      (Global wrap, e.g. Stack or Tabs)
+// ├── index.tsx        (Matches '/')
+// ├── (auth)/          (Route group, invisible in URL)
+// │   └── login.tsx    (Matches '/login')
+// └── user/
+//     └── [id].tsx     (Dynamic route, matches '/user/123')
+
+// Link navigation (Strongly typed in Expo Router v3+)
+import { Link, router } from 'expo-router';
+
+export default function Home() {
+  return (
+    <View>
+      {/* Declarative */}
+      <Link href="/user/123" asChild>
+        <Pressable><Text>Go to Profile</Text></Pressable>
+      </Link>
+      
+      {/* Imperative */}
+      <Button onPress={() => router.push('/(auth)/login')} title="Login" />
+    </View>
+  );
+}
+```
+
+---
+
+## 2. Platform Nuances & Safe Areas
+
+Mobile devices have notches, home indicators, and varied status bars.
+
+```typescript
+// ❌ BAD: Ignoring notches
+export const Header = () => <View style={{ paddingTop: 20 }} />
+
+// ✅ GOOD: react-native-safe-area-context
+import { useSafeAreaInsets } from 'react-native-safe-area-context';
+
+export const Header = () => {
+  const insets = useSafeAreaInsets();
+  return (
+    <View style={{ paddingTop: insets.top, paddingBottom: insets.bottom }}>
+      <Text>Header Content</Text>
+    </View>
+  );
+}
+
+// ✅ Platform-specific logic
+import { Platform, StyleSheet } from 'react-native';
+
+const styles = StyleSheet.create({
+  shadow: {
+    ...Platform.select({
+      ios: { shadowColor: '#000', shadowOffset: { width: 0, height: 2 }, shadowOpacity: 0.2 },
+      android: { elevation: 4 }, // Android requires elevation for shadows
+    }),
+  }
+});
+```
+
+---
+
+## 3. High-Performance Animations (Reanimated)
+
+Never animate over the React Native bridge. Keep animations strictly on the native UI thread using `react-native-reanimated`.
+
+```typescript
+// ❌ BAD: Animated.Value across the bridge, or setState driven animations
+// setState -> JS Thread calculate -> Bridge JSON -> Native UI (Drops frames!)
+
+// ✅ GOOD: Reanimated UI thread execution
+import Animated, { useSharedValue, useAnimatedStyle, withSpring } from 'react-native-reanimated';
+
+export function BouncyBox() {
+  const offset = useSharedValue(0); // Lives natively
+
+  const animatedStyles = useAnimatedStyle(() => {
+    return {
+      transform: [{ translateY: offset.value }], // Syncs natively
+    };
+  });
+
+  return (
+    <>
+      <Animated.View style={[styles.box, animatedStyles]} />
+      <Button onPress={() => (offset.value = withSpring(Math.random() * 255))} title="Bounce" />
+    </>
+  );
+}
+```
+
+---
+
+## 4. List Performance
+
+FlatList rendering is the #1 cause of React Native app crashes due to OOM (Out of Memory).
+
+```typescript
+import { FlashList } from "@shopify/flash-list";
+
+// ❌ BAD: Standard ScrollView for massive lists
+// Maps every item instantly. Crashes on large data sets.
+
+// ❌ MEDIOCRE: FlatList
+// Blank spaces when scrolling fast due to JS thread bridge bottlenecks.
+
+// ✅ BEST: FlashList (Shopify)
+// Recycles views instantly like native UICollectionView / RecyclerView.
+export function FastList({ data }) {
+  return (
+    <FlashList
+      data={data}
+      renderItem={({ item }) => <Text>{item.title}</Text>}
+      estimatedItemSize={50} // CRUCIAL for performance
+    />
+  );
+}
+```
+
+---
+
+## 🤖 LLM-Specific Traps (React Native UI)
+
+1. **HTML Elements:** AI frequently hallucinates `<div>`, `<span>`, and `<p>` tags inside React Native code. React Native STRICTLY requires `<View>`, `<Text>`, and `<Pressable>`.
+2. **CSS properties:** AI writes `box-shadow` or `border-radius: 10px`. React Native styling uses `shadowColor / elevation` and numeric `borderRadius: 10`.
+3. **Bridge Animations:** AI suggests legacy `Animated.timing` or `setState` loops for animations. Demand `react-native-reanimated` shared values on the UI thread.
+4. **Ignoring Safe Areas:** Bounding UI boxes against the absolute physical screen edge, resulting in text hidden behind iPhone dynamic islands or Android navigation bars.
+5. **ScrollView Data Dumps:** Rendering a `.map()` inside a `<ScrollView>` for 1000 items, crashing the mobile memory constraint.
+6. **`onClick` instead of `onPress`:** Using standard web synthetic events. React Native buttons use `onPress`.
+7. **Absolute SVGs:** Attempting to render standard `<svg>` tags. Requires `react-native-svg` with precise React-friendly props.
+8. **Keyboard Avoidance:** Failing to wrap inputs in `<KeyboardAvoidingView>`, meaning the digital keyboard pops up and permanently obscures the text input.
+9. **Platform Blindness:** Applying `shadowOpacity` expecting it to work on Android (it doesn't, requires `elevation`).
+10. **Legacy Navigation:** Generating sprawling `react-navigation` stack files instead of utilizing modern Expo Router file-based topologies.
+
+---
+
+## 🏛️ Tribunal Integration
+
+### ✅ Pre-Flight Self-Audit
+```
+✅ Did I exclusively use native primitives (<View>, <Text>, <Pressable>) and NO HTML tags?
+✅ Is `react-native-reanimated` handling all physics and animations on the UI thread?
+✅ Are large lists utilizing `<FlashList>` with a declared `estimatedItemSize`?
+✅ Is UI guarded from notches using `useSafeAreaInsets`?
+✅ Are styles written strictly via `StyleSheet.create` with numeric values, not string CSS?
+✅ Are interactive touch points using `onPress`, not `onClick`?
+✅ Is the Keyboard explicitly handled via `KeyboardAvoidingView` or `KeyboardAwareScrollView`?
+✅ Is routing leveraging modern Expo Router file systems?
+✅ Are shadows handled specifically for iOS (shadowProps) and Android (elevation)?
+✅ Have I avoided sending massive state updates back and forth across the JS bridge?
+```