jettypod 3.0.1

package/docs/core-jettypod-methodology/deprecated/vibe-coding-framework.md

@@ -0,0 +1,1544 @@
+# The Vibe Coding System - Core Framework
+
+## Why This System Exists
+
+Everyone should have a side project that could become real.
+
+Not hobbyist tinkering. Not premature startup theater. This is disciplined development that keeps doors open. Your side project is your insurance policy. Build like it matters, because it might.
+
+This system teaches you to build production-quality software in the time you have. Claude is your technical co-founder for $20/month. The difference between a toy and a real product is smaller than you think with the right approach.
+
+## The Vibe Coding Philosophy
+
+### Core Values
+
+**Momentum**  
+Building software includes frustrating moments for everyone. Ship simple, complete features regularly - each working piece maintains morale and teaches you something. Momentum isn't about speed or size, it's about consistent forward progress that keeps you engaged as you inevitably face confusion.
+
+**Humility**  
+You're operating outside your circle of competence - respect that. Even if you've been around software for years, building it is different. You don't have the pattern recognition of an engineer. Success requires actively pursuing understanding - ask why things work, test assumptions, verify outcomes. You can't fake it here. Understanding must be earned.
+
+**Simplicity**  
+Claude excels at simple, well-defined tasks but struggles with complexity. Success with AI means breaking everything down to its simplest form. This constraint is actually your superpower - it forces you to build what you can understand and maintain. Simple code is debuggable code. Simple code is shippable code. Start simple, stay simple longer than feels comfortable.
+
+**Patience**  
+Good systems grow, they aren't built. Speed Mode code becoming Production code takes time. Standards emerge from patterns. Understanding comes from iteration. Rushing to Production Mode before you're ready creates disasters - patience prevents rewrites.
+
+### Operating Principles
+
+**The Three Pillars:**
+1. **Momentum over perfection** - Ship broken rather than perfect
+2. **Tests are the only truth** - Docs lie, tests run
+3. **Make it work → Make it good → Make it great** - Natural progression through modes
+
+**The AI Partnership:**
+- **AI is a partner, not a compiler** - Have conversations, not commands
+- **AI context is hard and it's on YOU** - Claude can't read your mind
+- **Lean into AI's strengths** - Boilerplate, refactoring, explaining
+- **Garbage in, garbage out** - Vague requests get enterprise spaghetti
+
+**The Speed Principles:**
+- **Code is cheap** - Throw away code freely, rebuild from scratch often
+- **Perspective is cheap** - Have models wear different hats (security reviewer, user, architect)
+- **Prototypes > technical planning** - Build to learn what you need
+- **Slow is smooth, smooth is fast** - Rushing creates messes that slow you down
+
+**The Documentation Truth:**
+- **Actual docs are scratch pads** - They're lies the moment you write them
+- **Tests are docs, docs are tests** - One source of truth
+- **Never skip tests** - Even in Speed Mode, 3 tests minimum
+
+### Core Practices
+
+**Building Practices:**
+- **BDD always** - Given/When/Then before any code
+- **Mode-based development** - Altitude determines approach
+- **Progressive standardization** - Standards emerge naturally through modes
+- **Dogfooding** - Use what you build while building it
+- **Aggressive prototyping** - When unclear, build 3 versions
+- **Prototype drilling** - Go deep on unclear aspects quickly
+
+**Maintenance Practices:**
+- **Refactor 20% of the time** - Boy Scout rule, constant improvement
+- **Test maintenance > feature development** - Tests are the product
+- **Frequent commits** - Working checkpoints every 30 minutes
+- **Pre-commit test checks** - Never commit red tests
+- **Always understand how everything works** - No magic, no mysteries
+
+**Planning Practices:**
+- **Plan epics lightly until active** - Details emerge through building
+- **Surface the right context at the right time** - Mode-appropriate information
+- **Short implementation documents** - Keep Claude on track
+- **Model-to-model feedback** - Have Claude review Claude's code
+
+---
+
+## Core Principle: Test-Driven Everything
+
+**The Foundation:** Tests ARE your application. Not documentation about your application - they ARE the application specification.
+
+**The Practice:** 
+1. Write Gherkin scenarios BEFORE any code
+2. Tests fail (red)
+3. Implement to make tests pass (green)
+4. Tests become living documentation
+
+**No separate artifacts.** No README. No comments. No documentation. Just executable Gherkin scenarios.
+
+---
+
+## The Two-Level Testing Architecture
+
+**The Revelation:** Not all tests are created equal. There are exactly two types of tests that matter, and knowing when to use each is the key to moving fast without breaking things.
+
+### Level 1: User-Facing Tests (Gherkin)
+**What they test:** What users can see and do
+**When to write:** ALWAYS - these define your product
+**Examples:**
+```gherkin
+Scenario: User completes a task
+  Given I have a task "Write tests"
+  When I mark it complete
+  Then the task shows as done
+  And my completion count increases
+```
+
+These tests ARE your product specification. If it's not in a Gherkin test, it doesn't exist from the user's perspective.
+
+### Level 2: Code-Facing Tests (Unit Tests)
+**What they test:** Complex internal logic that users don't see
+**When to write:** ONLY for complex calculations, algorithms, or business rules
+**Examples:**
+```javascript
+test('calculates compound interest correctly', () => {
+  expect(calculateInterest(1000, 0.05, 12, 10)).toBe(1647.01)
+})
+```
+
+These tests document HOW your code works internally. They're for developer confidence, not user features.
+
+### The Mode-Based Testing Strategy
+
+**Discovery Mode:**
+- User-Facing: 3-5 vague scenarios to explore
+- Code-Facing: NONE - code is throwaway
+
+**Speed Mode:**
+- User-Facing: 3-5 clear scenarios that define MVP
+- Code-Facing: ONLY for complex logic (calculations, algorithms)
+- Skip unit tests for: Simple CRUD, UI logic, straightforward data flow
+
+**Production Mode:**
+- User-Facing: Comprehensive scenarios for all user paths
+- Code-Facing: Full coverage for business logic, security, data integrity
+
+**Recovery Mode:**
+- User-Facing: Test that reproduces the bug
+- Code-Facing: Unit test to isolate the exact problem
+
+### The Critical Insight
+
+In Speed Mode, you can ship with ONLY green User-Facing tests and no unit tests because:
+1. User-Facing tests catch what matters (user experience)
+2. Simple code doesn't need unit tests (CRUD, basic UI)
+3. Complex logic gets unit tests even in Speed Mode
+4. You can add unit tests later when elevating to Production
+
+This is why Speed Mode works - you're not skipping quality, you're focusing on user value.
+
+### Examples by Mode
+
+**Speed Mode Testing (90% of your work):**
+```gherkin
+# User-Facing Test (Required)
+Scenario: Calculate monthly budget
+  Given I have $5000 income
+  And $3000 in expenses
+  When I view my budget
+  Then I see $2000 surplus
+
+# Code-Facing Test (Only because math is complex)
+test('budget calculations', () => {
+  const budget = calculateBudget(5000, 3000)
+  expect(budget.surplus).toBe(2000)
+  expect(budget.savingsRate).toBe(0.4)
+})
+```
+
+**What you DON'T test in Speed Mode:**
+- Form validation (covered by User-Facing tests)
+- Data fetching (covered by User-Facing tests)
+- Component rendering (covered by User-Facing tests)
+- Simple state updates (too simple to break)
+
+**Production Mode Testing (When it matters):**
+```gherkin
+# User-Facing Test (Comprehensive)
+Scenario Outline: Handle various payment amounts
+  Given a payment of <amount>
+  When processed with <method>
+  Then <result>
+  
+  Examples:
+    | amount | method | result |
+    | $10    | card   | success |
+    | $0     | card   | error: invalid amount |
+    | $10000 | card   | error: limit exceeded |
+
+# Code-Facing Tests (Everything that could break)
+describe('Payment Processing', () => {
+  test('validates amount ranges')
+  test('handles currency conversion')
+  test('applies correct fees')
+  test('manages transaction states')
+  test('implements retry logic')
+})
+```
+
+### The Two-Level Truth
+
+- **User-Facing Tests** = The truth about what your product does
+- **Code-Facing Tests** = The truth about how your code works
+- **Together** = Complete confidence without over-testing
+
+This architecture prevents both the "no tests" disaster AND the "too many tests" paralysis. You test what matters, when it matters, at the level that matters.
+
+---
+
+## The Altitude Framework
+
+### Three Altitudes of Development
+
+**Project Altitude (Strategic - months/years)**
+- Discovery Mode: "What should I build?"
+- Speed Mode: "Make it work"
+- Production Mode: "Make it reliable"
+
+**Feature Altitude (Tactical - days/weeks)**
+- Inherits ceiling from Project Altitude
+- Can be lower than project, never higher
+- Own mini-progression within project constraints
+
+**Task Altitude (Operational - hours)**
+- Single mode per task
+- No progression
+- Determined by Feature and Project context
+
+### Mode Selection Matrix
+
+```
+CLARITY + RISK = MODE
+
+Low Clarity  + Low Risk  = Discovery Mode
+High Clarity + Low Risk  = Speed Mode
+High Clarity + High Risk = Production Mode
+Low Clarity  + High Risk = STOP (Discovery first, then Production)
+```
+
+### Altitude Constraints
+
+- **Project in Discovery** → Everything is Discovery
+- **Project in Speed** → Features can be Discovery or Speed (never Production)
+- **Project in Production** → Features can be any mode (default to Production)
+
+---
+
+## Mode Specifications
+
+### Discovery Mode
+**Purpose:** Figure out what to build through exploration
+
+**Core Approach:**
+- Build multiple prototypes to explore 3 levels of complexity
+- Change everything freely
+- Learn what works
+- No standards needed
+
+### Speed Mode  
+**Purpose:** Ship working software quickly
+
+**Core Approach:**
+- Simplest implementation that works
+- Cut every corner that doesn't matter
+- Progressive standards emerge naturally
+- Ship in hours, not days
+
+### Production Mode
+**Purpose:** Build reliable systems
+
+**Core Approach:**
+- Comprehensive test coverage
+- Handle all edge cases
+- Security and monitoring built-in
+- Full standards enforcement
+
+### Recovery Mode
+**Purpose:** Fix what's broken
+
+**Core Approach:**
+- Stop the bleeding first
+- Reproduce the issue with tests
+- Fix systematically
+- Return to previous mode when stable
+
+---
+
+## Use Cases
+
+### Starting a New Project
+
+#### Discovery Mode: Starting a New Project
+
+**The Situation**  
+You have an idea but aren't sure exactly what to build. Multiple approaches seem viable. You need to explore before committing.
+
+**The Goal**  
+Achieve clarity on your happy path - what's the core workflow that delivers value. You don't need to understand edge cases or full requirements, just the main thing users will do repeatedly. Test assumptions cheaply. Find the simplest version that resonates.
+
+**The Approach**  
+Build 3 working prototypes at different complexity levels (simple/medium/ambitious). Understand pros and cons of each. Ask AI what it considered but didn't pitch for each level - there might be bad assumptions. Test with real people (not friends). Let usage guide your decision.
+
+**Gherkin Scenarios**
+```gherkin
+# Prototype 1: Task-based approach
+Scenario: User completes a task
+  Given I have work to do
+  When I use approach 1
+  Then I see if this helps
+
+# Prototype 2: Timeline-based approach  
+Scenario: User views their timeline
+  Given I want to see my history
+  When I use approach 2
+  Then I learn if this is better
+
+# Keep scenarios vague - you're learning
+```
+
+**Technical Checklist**
+- [ ] Each prototype in separate file
+- [ ] No shared code between prototypes
+- [ ] Use CDNs, no build process
+- [ ] Deploy each to separate URL
+- [ ] Built in hours, not days
+- [ ] No auth, no database
+- [ ] Different UI paradigms
+
+**Claude Prompting Strategy**
+```
+## YOUR PRIORITY
+Help the user figure out what they want to build by showing options.
+
+## AUTOMATIC BEHAVIOR
+For ANY feature request, ALWAYS respond with this format:
+
+"I'll show you 3 different approaches for [specific feature/task]:
+
+**Option 1: Simple**
+[Brief description - quickest to build]
+- **Pros**: ✅ [2-3 specific advantages]
+- **Cons**: ❌ [2-3 specific trade-offs]
+- **Time to build**: [estimate]
+
+**Option 2: Balanced**
+[Brief description - good mix of features and effort]
+- **Pros**: ✅ [2-3 specific advantages]
+- **Cons**: ❌ [2-3 specific trade-offs]
+- **Time to build**: [estimate]
+
+**Option 3: Advanced**
+[Brief description - most features, most complex]
+- **Pros**: ✅ [2-3 specific advantages]
+- **Cons**: ❌ [2-3 specific trade-offs]
+- **Time to build**: [estimate]
+
+**Additional options considered but not recommended:**
+- *Simple alternative*: [Brief description] - Not selected because [1-line reason]
+- *Balanced alternative*: [Brief description] - Not selected because [1-line reason]
+- *Advanced alternative*: [Brief description] - Not selected because [1-line reason]
+
+**Would you like me to create working prototypes of these options?**
+
+If yes, which ones interest you most? Or should we refine the approach first?"
+
+ONLY after user confirms, create the requested prototypes.
+
+## TECHNICAL APPROACH FOR PROTOTYPES
+- Each prototype should be functional
+- Use different techniques to show trade-offs
+- Show different technical approaches when relevant
+
+## DISCOVERY MODE RULES
+1. Always show 3 options, even if the user seems certain
+2. Create actual working prototypes, not just descriptions
+3. Highlight trade-offs clearly (time, complexity, maintenance)
+4. After showing options, ask: "Which approach resonates with you?"
+5. Keep prototypes simple enough to understand
+6. Use comments to explain key differences
+
+## PROTOTYPE FILE NAMING
+When creating prototypes, ALWAYS use this naming convention:
+- Place in `/prototypes/` directory
+- Name format: `[YYYY-MM-DD]-[feature-name]-option[1-3]-[complexity].js`
+- Examples:
+  - `2025-09-02-search-option1-simple.js`
+  - `2025-09-02-search-option2-balanced.js`
+  - `2025-09-02-search-option3-advanced.js`
+
+## EXPLORATION AREAS
+When exploring options, consider variations in:
+- Architecture patterns (MVC, Component-based, Functional)
+- State management (Local, Context, Redux, Zustand)
+- Styling approaches (CSS, CSS-in-JS, Tailwind, Component libraries)
+- Data fetching (fetch, axios, SWR, React Query)
+- Testing strategies (No tests, Unit tests, Integration, E2E)
+- Build complexity (CRA, Vite, Next.js, Custom webpack)
+- Type safety (JavaScript, TypeScript, PropTypes)
+- Performance optimization levels
+```
+
+**Common Pitfalls**
+- Building one "perfect" version instead of multiple rough ones
+- Asking friends instead of strangers for feedback
+- Adding features instead of testing core concept
+- Analysis paralysis - not shipping anything
+
+**Graduation Criteria**
+- Clear winner emerges from prototypes → Speed Mode
+- Still confused after 3+ prototypes → More Discovery
+- None resonate → Consider different problem
+
+**Real Example**
+"For my workout tracker, I built three prototypes:
+1. Simple list with checkboxes (30 minutes)
+2. Calendar view with dots for completed days (45 minutes)  
+3. Graph showing progressive overload (1 hour)
+
+The calendar view immediately clicked with testers. Threw away the others, moved to Speed Mode with calendar approach."
+
+---
+
+#### Speed Mode: Starting a New Project
+
+**The Situation**  
+You know exactly what to build. The approach is clear from Discovery Mode or prior experience. You just need to ship it fast and see if it's actually useful. This is about building momentum, not perfection.
+
+**The Goal**  
+Ship working software in 1-2 hours typically, 4 hours absolute maximum. Get it in users' hands TODAY. Build momentum through visible progress. Remember: momentum over perfection, code is cheap, slow is smooth and smooth is fast.
+
+**The Philosophy**  
+Speed Mode isn't about being sloppy - it's about being ruthlessly focused. Every line of code either delivers core value or it doesn't exist. You're testing if this thing should exist, not building the perfect version of it. Tests are still truth, but only 3-5 truths matter right now.
+
+**The Approach**  
+One file to rule them all. Every feature that isn't core value gets cut. localStorage is your database. Tailwind CDN is your design system. Your laptop is your CI/CD. Ship to a static hosting service with one click (Netlify, Vercel, Surge, GitHub Pages, Cloudflare Pages - whatever's fastest for you). If it takes more than 2 hours, you're probably over-building. If it takes more than 4 hours, you're definitely in the wrong mode.
+
+**Gherkin Scenarios (Write These FIRST)**
+```gherkin
+Feature: [One-Line Description of Core Value]
+  # These 3-5 scenarios ARE your product spec
+  # If it's not in these scenarios, it doesn't exist
+
+Scenario: The Happy Path
+  Given I'm a user with [specific problem]
+  When I [do the main action]
+  Then [problem is measurably solved]
+  # This is THE scenario that matters most
+
+Scenario: Data Persists
+  Given I did work in the app
+  When I refresh/return later
+  Then my work is still there
+  # localStorage must work or users will hate you
+
+Scenario: Core Interaction Feels Good
+  Given I'm using the app
+  When I perform [most common action]
+  Then it responds in under 100ms
+  And I can see what happened
+  # Speed of feedback is a feature
+
+# MAXIMUM 5 scenarios. Not 6. Not "just this one more."
+# These tests ARE your documentation
+```
+
+**Technical Checklist**
+- [ ] Write 3-5 Gherkin scenarios FIRST (10-15 min)
+- [ ] Single HTML file with <script> tags OR single React component
+- [ ] localStorage for ALL persistence (no databases, no backends)
+- [ ] Tailwind via CDN for styling (no custom CSS files)
+- [ ] No auth unless it's literally the core feature
+- [ ] No build process (if you're running npm build, you're doing it wrong)
+- [ ] Deploy via drag-and-drop or CLI to static hosting (Netlify, Vercel, Surge, GitHub Pages, etc.)
+- [ ] Works on mobile (test on your phone before shipping)
+- [ ] Tests can run by opening the HTML file
+- [ ] Commit working code every 30 minutes
+
+**Claude Prompting Strategy**
+```
+## SPEED MODE CONTEXT
+You are helping me ship working software in 1-2 hours (4 hours absolute max).
+Momentum over perfection. Tests are truth but keep it minimal.
+
+## THE SCENARIOS (These ARE the spec)
+[Paste your 3-5 Gherkin scenarios]
+
+## YOUR CONSTRAINTS
+1. Single file application (HTML with scripts OR single React component)
+2. localStorage for all persistence (no backend, no database)
+3. Tailwind CDN for all styling (no custom CSS)
+4. Must pass these exact scenarios - nothing more
+5. Simplest possible implementation that works
+6. No features beyond these scenarios
+7. Comments only where the code is genuinely surprising
+
+## TECHNICAL APPROACH
+- Start with the HTML structure
+- Add the simplest possible state management
+- Use onclick handlers, not complex event systems
+- Use array methods liberally (map, filter, reduce)
+- Use template literals for rendering
+- If using React, useState only (no Context, no Redux)
+- Error handling: console.error is fine
+- Loading states: not needed if fast enough
+
+## WHAT SUCCESS LOOKS LIKE
+The app works, deploys in one click, and users can immediately understand it.
+If you're explaining how to set it up, you've failed.
+
+Start with the HTML structure and the simplest possible way to pass the first scenario.
+```
+
+**The Speed Mode Mantras**
+- "If it's not in the test, it doesn't exist"
+- "Every feature that can be cut should be cut"
+- "localhost to user feedback in 1-2 hours"
+- "Code is cheap, throw it all away tomorrow if needed"
+- "Ship broken rather than perfect"
+- "Momentum over perfection"
+- "If it's taking 4 hours, you're building too much"
+
+**Common Pitfalls**
+- **The "Just One More Feature" Trap**: After each scenario passes, you think of something else. DON'T. Ship what you have.
+- **The "Proper Setup" Trap**: Installing webpack, setting up ESLint, configuring TypeScript. You've already failed.
+- **The "Future Scale" Trap**: "What if 1000 users..." You don't have 10 users. Stop it.
+- **The "Code Quality" Trap**: Refactoring before shipping. The code works. Ship it.
+- **The "Edge Case" Trap**: "What about users who..." They'll tell you if it matters.
+- **The "Documentation" Trap**: Writing README files. Your 5 scenarios ARE the docs.
+
+**The Realistic Timeline**
+```
+30 minutes: Scenarios written, HTML structure, first test passing
+1 hour: Core functionality working, 3+ tests passing
+1.5 hours: All tests passing, deployed, getting feedback
+
+If you're still coding at:
+2 hours: You're probably adding unnecessary features
+3 hours: You're definitely over-building  
+4 hours: Wrong mode, abort mission
+```
+
+**Graduation Criteria**
+- **To Production Mode**: 10+ real users actively using AND handling sensitive data
+- **Stay in Speed Mode**: Core value validated, users want more features
+- **Back to Discovery**: Users confused, not solving the problem, engagement drops
+- **To Recovery**: You broke something that was working
+
+**Real Example (With Actual Timeline)**
+```
+"Built a daily standup tool in 90 minutes:
+
+Minute 0-10: Wrote 4 scenarios
+1. Create today's update
+2. See yesterday's update  
+3. Mark blockers
+4. Data persists
+
+Minute 10-30: HTML structure + first scenario
+- Form with 3 textareas (yesterday/today/blockers)
+- Save button
+- localStorage.setItem on save
+
+Minute 30-60: All core features
+- Show previous update on load
+- Clear form after save
+- Add date stamps
+
+Minute 60-80: Quick polish
+- Tailwind styling (just enough)
+- Character counts
+- Keyboard shortcut (Cmd+Enter to save)
+
+Minute 80-90: Deployed
+- Dragged folder to Netlify
+- Shared link in Slack
+- First feedback: 'Can we have history?'
+- Me: 'Great idea for tomorrow!'
+
+Total lines of code: 147
+Total time: 1.5 hours
+Total user value: Replaced $50/mo SaaS tool"
+```
+
+**The Speed Mode Checklist Before Shipping**
+```
+□ All 3-5 scenarios passing?
+□ Deployable with one click?
+□ Works on your phone?
+□ Could your mom understand what it does?
+□ Did this take less than 2 hours? (Good!)
+□ Did this take less than 4 hours? (Acceptable)
+
+If all checked → SHIP IT NOW
+If took more than 4 hours → You're not in Speed Mode
+```
+
+---
+
+#### Production Mode: Starting a New Project
+
+**⚠️ WARNING: This is almost never the right choice**
+
+**The Situation**  
+You're considering starting in Production Mode because you're handling sensitive data or replacing a critical system. STOP. You're probably wrong. Even with sensitive data, start in Speed Mode with fake data. You need to learn what you're actually building first.
+
+**The ONLY Valid Reasons to Start Here:**
+1. You're rebuilding something that already exists with EXACT requirements
+2. You have complete specifications from an existing system
+3. You've built this exact thing before multiple times
+4. There are regulatory requirements from day one AND you can't use fake data
+
+**If any doubt exists → Start in Speed Mode with fake data**
+
+**Why Starting Here Is Usually Wrong**  
+Starting in Production Mode means you're optimizing for problems you don't have yet. You'll build abstractions for requirements that will change. You'll add security for threats that don't exist. You'll create architecture for scale you'll never reach. Meanwhile, you won't ship anything for weeks, losing momentum and learning nothing about what users actually need.
+
+**The Reality Check**
+```
+"I'm handling payment data" → Use Speed Mode with Stripe test mode
+"It's healthcare data" → Use Speed Mode with fake patients  
+"It's replacing a critical system" → Use Speed Mode as a prototype first
+"It needs to be secure" → Speed Mode code with fake data IS secure
+"What if we get hacked?" → You have zero users
+"But technical debt!" → Code is cheap, throw it away later
+```
+
+**If You Actually Need to Start in Production Mode**  
+This should feel constraining - like coding with heavy gloves on. You're choosing to move 10x slower to avoid risks that probably don't exist yet. Make sure you're certain about the requirements because changes will be expensive.
+
+**The Approach**  
+Since you've decided to start here: Full test coverage before features. Real auth service from day one. Real database with migrations. Monitoring and logging from the start. Security review before first deploy. This will take weeks, not hours.
+
+**Gherkin Scenarios (Need Clear Requirements)**
+```gherkin
+Feature: Production-Ready Foundation
+  # These should be exact requirements that won't change
+
+Background:
+  Given proper authentication system
+  And comprehensive audit logging
+  And complete input validation
+  # You're paying for this complexity upfront
+
+Scenario: User registration with full validation
+  Given a new user registration attempt
+  When they provide valid data
+  Then account created with proper encryption
+  And email verified through double opt-in
+  And audit trail captures every field
+  And GDPR consent recorded
+  And rate limiting applied
+  # Make sure you actually need all this
+
+Scenario: Concurrent operations handling
+  Given multiple simultaneous database writes
+  When conflicts occur
+  Then transactions maintain ACID properties
+  And optimistic locking prevents corruption
+  And retry logic handles transient failures
+  # This complexity should be necessary
+```
+
+**Technical Checklist (Weeks of Work)**
+- [ ] Complete test suite (100+ scenarios)
+- [ ] Auth service (Auth0/Clerk/Supabase)
+- [ ] PostgreSQL with migration strategy
+- [ ] Secrets management system
+- [ ] Input validation on every field
+- [ ] Error tracking (Sentry)
+- [ ] Structured logging (with log aggregation)
+- [ ] API rate limiting by user and IP
+- [ ] Automated backup strategy
+- [ ] CI/CD pipeline with multiple environments
+- [ ] Staging environment matching production
+- [ ] Security scanning in pipeline
+- [ ] Load testing infrastructure
+- [ ] Monitoring and alerting
+- [ ] Incident response playbooks
+
+**The Realistic Timeline**
+```
+Week 1: Setting up infrastructure, still no features
+Week 2: Auth system, still no value delivered  
+Week 3: Data model and migrations, users getting impatient
+Week 4: First actual feature, realize requirements were wrong
+Week 5: Refactoring to match actual needs
+Week 6: Wishing you'd started with Speed Mode
+```
+
+**Common Pitfalls (Besides Starting Here)**
+- Building for 1000 users when you don't have 1
+- "Proper" architecture that doesn't match actual needs
+- Security theater for non-existent threats
+- Premature optimization everywhere
+- Analysis paralysis on every decision
+- Never actually shipping anything
+
+**Graduation Criteria**
+- Not applicable - you started at the end
+- When requirements change → Consider if Speed Mode would help you learn faster
+
+**A More Realistic Example**
+```
+"Building a healthcare appointment system:
+
+What works better:
+Day 1: Speed Mode with fake patients
+Day 2: Learned the workflow was wrong
+Day 3: Rebuilt with correct workflow
+Week 2: 50 beta users with fake data
+Week 3: Validated all assumptions
+Week 4: NOW move to Production Mode with real requirements
+
+What happens when you start in Production:
+Week 1-2: Built auth and data model
+Week 3-4: Built features based on assumptions
+Week 5-6: Realized assumptions were wrong
+Week 7-8: Rebuilt in Speed Mode to learn
+Total time lost: 4 weeks"
+```
+
+**The Bottom Line**
+If you're reading this section to start a new project, you're probably in the wrong section. Go back to Speed Mode. Build with fake data. Learn what you actually need. Then come back here to add Production features to your working Speed Mode code.
+
+**Remember: Tests are truth, but you don't know what truth is yet.**
+
+---
+
+### Building New Features
+
+#### Discovery Mode: Building New Features
+
+**The Situation**  
+Your project is stable but you're not sure what feature to add next. Multiple user requests but unclear which matters. Need to test feature-market fit.
+
+**The Goal**  
+Figure out what feature actually adds value. Test different approaches without destabilizing your working app.
+
+**The Approach**  
+Build feature prototypes separately from main app. Test with subset of users. Use feature flags or separate URLs.
+
+**Gherkin Scenarios**
+```gherkin
+# Exploring feature value
+Scenario: Feature might solve problem
+  Given user has [potential problem]
+  When they try [feature approach]
+  Then we learn if this helps
+
+# Multiple variants to test
+Scenario: Variant A
+  Given the feature works like X
+  When user interacts
+  Then measure engagement
+
+Scenario: Variant B  
+  Given the feature works like Y
+  When user interacts
+  Then compare to variant A
+```
+
+**Technical Checklist**
+- [ ] Separate prototype files
+- [ ] Feature flags for testing
+- [ ] Analytics to measure usage
+- [ ] Quick user feedback loops
+- [ ] No integration with core yet
+- [ ] Time-boxed exploration
+
+**Claude Prompting Strategy**
+```
+"I need to explore adding [feature] to my [app].
+Create 3 different approaches:
+1. [Simple version]
+2. [Different paradigm]
+3. [Ambitious version]
+
+Build each as standalone prototype.
+Must be testable independently."
+```
+
+**Common Pitfalls**
+- Building the feature fully before validating
+- Testing with existing users only (bias)
+- Integration before validation
+- Analysis paralysis on approach
+
+**Graduation Criteria**
+- Clear approach validated → Speed Mode
+- Feature doesn't resonate → Kill it
+- Need more data → More Discovery
+
+**Real Example**
+"Testing 'social features' for workout app:
+- Built 3 prototypes: comments, kudos, challenges
+- Deployed each to different test groups
+- Kudos had 80% engagement, others <20%
+- Moved kudos to Speed Mode, killed others"
+
+---
+
+#### Speed Mode: Building New Features
+
+**The Situation**  
+Your project is in Speed Mode and working well. Users are asking for a specific feature. You know what to build.
+
+**The Goal**  
+Add value quickly without breaking what works. Maintain momentum. Ship to users within hours.
+
+**The Approach**  
+Add feature in isolation. Minimal integration with existing code. Ship behind feature flag if risky. 2-hour timebox.
+
+**Gherkin Scenarios**
+```gherkin
+Feature: [New Feature Name]
+
+Scenario: Feature delivers value
+  Given existing user workflow
+  When new feature is used
+  Then clear value delivered
+
+Scenario: Doesn't break existing
+  Given current functionality
+  When new feature added
+  Then old features still work
+
+Scenario: Data consistency
+  Given feature creates data
+  When app restarts
+  Then data persists correctly
+
+# 3-5 scenarios max for speed
+```
+
+**Technical Checklist**
+- [ ] 2-hour implementation timebox
+- [ ] Feature flag optional but nice
+- [ ] Minimal refactoring of existing
+- [ ] New code in separate functions
+- [ ] Basic error handling only
+- [ ] Ship same day
+- [ ] Test with real users immediately
+
+**Claude Prompting Strategy**
+```
+"Current app: [brief context or paste main file]
+Current tests: [paste existing scenarios]
+
+Add this feature: [description]
+New scenarios to pass: [3-5 new scenarios]
+
+Requirements:
+- Don't break existing tests
+- Minimal changes to current code
+- Ship within 2 hours
+- Feature flag: ENABLE_[FEATURE]"
+```
+
+**Common Pitfalls**
+- Scope creep - "while we're at it"
+- Refactoring existing code unnecessarily
+- Over-engineering for future
+- Not shipping same day
+- Too many test scenarios
+
+**Graduation Criteria**
+- Feature working + users happy → Stay in Speed
+- Feature critical to business → Elevate to Production
+- Feature unused after week → Remove it
+
+**Real Example**
+"Adding search to expense tracker:
+- 90 minutes total
+- Added searchTerm to state
+- Filter function before display
+- Three tests: search by name, amount, category
+- Shipped via feature flag
+- 100% adoption within 3 days"
+
+---
+
+#### Production Mode: Building New Features
+
+**The Situation**  
+Your project is in Production with real users depending on it. Adding a feature that touches critical paths or handles sensitive data.
+
+**The Goal**  
+Add feature without compromising reliability. Maintain security and performance. Enable confident iteration.
+
+**The Approach**  
+Full test coverage before implementation. Gradual rollout. Performance testing. Security review. Monitoring from day one.
+
+**Gherkin Scenarios**
+```gherkin
+Feature: Production-Grade [Feature]
+
+Scenario: Happy path
+  Given perfect conditions
+  When feature is used
+  Then expected outcome
+  And performance maintained
+  And audit logged
+
+Scenario Outline: Edge cases
+  Given <edge_condition>
+  When feature is used
+  Then <graceful_handling>
+  
+  Examples:
+    | edge_condition | graceful_handling |
+    | null input | validation error |
+    | concurrent use | locks properly |
+    | malicious input | sanitized |
+
+Scenario: Load testing
+  Given 100 concurrent users
+  When all use feature
+  Then response time < 200ms
+  And no data corruption
+
+Scenario: Rollback safety
+  Given feature is enabled
+  When critical error occurs
+  Then feature auto-disables
+  And system continues working
+```
+
+**Technical Checklist**
+- [ ] Design doc reviewed
+- [ ] Full test suite first
+- [ ] Database migrations safe
+- [ ] API versioning considered
+- [ ] Feature flags required
+- [ ] Performance benchmarked
+- [ ] Security reviewed
+- [ ] Monitoring configured
+- [ ] Rollback plan documented
+- [ ] Gradual rollout planned
+
+**Claude Prompting Strategy**
+```
+"Production feature addition:
+System context: [architecture overview]
+Current tests: [existing test suite]
+Feature requirements: [detailed spec]
+New scenarios: [comprehensive Gherkin]
+
+Requirements:
+- Full error handling
+- Transaction safety
+- Performance optimization
+- Security validation
+- Monitoring integration
+- Migration safety
+
+Start with implementation plan."
+```
+
+**Common Pitfalls**
+- Rushing due to pressure
+- Skipping load testing
+- No rollback plan
+- Inadequate monitoring
+- Breaking API contracts
+
+**Graduation Criteria**
+- Feature stable for 30 days → Success
+- Issues in production → Recovery Mode
+- Feature complete → Back to Speed for next feature
+
+**Real Example**
+"Adding payment processing:
+Week 1: Stripe integration design, security review
+Week 2: Test suite (50+ scenarios), implementation
+Week 3: Load testing, security scan
+Week 4: Gradual rollout (1%, 10%, 50%, 100%)
+Zero payment failures in first month"
+
+---
+
+### Refactoring
+
+#### Speed Mode: Refactoring
+
+**The Situation**  
+Your Speed Mode code is getting messy. Files too long. Duplication appearing. Still works but harder to maintain.
+
+**The Goal**  
+Reduce daily friction without stopping progress. Make code maintainable enough to keep shipping.
+
+**The Approach**  
+Extract obvious components. Improve naming. Remove duplication. Keep all tests passing. Don't add features.
+
+**Gherkin Scenarios**
+```gherkin
+# Tests don't change during refactoring!
+# These ensure behavior stays the same:
+
+Scenario: All existing features still work
+  Given each existing test
+  When run after refactoring
+  Then all still pass
+
+Scenario: Performance maintained
+  Given current response times
+  When code is refactored
+  Then same or better performance
+
+# No new scenarios - refactoring only
+```
+
+**Technical Checklist**
+- [ ] One refactor type at a time
+- [ ] Tests passing after each change
+- [ ] Commit after each successful refactor
+- [ ] No new features during refactor
+- [ ] Time-box to 2 hours
+- [ ] Focus on biggest pain points
+
+**Claude Prompting Strategy**
+```
+"Refactor this code for better organization:
+[paste current code]
+Current tests: [paste tests]
+
+Refactoring goals:
+- Extract [component] into separate function
+- Rename variables for clarity
+- Remove duplication in [area]
+
+Keep all tests passing. No behavior changes."
+```
+
+**Common Pitfalls**
+- Refactoring everything at once
+- Adding features during refactoring
+- Breaking tests and "fixing later"
+- Over-abstracting
+- Refactoring without clear goal
+
+**Graduation Criteria**
+- Code maintainable → Continue building
+- Still messy → Another refactor session
+- Tests failing → Recovery Mode
+
+**Real Example**
+"Expense tracker refactor:
+- 500 line component → 5 files
+- Extracted: ExpenseForm, ExpenseList, calculations
+- Renamed: 'x', 'temp', 'data' → meaningful names
+- All tests still passing
+- 2 hours total, much easier to work with"
+
+---
+
+#### Production Mode: Refactoring
+
+**The Situation**  
+Production system needs architectural changes. Performance issues. Technical debt affecting reliability. Team struggling with complexity.
+
+**The Goal**  
+Improve system maintainability without disrupting service. Enable faster future development. Reduce operational burden.
+
+**The Approach**  
+Add comprehensive tests for current behavior. Refactor with safety net. Measure everything. Deploy carefully with rollback ready.
+
+**Gherkin Scenarios**
+```gherkin
+Feature: Refactoring Safety
+
+Scenario: Behavior preservation
+  Given all current functionality
+  When refactoring complete
+  Then identical behavior
+  And all tests still pass
+
+Scenario: Performance improvement
+  Given current metrics baseline
+  When refactored code runs
+  Then performance same or better
+  And resource usage reduced
+
+Scenario: Backward compatibility
+  Given existing API contracts
+  When refactoring deployed
+  Then all contracts honored
+  And no breaking changes
+
+Scenario: Safe rollback
+  Given refactored version live
+  When issues detected
+  Then rollback without data loss
+  And service continues
+```
+
+**Technical Checklist**
+- [ ] Current behavior fully tested
+- [ ] Performance baseline measured
+- [ ] Refactor plan reviewed
+- [ ] Changes behind feature flags
+- [ ] Blue-green deployment ready
+- [ ] Monitoring enhanced
+- [ ] Load testing completed
+- [ ] Rollback tested
+- [ ] Team informed
+- [ ] Documentation updated
+
+**Claude Prompting Strategy**
+```
+"Production refactoring needed:
+Current implementation: [code]
+Test suite: [comprehensive tests]
+Performance baseline: [metrics]
+Pain points: [specific issues]
+
+Refactoring goals:
+- [Specific improvements]
+- Maintain backward compatibility
+- Improve performance
+- Increase maintainability
+
+Provide refactoring plan first, then implementation."
+```
+
+**Common Pitfalls**
+- Refactoring without complete tests
+- Big bang deployment
+- No performance measurement
+- Breaking API contracts
+- No rollback plan
+
+**Graduation Criteria**
+- Refactoring complete, stable → Normal operation
+- Issues discovered → Recovery Mode
+- More refactoring needed → Plan next phase
+
+**Real Example**
+"Database query optimization:
+- Added query performance tests
+- Measured: 2s average response time
+- Refactored to use indexes, better joins
+- Deployed behind flag to 10% traffic
+- Measured: 200ms response time
+- Gradual rollout over 1 week
+- 10x performance improvement, zero downtime"
+
+---
+
+### Recovery Mode
+
+#### Recovery Mode: Any Situation
+
+**The Situation**  
+Something is broken in production. Users affected. Data potentially at risk. You need to fix it NOW.
+
+**The Goal**  
+Stop the bleeding immediately. Restore service. Fix root cause. Prevent recurrence.
+
+**The Approach**  
+Follow the protocol: Disable/rollback first, communicate, reproduce with test, fix systematically, add regression tests.
+
+**Gherkin Scenarios**
+```gherkin
+Feature: Bug Reproduction and Fix
+
+Scenario: Reproduce the exact bug
+  Given the exact failing conditions
+  When the broken action occurs
+  Then bug manifests (test fails)
+  # This test SHOULD fail initially
+
+Scenario: Verify the fix
+  Given the same conditions
+  When fix is applied
+  Then bug no longer occurs
+  And no new issues introduced
+
+Scenario: Regression prevention
+  Given various related inputs
+  When system processes them
+  Then no similar bugs possible
+```
+
+**Technical Checklist**
+- [ ] Service stabilized first
+- [ ] Users notified
+- [ ] Bug reproduced in test
+- [ ] Root cause identified
+- [ ] Fix implemented
+- [ ] All tests passing
+- [ ] Similar code checked
+- [ ] Monitoring added
+- [ ] Postmortem written
+- [ ] Regression tests added
+
+**Claude Prompting Strategy**
+```
+"URGENT: Production issue
+Symptoms: [what's broken]
+Error messages: [paste any errors]
+Recent changes: [what changed]
+Current code: [paste relevant code]
+
+Need:
+1. Immediate mitigation
+2. Root cause analysis
+3. Fix that won't break other things
+4. Tests to prevent recurrence"
+```
+
+**Common Pitfalls**
+- Fixing without understanding
+- Making multiple changes at once
+- Not communicating with users
+- Forgetting to add regression tests
+- Not checking for similar bugs
+
+**Graduation Criteria**
+- Service restored → Continue postmortem
+- Fix verified → Return to previous mode
+- Can't fix → Consider partial rollback
+
+**Real Example**
+"Payment processing bug:
+1. Disabled payment feature (30 seconds)
+2. Notified users with workaround
+3. Wrote test reproducing double-charge
+4. Found race condition in webhook handler
+5. Added mutex lock, fixed issue
+6. Re-enabled gradually
+7. Added 5 regression tests
+8. Total downtime: 15 minutes"
+
+---
+
+### Elevation Pattern
+
+**The Situation**  
+Your Speed Mode code is working well. Users depend on it. Time to graduate to Production Mode without rewriting.
+
+**The Goal**  
+Evolve code to production quality through test addition. No rewrites. Gradual improvement.
+
+**The Approach**  
+Add tests for edge cases first. Implement code to pass new tests. Standards emerge naturally. Architecture evolves.
+
+**Week 1-2: Current State (Speed Mode)**
+```gherkin
+# Your starting point - basic tests
+Scenario: Core function works
+  Given normal input
+  When action performed
+  Then expected output
+```
+
+**Week 3-4: Add Resilience**
+```gherkin
+# Add error handling tests
+Scenario: Handles missing data
+  Given incomplete input
+  When action attempted
+  Then graceful failure
+
+Scenario: Validates input
+  Given invalid input
+  When validation runs
+  Then clear error message
+```
+
+**Week 5-6: Add Security**
+```gherkin
+# Add security tests
+Scenario: Prevents injection
+  Given malicious input
+  When processed
+  Then attack prevented
+
+Scenario: Rate limiting works
+  Given rapid requests
+  When limit exceeded
+  Then requests blocked
+```
+
+**Week 7-8: Add Scale**
+```gherkin
+# Add performance tests
+Scenario: Handles concurrent users
+  Given 100 simultaneous users
+  When all act
+  Then system remains stable
+
+Scenario: Data integrity maintained
+  Given concurrent modifications
+  When conflicts occur
+  Then resolved correctly
+```
+
+**Technical Evolution Checklist**
+- [ ] Week 1-2: Document current behavior in tests
+- [ ] Week 3-4: Add error handling to pass new tests
+- [ ] Week 5-6: Add validation and security
+- [ ] Week 7-8: Add performance optimizations
+- [ ] Week 9-10: Add monitoring and logging
+- [ ] Week 11-12: Production ready!
+
+**Claude Prompting Strategy**
+```
+"Elevate this Speed Mode code:
+Current code: [paste]
+Current tests: [basic scenarios]
+New tests to add: [resilience scenarios]
+
+Make code pass new tests WITHOUT breaking existing.
+Add only what's needed for tests to pass."
+```
+
+**Common Pitfalls**
+- Trying to elevate everything at once
+- Rewriting instead of evolving
+- Adding features during elevation
+- Skipping test-first approach
+
+**Graduation Criteria**
+- All production tests passing → Production Mode achieved
+- Taking too long → Scope too big, split up
+- Tests revealing major issues → Consider partial rewrite
+
+**Real Example**
+"Elevating expense tracker:
+- Week 1: Added 20 tests documenting current behavior
+- Week 2: Added input validation (5 new tests)
+- Week 3: Error handling (8 new tests)
+- Week 4: localStorage corruption recovery (3 tests)
+- Week 5: Performance with 10k expenses (2 tests)
+- Week 6: Migration to IndexedDB for scale
+Never rewrote, just evolved. Now handles 50k expenses reliably."
+
+---
+
+## Standards Progression
+
+### Project Maturity Levels
+
+**Level 0: Discovery (No standards)**
+- Any file naming
+- Any structure  
+- Any patterns
+- Just explore
+
+**Level 1: Early Speed (Minimal standards)**
+- Basic file names (MyComponent.js)
+- Single folder
+- localStorage for data
+- One test file
+
+**Level 2: Late Speed (Patterns emerge)**
+- Consistent naming (PascalCase components)
+- Folders by feature
+- Basic error handling
+- Tests grouped by feature
+
+**Level 3: Early Production (Standards enforced)**
+- Full naming conventions
+- Clear architecture
+- Error boundaries
+- Comprehensive test structure
+
+**Level 4: Mature Production (Full standardization)**
+- Documented conventions (in tests)
+- Enforced via tooling
+- Design system
+- Test coverage requirements
+
+### Standards by Mode
+
+**Discovery Mode Standards:**
+- None required
+- Change freely
+- Document nothing
+
+**Speed Mode Standards:**
+```javascript
+// Minimal viable standards
+- PascalCase for components
+- camelCase for functions
+- Single /src folder
+- Tests next to code
+- localStorage for persistence
+```
+
+**Production Mode Standards:**
+```javascript
+// Full standards
+- /features folder structure
+- TypeScript required
+- Error handling required
+- 80% test coverage
+- API versioning
+- Database migrations
+- CI/CD pipeline
+```
+
+---
+
+## Technical Requirements by Mode
+
+### Discovery Mode Tech Stack
+- HTML + script tags OR
+- Single React file OR  
+- Whatever you know
+- No build process
+- No dependencies
+
+### Speed Mode Tech Stack
+- React (one file)
+- Tailwind CDN
+- localStorage
+- Netlify/Vercel
+- No auth
+- No database
+
+### Production Mode Tech Stack
+- Next.js/Remix
+- PostgreSQL/Supabase
+- Auth0/Clerk
+- Sentry
+- Monitoring
+- CI/CD
+- Backups
+
+---
+
+## Mode Switching Triggers
+
+### When to Switch Modes
+
+**Discovery → Speed**
+- "I know what to build now"
+- Can write 3-5 clear scenarios
+- Ready to ship something
+
+**Speed → Production**  
+- Real users depending on it
+- Handling sensitive data
+- Need reliability
+- Team growing
+
+**Any → Recovery**
+- Something is broken
+- Users affected
+- Data at risk
+
+**Recovery → Previous**
+- Crisis resolved
+- Tests added
+- Confidence restored
+
+### Anti-Patterns to Avoid
+
+**Discovery Mode:**
+- ❌ Writing documentation
+- ❌ Setting up CI/CD
+- ❌ Choosing standards
+
+**Speed Mode:**
+- ❌ Custom auth system
+- ❌ Microservices
+- ❌ Perfect architecture
+- ❌ >5 test scenarios
+
+**Production Mode:**
+- ❌ Shipping untested code
+- ❌ No error handling
+- ❌ Skipping security
+- ❌ No monitoring
+
+---
+
+## The Daily Workflow
+
+### Starting Each Session
+
+1. **Check altitude:** What level am I working at?
+2. **Check mode:** What mode should I be in?
+3. **Write scenarios:** What behavior am I adding?
+4. **Run tests:** What's currently broken?
+5. **Implement:** Make tests pass
+6. **Ship:** Deploy immediately
+
+### Mode-Specific Prompts
+
+**Discovery Mode:**
+```
+"Show me 3 different ways to implement these scenarios:
+[Gherkin scenarios]
+Create working prototypes I can try"
+```
+
+**Speed Mode:**
+```
+"Make these scenarios pass with simplest implementation:
+[3-5 Gherkin scenarios]
+Single file, localStorage, ship today"
+```
+
+**Production Mode:**
+```
+"Implement these scenarios with production standards:
+[Comprehensive Gherkin]
+Include error handling, validation, monitoring"
+```
+
+**Recovery Mode:**
+```
+"This scenario is failing in production:
+[Failing Gherkin]
+Fix immediately with minimal changes"
+```
+
+---
+
+## Success Metrics
+
+### By Mode
+
+**Discovery Success:**
+- Gained clarity
+- Eliminated options
+- Found the right thing to build
+
+**Speed Success:**
+- Shipped in hours
+- Users using it
+- Momentum maintained
+
+**Production Success:**
+- 99.9% uptime
+- No data loss
+- Security maintained
+- Team can contribute
+
+**Recovery Success:**
+- Service restored < 1 hour
+- No data loss
+- Root cause fixed
+- Tests prevent recurrence