tribunal-kit 3.0.0 → 3.1.0

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

@@ -9,9 +9,6 @@ applies-to-model: gemini-2.5-pro, claude-3-7-sonnet
 
 # Behavioral Modes
 
-> The same task handled carelessly vs. carefully looks identical until it fails.
-> Mode selection is about matching rigor to risk.
-
 ---
 
 ## Overview
@@ -130,15 +127,15 @@ This skill defines how to behave in each context — not just what to produce.
 
 ## Mode Selection Rules
 
-| Signal in Request | Activate |
+|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 |
+|"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|
 
 ---
 
@@ -173,62 +170,4 @@ Pre-Flight:  ✅ All checks passed
              or ❌ [blocking item that must be resolved first]
 ```
 
-
----
-
-## 🏛️ Tribunal Integration 
-
-**Slash command: Contextually applied based on user intent**
-**Active reviewers: `logic-reviewer` (monitors for mode adherence)**
-
-### ✅ 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?
-```
-
-
----
-
-## 🤖 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.

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

@@ -1,104 +1,428 @@
----
-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?
-```
+---
+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: 3.1.0
+last-updated: 2026-04-06
+applies-to-model: gemini-2.5-pro, claude-3-7-sonnet
+---
+
+# Brainstorming — Socratic Exploration Mastery
+
+---
+
+## 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)
+```
+
+---
+
+## Dynamic Question Generation
+
+**PRINCIPLE:** Questions are not about gathering data—they are about **revealing architectural consequences**.
+
+Every question must connect to a concrete implementation decision that affects cost, complexity, or timeline.
+
+---
+
+### 🧠 Core Principles
+
+#### 1. Questions Reveal Consequences
+
+A good question is not "What color do you want?" but:
+
+```markdown
+❌ BAD: "What authentication method?"
+✅ GOOD: "Should users sign up with email/password or social login?
+
+   Impact:
+   - Email/Pass → Need password reset, hashing, 2FA infrastructure
+   - Social → OAuth providers, user profile mapping, less control
+
+   Trade-off: Security vs. Development time vs. User friction"
+```
+
+#### 2. Context Before Content
+
+First understand **where** this request fits:
+
+|Context|Question Focus|
+|---------|----------------|
+|**Greenfield** (new project)|Foundation decisions: stack, hosting, scale|
+|**Feature Addition**|Integration points, existing patterns, breaking changes|
+|**Refactor**|Why refactor? Performance? Maintainability? What's broken?|
+
+#### 3. Minimum Viable Questions
+
+**PRINCIPLE:** Each question must eliminate a fork in the implementation road.
+
+```
+Before Question:
+├── Path A: Do X (5 min)
+├── Path B: Do Y (15 min)
+└── Path C: Do Z (1 hour)
+
+After Question:
+└── Path Confirmed: Do X (5 min)
+```
+
+If a question doesn't reduce implementation paths → **DELETE IT**.
+
+#### 4. Questions Generate Data, Not Assumptions
+
+```markdown
+❌ ASSUMPTION: "User probably wants Stripe for payments"
+✅ QUESTION: "Which payment provider fits your needs?
+
+   Stripe → Best documentation, 2.9% + $0.30, US-centric
+   LemonSqueezy → Merchant of Record, 5% + $0.50, global taxes
+   Paddle → Complex pricing, handles EU VAT, enterprise focus"
+```
+
+---
+
+### 📋 Question Generation Algorithm
+
+```
+INPUT: User request + Context (greenfield/feature/refactor/debug)
+│
+├── STEP 1: Parse Request
+│   ├── Extract domain (ecommerce, auth, realtime, cms, etc.)
+│   ├── Extract features (explicit and implied)
+│   └── Extract scale indicators (users, data volume, frequency)
+│
+├── STEP 2: Identify Decision Points
+│   ├── What MUST be decided before coding? (blocking)
+│   ├── What COULD be decided later? (deferable)
+│   └── What has ARCHITECTURAL impact? (high-leverage)
+│
+├── STEP 3: Generate Questions (Priority Order)
+│   ├── P0: Blocking decisions (cannot proceed without answer)
+│   ├── P1: High-leverage (affects >30% of implementation)
+│   ├── P2: Medium-leverage (affects specific features)
+│   └── P3: Nice-to-have (edge cases, optimization)
+│
+└── STEP 4: Format Each Question
+    ├── 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
+```
+
+---
+
+### 🎯 Domain-Specific Question Banks
+
+#### E-Commerce
+
+|Question|Why It Matters|Trade-offs|
+|----------|----------------|------------|
+|**Single or Multi-vendor?**|Multi-vendor → Commission logic, vendor dashboards, split payments|+Revenue, -Complexity|
+|**Inventory Tracking?**|Needs stock tables, reservation logic, low-stock alerts|+Accuracy, -Development time|
+|**Digital or Physical Products?**|Digital → Download links, no shipping|Physical → Shipping APIs, tracking|
+|**Subscription or One-time?**|Subscription → Recurring billing, dunning, proration|+Revenue, -Complexity|
+
+#### Authentication
+
+|Question|Why It Matters|Trade-offs|
+|----------|----------------|------------|
+|**Social Login Needed?**|OAuth providers vs. password reset infrastructure|+UX, -Control|
+|**Role-Based Permissions?**|RBAC tables, policy enforcement, admin UI|+Security, -Development time|
+|**2FA Required?**|TOTP/SMI infrastructure, backup codes, recovery flow|+Security, -UX friction|
+|**Email Verification?**|Verification tokens, email service, resend logic|+Security, -Sign-up friction|
+
+#### Real-time
+
+|Question|Why It Matters|Trade-offs|
+|----------|----------------|------------|
+|**WebSocket or Polling?**|WS → Server scaling, connection management|Polling → Simpler, higher latency|
+|**Expected Concurrent Users?**|<100 → Single server, >1000 → Redis pub/sub, >10k → specialized infra|+Scale, -Complexity|
+|**Message Persistence?**|History tables, storage costs, pagination|+UX, -Storage|
+|**Ephemeral or Durable?**|Ephemeral → In-memory, Durable → Database write before emit|+Reliability, -Latency|
+
+#### Content/CMS
+
+|Question|Why It Matters|Trade-offs|
+|----------|----------------|------------|
+|**Rich Text or Markdown?**|Rich Text → Sanitization, XSS risks|Markdown → Simple, no WYSIWYG|
+|**Draft/Publish Workflow?**|Status field, scheduled jobs, versioning|+Control, -Complexity|
+|**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
+
+```markdown
+
+### 🔴 CRITICAL (Blocking Decisions)
+
+#### 1. **[DECISION POINT]**
+
+**Question:** [Clear, specific question]
+
+**Why This Matters:**
+- [Explain architectural consequence]
+- [Affects: cost / complexity / timeline / scale]
+
+**Options:**
+|Option|Pros|Cons|Best For|
+|--------|------|------|----------|
+|A|[Advantage]|[Disadvantage]|[Use case]|
+|B|[Advantage]|[Disadvantage]|[Use case]|
+
+**If Not Specified:** [Default choice + rationale]
+
+---
+
+### 🟡 HIGH-LEVERAGE (Affects Implementation)
+
+#### 2. **[DECISION POINT]**
+[Same format]
+
+---
+
+### 🟢 NICE-TO-HAVE (Edge Cases)
+
+#### 3. **[DECISION POINT]**
+[Same format]
+```
+
+---
+
+### 🔄 Iterative Questioning
+
+#### First Pass (3-5 Questions)
+Focus on **blocking decisions**. Don't proceed without answers.
+
+#### Second Pass (After Initial Implementation)
+As patterns emerge, ask:
+- "This feature implies [X]. Should we handle [edge case] now or defer?"
+- "We're using [Pattern A]. Should [Feature B] follow the same pattern?"
+
+#### Third Pass (Optimization)
+When functionality works:
+- "Performance bottleneck at [X]. Optimize now or acceptable for now?"
+- "Refactor [Y] for maintainability or ship as-is?"
+
+---
+
+### 🎭 Example: Full Question Generation
+
+```
+USER REQUEST: "Build an Instagram clone"
+
+STEP 1: Parse
+├── Domain: Social Media
+├── Features: Photo sharing, engagement (likes/comments), user profiles
+├── Implied: Feed, following, authentication
+└── Scale: Potentially high (social apps go viral)
+
+STEP 2: Decision Points
+├── Blocking: Storage strategy, authentication method, feed type
+├── High-leverage: Real-time notifications, data model complexity
+└── Deferable: Analytics, advanced search, reels/video
+
+STEP 3: Generate Questions (Priority)
+
+P0 (Blocking):
+1. Storage Strategy → Affects architecture, cost, speed
+2. Feed Algorithm → Affects database queries, complexity
+3. Auth Method → Affects dev time, UX, security
+
+P1 (High-leverage):
+4. Real-time Notifications → WebSocket vs polling
+5. Media Processing → Client-side vs server-side optimization
+
+P2 (Deferable):
+6. Story/Reels → Major feature creep, defer to v2
+7. DM/Chat → Separate subsystem, defer to v2
+
+STEP 4: Format Output
+```
+
+---
+
+### 📊 Generated Output (Example)
+
+```
+
+### 🔴 CRITICAL DECISIONS (Cannot Proceed Without Answers)
+
+#### 1. **Photo Storage Strategy**
+
+**Question:** Where will user photos be stored and served?
+
+**Why This Matters:**
+- Affects: Monthly hosting costs, page load speed, CDN complexity
+- High-volume social apps: 1000 users × 10 photos × 2MB = 20GB storage
+
+**Options:**
+|Option|Cost|Speed|Complexity|Best For|
+|--------|------|-------|------------|----------|
+|**Cloudinary**|$89/mo (25GB)|Fast (CDN)|Low|MVP, rapid launch|
+|**AWS S3 + CloudFront**|$0.023/GB|Fast (CDN)|Medium|Production, cost-optimized|
+|**Supabase Storage**|Free tier 1GB|Medium|Low|Small scale, simple|
+|**Local Storage**|Server cost|Slow|Low|Development only|
+
+**If Not Specified:** Cloudinary (balanced for MVP)
+
+---
+
+#### 2. **Feed Algorithm Choice**
+
+**Question:** How should the main feed work?
+
+**Why This Matters:**
+- Affects: Database query complexity, caching strategy, development time
+- Algorithmic feeds require ML infrastructure, ranking signals
+
+**Options:**
+|Option|Complexity|Database Impact|Best For|
+|--------|------------|-----------------|----------|
+|**Chronological**|Low|Simple query|Early stage, transparency|
+|**Follow-Only**|Medium|JOIN with pagination|Most social apps|
+|**Algorithmic**|High|Pre-computed feed tables|Instagram competitor|
+
+**If Not Specified:** Follow-Only (balanced for social app)
+
+---
+
+#### 3. **Authentication Approach**
+
+**Question:** How do users sign up and login?
+
+**Why This Matters:**
+- Affects: Development time (2-5 hours), security posture, UX friction
+
+**Options:**
+|Option|Dev Time|Security|UX|Best For|
+|--------|----------|----------|-----|----------|
+|**Email/Password**|4-5 hrs|High (if 2FA)|Medium|Full control needed|
+|**Social Only**|1-2 hrs|Provider-dependent|Smooth|B2C, rapid launch|
+|**Magic Link**|2-3 hrs|Medium|Very smooth|Security-focused|
+|**Clerk/Auth0**|1 hr|High|Smooth|Fastest to market|
+
+**If Not Specified:** Clerk (fastest for MVP)
+
+---
+
+### 🟡 HIGH-LEVERAGE (Affects Architecture)
+
+#### 4. **Real-time Notifications**
+
+**Question:** Do users need instant notifications for likes/comments?
+
+**Why This Matters:**
+- WebSocket adds infrastructure complexity (Redis pub/sub for scaling)
+- Polling is simpler but higher latency
+
+**Options:**
+|Option|Complexity|Scale Cost|Best For|
+|--------|------------|------------|----------|
+|**WebSocket + Redis**|High|$10+/mo|>1000 concurrent users|
+|**Polling (30s)**|Low|DB queries|<1000 users|
+|**No Real-time**|None|None|MVP, validate first|
+
+**If Not Specified:** Polling for MVP (defer WebSocket until validated)
+
+---
+
+### 🟢 NICE-TO-HAVE (Defer to v2)
+
+#### 5. **Video/Reels Support**
+- Major complexity (video processing, streaming infrastructure)
+- Recommendation: Launch with photos only, add video after validation
+
+#### 6. **Direct Messaging**
+- Separate subsystem (chat infrastructure different from feed)
+- Recommendation: Use Pusher/Stream for real-time or defer entirely
+
+---
+
+### 📋 Summary
+
+|Decision|Recommendation|If Changed|
+|----------|----------------|------------|
+|Storage|Cloudinary|+3 hrs setup|
+|Feed|Follow-only|+2 hrs query optimization|
+|Auth|Clerk|-3 hrs dev time|
+|Real-time|Polling|+5 hrs WebSocket setup|
+|Video|Defer to v2|N/A|
+|DM|Defer to v2|N/A|
+
+**Total Estimated MVP Time:** 15-20 hours with recommendations above
+```
+
+---
+
+### 🎯 Principles Recap
+
+1. **Every question = Architectural decision** → Not data gathering
+2. **Show trade-offs** → User understands consequences
+3. **Prioritize blocking decisions** → Cannot proceed without
+4. **Provide defaults** → If user doesn't answer, we proceed anyway
+5. **Domain-aware** → Ecommerce questions ≠ Auth questions ≠ Real-time questions
+6. **Iterative** → More questions as patterns emerge during implementation