Skip to main content

ADR-006: Phased MVP Scope Reduction

Status: PROPOSED
Date: 2025-08-25
Author: Architecture Review Team

Context​

The current MVP scope includes:

  • Semantic analysis engine (4 layers)
  • Badge generation service
  • MCP integration for AI agents
  • Similarity search
  • Dashboard and customization
  • API access

This is not minimal - it's attempting to deliver the full vision in the first release, risking:

  • Extended development time beyond 6-8 week target
  • Quality compromises trying to deliver everything
  • Missing the market window
  • Overwhelming users with too many features

Decision​

AGGRESSIVELY REDUCE MVP SCOPE to core value proposition only

Phase 1 MVP (Weeks 1-4):

  • Static badge generation with basic semantic classification
  • GitHub OAuth and repository import
  • Simple dashboard (list view only)
  • One-click badge addition to README
  • Basic similarity (top 3 similar projects)

Phase 2 Enhancement (Weeks 5-8):

  • Advanced semantic analysis
  • Badge customization
  • Similarity search interface
  • Usage analytics

Phase 3 Monetization (Month 3):

  • MCP integration
  • API access
  • Pro features
  • Team functionality

Consequences​

Positive:

  • Can launch in 4 weeks instead of 8
  • Focus on validating core hypothesis
  • Higher quality on fewer features
  • Faster iteration based on user feedback
  • Reduced initial infrastructure costs

Negative:

  • May appear less differentiated initially
  • Delayed monetization opportunities
  • Risk of being perceived as "just another badge generator"
  • Competitive vulnerability during phased rollout

Alternatives Considered​

  1. Full Feature MVP (Current Plan)

    • Pros: Complete value proposition from day one
    • Cons: 8+ weeks development, quality risks, complexity

  2. Phased Rollout (RECOMMENDED)

    • Pros: Fast launch, iterative improvement, reduced risk
    • Cons: Incomplete initial offering, phased differentiation

  3. Badge-Only Launch

    • Pros: Could launch in 2 weeks
    • Cons: No differentiation, hard to add semantic value later

  4. API-First Launch

    • Pros: B2B monetization potential
    • Cons: No viral growth mechanism, longer sales cycle

Risk Assessment​

Risks of Current Full-Feature Approach:

  • Time Risk: 12+ weeks actual vs 8 weeks planned
  • Quality Risk: Bugs across many features
  • Complexity Risk: Too many moving parts for MVP
  • User Risk: Overwhelming experience

Risks of Phased Approach:

  • Competition Risk: Competitors could copy before full differentiation
  • Perception Risk: Initial users may not see full potential
  • Retention Risk: Users may not return for new features

Migration Strategy​

Week 1-2: Core Infrastructure

// Minimal viable architecture
const mvpStack = {
  frontend: 'Next.js + Shadcn/ui',
  auth: 'NextAuth.js (GitHub only)',
  database: 'PostgreSQL + Prisma',
  badges: 'badge-maker + CDN',
  analysis: 'Simple GPT-3.5 classification'
}

Week 3-4: MVP Features

  • Repository import flow
  • Basic semantic classification
  • Badge generation
  • Simple dashboard
  • README integration guide

Success Metrics for Phase 1:

  • 100 users in first week
  • 50% add badge to README
  • 20% click-through rate on badges
  • Clear demand signal for similarity features

Conclusion​

The current MVP scope is too ambitious for the timeline and risks. A phased approach allows faster validation of the core hypothesis while maintaining the ability to add differentiation based on user feedback. Launch with badges that show semantic intelligence, then expand based on what users actually value.