This commit represents a comprehensive audit and validation of the entire ai-dev-standards automation system, restoring user confidence through systematic transparency and exhaustive proof. ## What Was Fixed ### Automation Gaps Closed - Added DOCS/RESOURCE-GUIDE.md to auto-update system - Added .claude/claude.md auto-generation from skill-registry.json - Updated scripts/update-all-files-complete.cjs to handle 8 files (was 6) - Enhanced scripts/validate-all.cjs with root file validation (22 checks total) ### Documentation Created - COMPLETE-FILE-RELATIONSHIP-AUDIT.md (12,000+ words) - DARK-MATTER-ANALYSIS-SELF-AUDIT.md (7,000+ words) - SESSION-TRANSCRIPT-2025-10-23.md (15,000+ words) - FOLDER-STRUCTURE-BREAKDOWN.md (10,000+ words) ## Validation Status ✅ 22/22 validation checks passing ✅ 37 skills synchronized ✅ 7 MCPs synchronized ✅ 100% relationship mapping coverage ✅ 8 files auto-updating correctly ✅ 0 automation gaps remaining ## Repository Coherence Index: 78/100 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
16 KiB
Validation-First Development Playbook
Purpose: Prevent wasting time and money by building the wrong thing. This playbook ensures you validate problems and solutions before committing to implementation.
When to use: At the start of every new project or feature.
Time to complete: 2-4 weeks (vs 8-12 weeks building blindly)
🎯 Core Principle
BUILD AS LITTLE AS POSSIBLE TO LEARN AS MUCH AS POSSIBLE.
Don't build anything until you've:
- ✅ Validated the problem exists and is severe
- ✅ Validated your solution actually solves it
- ✅ Validated people will pay for it
⚠️ STOP Signs
STOP if you're tempted to:
- ❌ "Just build it quickly and see if people use it"
- ❌ "I'll do some research and then start coding"
- ❌ "Let me set up the infrastructure first"
- ❌ "I need to learn this framework before I can validate"
- ❌ "I'll build a prototype to show investors"
START with:
- ✅ Talking to potential users
- ✅ Testing with landing pages
- ✅ Manually delivering the service (Concierge MVP)
- ✅ Observing current behavior
- ✅ Validating with $0 and <1 week
📊 The Playbook: 5 Phases
Phase 1: Problem Discovery (Week 1-2)
⏰ Time Limit: 2 weeks MAX - then move to Phase 2
Phase 2: Solution Validation (Day 1-3)
⏰ Time Limit: 3 days MAX - then move to Phase 3
Phase 3: MVP Build & Test (Week 1-2)
⏰ Time Limit: 2 weeks MAX - if longer, scope is too big
Phase 4: Validated Learning (Ongoing)
🎯 Gate: Must have metrics before Phase 5
Phase 5: Scale Decision
⚠️ Only proceed if metrics prove viability
Phase 1: Problem Discovery (Week 1-2)
Goal: Confirm the problem is real, frequent, painful, and worth solving
⏰ Time Limit: 2 weeks - if you're still researching after 2 weeks, STOP and move to Phase 2
Step 1.1: Define Problem Hypothesis (Day 1)
Template:
[Target users] struggle with [problem]
when they [context/situation],
which costs them [time/money/pain],
because [root cause].
Example: "Freelance designers struggle with invoice tracking when working with multiple clients, which costs them 3-5 hours per week, because existing tools are too complex or expensive."
Step 1.2: Customer Discovery Interviews (Week 1-2)
Target: 10-15 interviews minimum
Mom Test Questions (ask about past behavior, not opinions):
- "Tell me about the last time you encountered [problem]."
- "How are you currently solving this?"
- "How much time/money do you spend on this problem?"
- "What have you tried that didn't work?"
- "Walk me through your workflow when [doing related task]."
❌ DON'T ASK:
- "Would you use this product?" (Everyone says yes)
- "Do you think this is a good idea?"
- "How much would you pay for this?"
Step 1.3: Problem Severity Scoring (End of Week 2)
Score each dimension (1-5):
| Dimension | 1 (Low) | 3 (Medium) | 5 (High) |
|---|---|---|---|
| Frequency | Rarely | Monthly | Daily/Weekly |
| Impact | Minor annoyance | Wastes 1-2 hours | Critical blocker |
| Urgency | Can wait | Should fix eventually | Need it now |
| Willingness to Pay | Won't pay | Might pay $5-20/mo | Will pay $50+/mo |
| Current Workarounds | Works fine | Tolerable | Painful/expensive |
Decision Rule:
- Score 20-25 (4-5 High dimensions) → ✅ BUILD IT - Problem validated
- Score 12-19 (2-3 High dimensions) → ⚠️ VALIDATE SOLUTION - Problem exists, test solution
- Score 5-11 (0-1 High dimensions) → ❌ DON'T BUILD - Problem not severe enough
Validation Gate 1: Problem Discovery
Before moving to Phase 2, confirm:
- 10+ customer discovery interviews completed
- Problem severity score ≥ 12 (2+ High dimensions)
- Current workarounds documented and evaluated
- Willingness to pay signals collected
- 70%+ of interviewees confirm problem is real
If gate not passed: STOP - Problem not validated. Pivot or abandon.
If gate passed: Move to Phase 2 (Solution Validation)
Phase 2: Solution Validation (Day 1-3)
Goal: Test that your solution actually solves the problem
⏰ Time Limit: 3 days - Don't spend weeks on this
Choose ONE Validation Method
Method 1: Landing Page Test (Fastest - 1-2 days)
Steps:
- Create single-page site describing solution
- Add "Sign up for early access" email form
- Drive 100-500 visitors (ads, social, outreach)
- Success: >5% conversion to email signup
Cost: $50-100 in ads Time: 1-2 days Tools: Carrd ($19/year), Mailchimp (free), Google Ads ($50-100)
Method 2: Concierge MVP (1 week)
Steps:
- Manually deliver solution to 5-10 early customers
- Do everything by hand (no automation)
- Walk them through process yourself
- Success: Users achieve outcome and ask for more
Cost: $0-50 Time: 1 week Example: Food delivery → Take orders via WhatsApp, deliver yourself
Method 3: Wizard of Oz MVP (1-2 weeks)
Steps:
- Build front-end UI only
- Handle all requests manually behind the scenes
- Users think it's automated
- Success: Users continue using despite imperfections
Cost: $0-100 Time: 1-2 weeks Example: AI chatbot → Human answers, customer thinks it's AI
Method 4: Prototype Testing (3-5 days)
Steps:
- Create clickable prototype (Figma, InVision)
- Show to 10-15 target users
- Watch them attempt key tasks WITHOUT help
- Success: >70% complete core tasks without guidance
Cost: $0 Time: 3-5 days Tools: Figma (free), Maze for testing ($0-25)
Validation Gate 2: Solution Validation
Before moving to Phase 3, confirm:
- Solution tested with prototype or MVP
- 50%+ of testers say they'd use/pay for it
- Users achieve desired outcome
- Must-have features identified
- Pricing expectations validated
If gate not passed: STOP - Solution doesn't work. Redesign or abandon.
If gate passed: Move to Phase 3 (MVP Build)
Phase 3: MVP Build & Test (Week 1-2)
Goal: Build minimum viable product to test with real users
⏰ Time Limit: 2 weeks MAX - If taking longer, scope is too big
MVP Scope Definition
Use P0/P1/P2 Matrix:
| Priority | Definition | Action |
|---|---|---|
| P0 | Must have for core value proposition | Build now (this sprint) |
| P1 | Important but can wait | Ship after validation |
| P2 | Nice to have | Ship v2+ |
| Out of Scope | Not needed for validation | Defer indefinitely |
Example: Task Management MVP
P0 (Week 1):
- Create task with title
- Mark task complete
- View task list
- Basic auth (email/password)
P1 (After validation):
- Due dates
- Priorities
- Reminders
P2 (Future):
- Team collaboration
- File attachments
- Mobile app
Out of Scope:
- Gantt charts
- Time tracking
- Integrations
Implementation Checklist
Week 1:
- Set up minimal infrastructure (Vercel + Supabase OR Replit)
- Build P0 features only (resist scope creep!)
- No styling beyond basic CSS (ugly is fine for MVP)
- No optimization (performance can wait)
- Deploy to production
Week 2:
- Get 10-20 users testing
- Fix critical bugs only
- Collect usage data
- Do user interviews
- Measure key metrics
Cost Budget
MVP Budget (max):
- Infrastructure: $0-50/month (Vercel free + Supabase free tier)
- Tools: $0-30/month (Figma, analytics)
- Total: <$100/month, <$200 total
If you're spending more: Your scope is too big. Cut features.
Validation Gate 3: MVP Validation
After 2 weeks with MVP, measure:
- 10+ real users testing
- ≥40% retention (users return after first use)
- ≥30% weekly active (users use at least weekly)
- Positive feedback (users say they'd pay)
- Core use case validated (users achieve goal)
If gate not passed: STOP - Users don't love it. Pivot or improve core value prop.
If gate passed: Move to Phase 4 (Validated Learning)
Phase 4: Validated Learning (Ongoing)
Goal: Systematically test assumptions and improve product
Duration: Ongoing until Phase 5 decision point
Set Up Metrics
Track:
- Acquisition: How many users sign up?
- Activation: How many complete first key action?
- Retention: How many come back after 1 week? 1 month?
- Revenue: How many pay? Average revenue per user?
- Referral: How many invite others?
Weekly Learning Cycles
Every week:
- Identify biggest unknown/risk
- Design cheapest test to validate/invalidate
- Run test
- Analyze results
- Update strategy
- Repeat
Cost Control
Spending limits:
- Infrastructure: <$200/month
- Marketing: <$500/month
- Total: <$1000/month
If approaching limits: Time to decide (Phase 5) - scale or stop
Validation Gate 4: Validated Learning
Before Phase 5, you need:
- 3+ months of usage data
- 100+ active users
- Retention >40% (monthly)
- Clear understanding of unit economics
- Positive trend in key metrics
- Users willing to pay (even if not charging yet)
If gate not passed: Keep iterating or STOP (see "Kill Criteria" below)
If gate passed: Move to Phase 5 (Scale Decision)
Phase 5: Scale Decision
Goal: Decide whether to scale up or wind down
⚠️ DO NOT PROCEED WITHOUT VALIDATION GATES 1-4 COMPLETE
Scale Decision Matrix
Scale UP if:
- ✅ Retention >40% monthly
- ✅ Users actively using product weekly
- ✅ Positive word of mouth / referrals
- ✅ Revenue (or validated willingness to pay)
- ✅ Unit economics work (LTV > 3x CAC)
- ✅ Market opportunity >$10M SOM
- ✅ Team capable of executing scale plan
Keep iterating if:
- ⚠️ Some metrics good, some not yet
- ⚠️ Users like it but not using regularly
- ⚠️ Core value prop needs refinement
- ⚠️ Monetization not yet validated
Wind down if (Kill Criteria):
- ❌ <30% retention after 6 months
- ❌ Users not using product regularly
- ❌ No one willing to pay after 6 months
- ❌ Better alternatives exist
- ❌ Market too small (<$1M SOM)
- ❌ Burned through 6 months without traction
If Scaling: Then What?
NOW you can:
- ✅ Build robust infrastructure
- ✅ Implement full feature set
- ✅ Optimize performance
- ✅ Scale team
- ✅ Increase marketing spend
- ✅ Use technical skills: api-designer, frontend-builder, deployment-advisor
Before scaling checklist:
- Validation Gates 1-4 passed
- Product-market fit confirmed
- Unit economics understood
- Growth channels validated
- Team ready to execute
🚨 Warning Signs: Analysis Paralysis
STOP and move forward if:
Research Phase (>2 weeks)
- You've been researching for >2 weeks
- You're analyzing competitors for >1 week
- You're creating detailed specs without talking to users
- Action: STOP researching. Move to customer interviews.
Design Phase (>3 days without code)
- You're designing architecture for >3 days
- You're choosing tech stack for >2 days
- You're planning perfect database schema
- Action: STOP designing. Build simplest version. Learn from implementation.
Validation Phase (>2 weeks)
- You're perfecting landing page for >3 days
- You're building "better" prototype for >1 week
- You're waiting for "more data" for >2 weeks
- Action: STOP perfecting. Ship what you have. Get real feedback.
Implementation Phase (>2 weeks for MVP)
- MVP is taking >2 weeks
- You're adding "just one more feature"
- You're optimizing before anyone uses it
- Action: STOP building. Cut scope by 50%. Ship NOW.
💰 Cost Reality Check
Validation Costs (Phase 1-2)
| Method | Time | Cost | Learning |
|---|---|---|---|
| Customer interviews | 1-2 weeks | $0 | Problem validation |
| Landing page | 1-2 days | $50-100 | Demand validation |
| Concierge MVP | 1 week | $0 | Solution validation |
| Prototype test | 3-5 days | $0 | Usability validation |
Total validation: 2-4 weeks, $0-200
Building Without Validation
| Approach | Time | Cost | Risk |
|---|---|---|---|
| Full SaaS build | 4-8 weeks | $500-1500 | 80% fail |
| RAG system | 2-4 weeks | $200-600 | 70% unnecessary |
| Multi-agent | 3-6 weeks | $300-1000 | 75% overkill |
Average waste: 4-6 weeks, $400-800, 75% wrong solution
ROI Calculation
Cost of validation: 2-4 weeks, $100-300 Cost of building wrong thing: 6-12 weeks, $500-1500 Success rate with validation: 60% (vs 20% without)
Expected savings per project: 4-8 weeks, $400-1200
📋 Checklists
Project Start Checklist
Before writing ANY code:
- Problem hypothesis defined
- 10+ customer discovery interviews scheduled
- Mom Test questions prepared
- Problem severity matrix ready
- Validation method chosen (landing page, concierge, etc.)
Before Building MVP
- Problem validated (Validation Gate 1 passed)
- Solution validated (Validation Gate 2 passed)
- P0/P1/P2 features defined
- MVP scope ≤2 weeks of work
- Metrics defined
- User recruitment plan ready
Before Scaling
- All 4 validation gates passed
- 3+ months of data
- 100+ active users
- Retention >40%
- Unit economics positive
- Team ready to scale
🎯 Common Scenarios
Scenario 1: "I have a great idea for an app"
DON'T:
- ❌ Jump into coding
- ❌ Start with tech stack selection
- ❌ Build prototype to show friends
DO:
- ✅ Define problem hypothesis
- ✅ Interview 10-15 potential users
- ✅ Test with landing page
- ✅ Build only if validated
Scenario 2: "Users said they want feature X"
DON'T:
- ❌ Immediately build feature X
- ❌ Add to backlog without validation
- ❌ Trust verbal feedback alone
DO:
- ✅ Observe if they actually need it (do they have workaround?)
- ✅ Test with fake door (button that does nothing, see if clicked)
- ✅ Manual concierge delivery first
- ✅ Build only if they actually use it
Scenario 3: "I need AI/RAG for this project"
DON'T:
- ❌ Immediately set up vector database
- ❌ Start with complex RAG architecture
- ❌ Build before knowing if users want AI
DO:
- ✅ Test if users actually want AI-powered solution
- ✅ Try simple keyword search first
- ✅ Manual curation as concierge MVP
- ✅ Build RAG only if simple solutions don't work
Scenario 4: "I'm stuck analyzing competitors"
STOP signal: You've been researching for >1 week
Action:
- Pick top 2-3 competitors only
- Document their 3 main strengths/weaknesses
- Define your 1-2 key differentiators
- STOP researching
- Move to customer validation
📚 Related Resources
Skills to use:
- product-strategist - Detailed validation methodology
- mvp-builder - MVP patterns and prioritization
- user-researcher - Interview techniques
Skills to avoid until validated:
- ⚠️ api-designer (until solution validated)
- ⚠️ frontend-builder (until MVP validated)
- ⚠️ deployment-advisor (until scaling)
- ⚠️ rag-implementer (until you know you need RAG)
- ⚠️ multi-agent-architect (until you know you need agents)
Other playbooks:
avoid-analysis-paralysis.md- Time limits and triggersdeployment-checklist.md- When ready to scale
🎓 Key Takeaways
- Validate problems before solutions - Don't assume you know what users need
- Validate solutions before building - Test with cheapest method possible
- Build minimum to learn maximum - Every line of code has carrying cost
- Set time limits - 2 weeks discovery, 3 days validation, 2 weeks MVP
- Track validation gates - Don't skip phases
- Cost discipline - <$200 to validate, <$1000/month before scaling
- Kill quickly - If not working after 6 months, stop
✅ Success Criteria
You're doing it right if:
- ✅ Talked to 10+ users before writing code
- ✅ Tested with landing page or concierge before building
- ✅ MVP took <2 weeks and cost <$200
- ✅ Have usage metrics from real users
- ✅ Can explain why users care about your product (not why you think they should)
- ✅ Pivoted or stopped 1-2 ideas before finding one that works
You're doing it wrong if:
- ❌ Building for >2 weeks without users
- ❌ Spent >$500 before validation
- ❌ Haven't talked to users yet
- ❌ Researching for >2 weeks
- ❌ Optimizing before anyone uses it
- ❌ Can't articulate why users care
Remember: The best code is no code. Validate first, build later.