@girardmedia/bootspring 1.2.0 → 2.0.3

package/intelligence/learning/pattern-learner.js

@@ -29,6 +29,523 @@ const CONFIDENCE_LEVELS = {
   VERY_LOW: 0.1
 };
 
+/**
+ * Minimum decisions required before transitioning away from cold-start defaults
+ */
+const COLD_START_THRESHOLD = 5;
+
+/**
+ * Thresholds for blending default and learned patterns
+ */
+const BLEND_THRESHOLDS = {
+  FULL_DEFAULTS: 2,      // 0-2 decisions: use 100% defaults
+  HEAVY_DEFAULTS: 5,     // 3-5 decisions: 75% defaults, 25% learned
+  BALANCED: 10,          // 6-10 decisions: 50% defaults, 50% learned
+  HEAVY_LEARNED: 20,     // 11-20 decisions: 25% defaults, 75% learned
+  FULL_LEARNED: 21       // 21+ decisions: use 100% learned (defaults as fallback only)
+};
+
+/**
+ * Default patterns for cold start - comprehensive best practices
+ * These provide sensible recommendations when no history exists
+ */
+const DEFAULT_PATTERNS = {
+  insights: [
+    {
+      type: 'cold_start',
+      subject: 'general',
+      message: 'Using industry best practices until learning data accumulates',
+      level: 'info',
+      confidence: CONFIDENCE_LEVELS.MEDIUM
+    },
+    {
+      type: 'cold_start',
+      subject: 'data_collection',
+      message: `Recommendations will improve significantly after ${COLD_START_THRESHOLD} recorded decisions`,
+      level: 'info',
+      confidence: CONFIDENCE_LEVELS.MEDIUM
+    }
+  ],
+
+  /**
+   * Scenario-based patterns for common development tasks
+   */
+  scenarios: {
+    // New feature development patterns
+    new_feature: {
+      name: 'New Feature Development',
+      steps: [
+        'Define acceptance criteria before coding',
+        'Break feature into small, testable increments',
+        'Write tests for core functionality first',
+        'Implement happy path, then edge cases',
+        'Document API changes and user-facing behavior'
+      ],
+      common_pitfalls: [
+        'Starting without clear requirements',
+        'Building too much before getting feedback',
+        'Skipping tests for "simple" features'
+      ],
+      success_indicators: [
+        'All acceptance criteria met',
+        'Tests passing and covering edge cases',
+        'Code reviewed and approved'
+      ],
+      confidence: CONFIDENCE_LEVELS.HIGH,
+      is_default: true
+    },
+
+    // Bug fix patterns
+    bug_fix: {
+      name: 'Bug Fix',
+      steps: [
+        'Reproduce the bug reliably first',
+        'Write a failing test that demonstrates the bug',
+        'Identify root cause before implementing fix',
+        'Fix the root cause, not just symptoms',
+        'Verify fix resolves original issue without regressions'
+      ],
+      common_pitfalls: [
+        'Fixing symptoms instead of root cause',
+        'Not writing a regression test',
+        'Rushing fix without understanding impact'
+      ],
+      success_indicators: [
+        'Bug no longer reproducible',
+        'Regression test added and passing',
+        'No new issues introduced'
+      ],
+      confidence: CONFIDENCE_LEVELS.HIGH,
+      is_default: true
+    },
+
+    // Refactoring patterns
+    refactoring: {
+      name: 'Code Refactoring',
+      steps: [
+        'Ensure comprehensive test coverage exists first',
+        'Make small, incremental changes',
+        'Run tests after each change',
+        'Keep refactoring separate from feature changes',
+        'Document architectural decisions'
+      ],
+      common_pitfalls: [
+        'Refactoring without test coverage',
+        'Combining refactoring with feature work',
+        'Making too many changes at once'
+      ],
+      success_indicators: [
+        'All existing tests still pass',
+        'Code metrics improved (complexity, duplication)',
+        'No behavior changes introduced'
+      ],
+      confidence: CONFIDENCE_LEVELS.HIGH,
+      is_default: true
+    },
+
+    // Testing patterns
+    testing: {
+      name: 'Writing Tests',
+      steps: [
+        'Identify critical paths and edge cases',
+        'Write unit tests for isolated logic',
+        'Write integration tests for component interactions',
+        'Mock external dependencies consistently',
+        'Aim for meaningful coverage, not 100% coverage'
+      ],
+      common_pitfalls: [
+        'Testing implementation details instead of behavior',
+        'Brittle tests that break on refactoring',
+        'Ignoring edge cases and error paths'
+      ],
+      success_indicators: [
+        'Tests are reliable and not flaky',
+        'Tests run quickly (unit tests < 10s)',
+        'Tests catch real bugs during development'
+      ],
+      confidence: CONFIDENCE_LEVELS.HIGH,
+      is_default: true
+    },
+
+    // Database changes patterns
+    database_migration: {
+      name: 'Database Migration',
+      steps: [
+        'Plan migration with rollback strategy',
+        'Test migration on copy of production data',
+        'Make migrations backward compatible when possible',
+        'Deploy migration before code that depends on it',
+        'Monitor for performance issues after deployment'
+      ],
+      common_pitfalls: [
+        'No rollback plan',
+        'Locking tables during high-traffic periods',
+        'Deploying dependent code before migration completes'
+      ],
+      success_indicators: [
+        'Migration completes without errors',
+        'Application continues working during migration',
+        'Rollback tested and working'
+      ],
+      confidence: CONFIDENCE_LEVELS.HIGH,
+      is_default: true
+    },
+
+    // API development patterns
+    api_development: {
+      name: 'API Development',
+      steps: [
+        'Design API contract before implementation',
+        'Validate all inputs at the boundary',
+        'Return consistent error formats',
+        'Version APIs for breaking changes',
+        'Document endpoints with examples'
+      ],
+      common_pitfalls: [
+        'Inconsistent error handling',
+        'Missing input validation',
+        'Breaking changes without versioning'
+      ],
+      success_indicators: [
+        'Clear and consistent API contract',
+        'Comprehensive error handling',
+        'Documentation up to date'
+      ],
+      confidence: CONFIDENCE_LEVELS.HIGH,
+      is_default: true
+    },
+
+    // Performance optimization patterns
+    performance: {
+      name: 'Performance Optimization',
+      steps: [
+        'Measure before optimizing - establish baseline',
+        'Identify bottleneck using profiling tools',
+        'Focus on the biggest impact first',
+        'Measure after each change',
+        'Document performance requirements and results'
+      ],
+      common_pitfalls: [
+        'Optimizing without measuring',
+        'Premature optimization',
+        'Optimizing non-bottlenecks'
+      ],
+      success_indicators: [
+        'Measurable performance improvement',
+        'No functionality regressions',
+        'Performance requirements documented and met'
+      ],
+      confidence: CONFIDENCE_LEVELS.MEDIUM,
+      is_default: true
+    },
+
+    // Security implementation patterns
+    security: {
+      name: 'Security Implementation',
+      steps: [
+        'Validate and sanitize all user inputs',
+        'Use parameterized queries for database access',
+        'Implement proper authentication and authorization',
+        'Store secrets in environment variables or vaults',
+        'Log security events without exposing sensitive data'
+      ],
+      common_pitfalls: [
+        'Trusting user input',
+        'Hardcoding secrets',
+        'Logging sensitive information'
+      ],
+      success_indicators: [
+        'Passes security review/scan',
+        'No secrets in codebase',
+        'Proper access controls in place'
+      ],
+      confidence: CONFIDENCE_LEVELS.VERY_HIGH,
+      is_default: true
+    }
+  },
+
+  recommendations: {
+    by_type: {
+      'database': {
+        success_rate: 0.8,
+        recommendation: 'Use migrations for schema changes, write tests for queries',
+        sample_size: 0,
+        is_default: true,
+        tips: [
+          'Always create rollback migrations',
+          'Test with production-like data volumes',
+          'Index columns used in WHERE clauses'
+        ]
+      },
+      'api': {
+        success_rate: 0.75,
+        recommendation: 'Document endpoints, validate inputs, handle errors consistently',
+        sample_size: 0,
+        is_default: true,
+        tips: [
+          'Use OpenAPI/Swagger for documentation',
+          'Return appropriate HTTP status codes',
+          'Include request IDs for debugging'
+        ]
+      },
+      'ui': {
+        success_rate: 0.7,
+        recommendation: 'Start with mobile-first design, use design system components',
+        sample_size: 0,
+        is_default: true,
+        tips: [
+          'Test on real devices, not just emulators',
+          'Consider accessibility from the start',
+          'Use semantic HTML elements'
+        ]
+      },
+      'testing': {
+        success_rate: 0.85,
+        recommendation: 'Write tests for critical paths first, mock external services',
+        sample_size: 0,
+        is_default: true,
+        tips: [
+          'Use factories for test data',
+          'Keep tests independent and isolated',
+          'Test behavior, not implementation'
+        ]
+      },
+      'security': {
+        success_rate: 0.9,
+        recommendation: 'Never store secrets in code, validate all inputs, use prepared statements',
+        sample_size: 0,
+        is_default: true,
+        tips: [
+          'Use environment variables for configuration',
+          'Implement rate limiting on public endpoints',
+          'Keep dependencies updated'
+        ]
+      },
+      'architecture': {
+        success_rate: 0.65,
+        recommendation: 'Start simple, refactor when patterns emerge, document decisions',
+        sample_size: 0,
+        is_default: true,
+        tips: [
+          'Use ADRs (Architecture Decision Records)',
+          'Prefer composition over inheritance',
+          'Keep components loosely coupled'
+        ]
+      },
+      'feature': {
+        success_rate: 0.75,
+        recommendation: 'Break into small increments, define acceptance criteria, get early feedback',
+        sample_size: 0,
+        is_default: true,
+        tips: [
+          'Ship MVPs and iterate',
+          'Use feature flags for gradual rollout',
+          'Track metrics to measure success'
+        ]
+      },
+      'bugfix': {
+        success_rate: 0.8,
+        recommendation: 'Write failing test first, fix root cause, verify no regressions',
+        sample_size: 0,
+        is_default: true,
+        tips: [
+          'Understand the bug before fixing',
+          'Check for similar issues elsewhere',
+          'Update documentation if behavior was unclear'
+        ]
+      },
+      'refactoring': {
+        success_rate: 0.7,
+        recommendation: 'Ensure test coverage, make small changes, keep separate from features',
+        sample_size: 0,
+        is_default: true,
+        tips: [
+          'Use IDE refactoring tools when available',
+          'Commit frequently during refactoring',
+          'Review changes in small batches'
+        ]
+      },
+      'performance': {
+        success_rate: 0.65,
+        recommendation: 'Measure first, optimize bottlenecks, measure again',
+        sample_size: 0,
+        is_default: true,
+        tips: [
+          'Set performance budgets upfront',
+          'Profile in production-like environments',
+          'Consider caching strategies'
+        ]
+      },
+      'deployment': {
+        success_rate: 0.75,
+        recommendation: 'Use staging environment, implement health checks, have rollback plan',
+        sample_size: 0,
+        is_default: true,
+        tips: [
+          'Automate deployments',
+          'Use blue-green or canary deployments',
+          'Monitor error rates after deploy'
+        ]
+      },
+      'documentation': {
+        success_rate: 0.8,
+        recommendation: 'Keep docs close to code, include examples, update during changes',
+        sample_size: 0,
+        is_default: true,
+        tips: [
+          'Use inline comments for "why", not "what"',
+          'Include runnable code examples',
+          'Document breaking changes prominently'
+        ]
+      }
+    },
+    by_phase: {
+      'planning': {
+        success_rate: 0.8,
+        recommendation: 'Break large features into small stories, define acceptance criteria',
+        sample_size: 0,
+        is_default: true,
+        tips: [
+          'Include technical spike time for unknowns',
+          'Define "done" criteria upfront',
+          'Identify dependencies early'
+        ]
+      },
+      'development': {
+        success_rate: 0.75,
+        recommendation: 'Commit early and often, write tests alongside code',
+        sample_size: 0,
+        is_default: true,
+        tips: [
+          'Use meaningful commit messages',
+          'Keep pull requests small and focused',
+          'Request reviews early for big changes'
+        ]
+      },
+      'testing': {
+        success_rate: 0.85,
+        recommendation: 'Automate tests, test edge cases, verify in staging',
+        sample_size: 0,
+        is_default: true,
+        tips: [
+          'Include both happy path and error cases',
+          'Test with realistic data',
+          'Run security scans in CI'
+        ]
+      },
+      'deployment': {
+        success_rate: 0.7,
+        recommendation: 'Use feature flags, deploy to staging first, monitor closely',
+        sample_size: 0,
+        is_default: true,
+        tips: [
+          'Have runbooks for common issues',
+          'Set up alerting before deploying',
+          'Deploy during low-traffic periods for risky changes'
+        ]
+      },
+      'maintenance': {
+        success_rate: 0.8,
+        recommendation: 'Keep dependencies updated, monitor for issues, document learnings',
+        sample_size: 0,
+        is_default: true,
+        tips: [
+          'Schedule regular dependency updates',
+          'Review and clean up technical debt',
+          'Archive unused code rather than commenting out'
+        ]
+      }
+    },
+    general: [
+      {
+        priority: 'medium',
+        message: 'Building your decision history - recommendations will improve with more data',
+        action: 'Continue making decisions and recording outcomes'
+      },
+      {
+        priority: 'low',
+        message: 'Record outcomes for decisions to help the system learn',
+        action: 'Use decision tracker to mark decisions as success, failure, or reverted'
+      }
+    ]
+  },
+  anti_patterns: [
+    {
+      type: 'security',
+      decision: 'hardcoded_secrets',
+      failure_rate: 1.0,
+      occurrences: 0,
+      recommendation: 'AVOID',
+      message: 'Never hardcode API keys, passwords, or secrets in source code',
+      is_default: true
+    },
+    {
+      type: 'database',
+      decision: 'no_migrations',
+      failure_rate: 0.8,
+      occurrences: 0,
+      recommendation: 'AVOID',
+      message: 'Always use migrations for schema changes, avoid direct DB modifications',
+      is_default: true
+    },
+    {
+      type: 'deployment',
+      decision: 'direct_to_production',
+      failure_rate: 0.7,
+      occurrences: 0,
+      recommendation: 'AVOID',
+      message: 'Deploy to staging first, test thoroughly before production',
+      is_default: true
+    },
+    {
+      type: 'testing',
+      decision: 'skip_tests_for_deadline',
+      failure_rate: 0.75,
+      occurrences: 0,
+      recommendation: 'AVOID',
+      message: 'Skipping tests to meet deadlines often leads to bugs and longer timelines',
+      is_default: true
+    },
+    {
+      type: 'refactoring',
+      decision: 'big_bang_refactor',
+      failure_rate: 0.65,
+      occurrences: 0,
+      recommendation: 'AVOID',
+      message: 'Large refactors without tests are risky - prefer incremental changes',
+      is_default: true
+    },
+    {
+      type: 'feature',
+      decision: 'no_requirements',
+      failure_rate: 0.6,
+      occurrences: 0,
+      recommendation: 'AVOID',
+      message: 'Starting development without clear requirements leads to rework',
+      is_default: true
+    },
+    {
+      type: 'architecture',
+      decision: 'premature_optimization',
+      failure_rate: 0.5,
+      occurrences: 0,
+      recommendation: 'CAUTION',
+      message: 'Optimizing before measuring often wastes effort on non-bottlenecks',
+      is_default: true
+    },
+    {
+      type: 'api',
+      decision: 'breaking_change_no_version',
+      failure_rate: 0.8,
+      occurrences: 0,
+      recommendation: 'AVOID',
+      message: 'Breaking API changes without versioning breaks existing clients',
+      is_default: true
+    }
+  ],
+  correlations: []
+};
+
 /**
  * Ensure insights file exists
  */
@@ -59,13 +576,9 @@ function analyze() {
   const decisions = decisionTracker.readAllDecisions();
   const completedDecisions = decisions.filter(d => d.outcome);
 
-  if (completedDecisions.length < 5) {
-    return {
-      status: 'insufficient_data',
-      decisions_needed: 5 - completedDecisions.length,
-      message: `Need ${5 - completedDecisions.length} more completed decisions for analysis`
-    };
-  }
+  // Calculate blend ratio based on completed decisions
+  const blendRatio = calculateBlendRatio(completedDecisions.length);
+  const useDefaults = completedDecisions.length < COLD_START_THRESHOLD;
 
   ensureInsightsFile();
   const insightsData = JSON.parse(fs.readFileSync(insightsFile, 'utf-8'));
@@ -96,17 +609,33 @@ function analyze() {
 
   // Update insights file
   insightsData.last_analysis = new Date().toISOString();
-  insightsData.insights = insights;
-  insightsData.correlations = correlations;
-  insightsData.anti_patterns = antiPatterns;
-  insightsData.recommendations = recommendations;
+
+  // Blend defaults with learned patterns based on data available
+  const blendedData = blendPatterns(
+    { insights, recommendations, antiPatterns, correlations },
+    DEFAULT_PATTERNS,
+    blendRatio,
+    completedDecisions.length
+  );
+
+  insightsData.insights = blendedData.insights;
+  insightsData.recommendations = blendedData.recommendations;
+  insightsData.anti_patterns = blendedData.antiPatterns;
+  insightsData.correlations = blendedData.correlations;
+  insightsData.scenarios = DEFAULT_PATTERNS.scenarios; // Always include scenarios
+  insightsData.using_defaults = useDefaults;
+  insightsData.blend_ratio = blendRatio;
+
   insightsData.analysis_summary = {
     total_decisions: decisions.length,
     completed_decisions: completedDecisions.length,
     success_rate: calculateOverallSuccessRate(completedDecisions),
     top_performing_type: typeStats.top_type,
-    patterns_found: insights.length,
-    anti_patterns_found: antiPatterns.length
+    patterns_found: insightsData.insights.length,
+    anti_patterns_found: insightsData.anti_patterns.length,
+    using_defaults: useDefaults,
+    blend_ratio: blendRatio,
+    decisions_until_full_learning: Math.max(0, BLEND_THRESHOLDS.FULL_LEARNED - completedDecisions.length)
   };
 
   fs.writeFileSync(insightsFile, JSON.stringify(insightsData, null, 2));
@@ -114,6 +643,232 @@ function analyze() {
   return insightsData;
 }
 
+/**
+ * Calculate blend ratio between default and learned patterns
+ * Returns object with defaultWeight and learnedWeight (0-1)
+ */
+function calculateBlendRatio(completedDecisions) {
+  if (completedDecisions <= BLEND_THRESHOLDS.FULL_DEFAULTS) {
+    return { defaultWeight: 1.0, learnedWeight: 0.0, phase: 'cold_start' };
+  }
+  if (completedDecisions <= BLEND_THRESHOLDS.HEAVY_DEFAULTS) {
+    return { defaultWeight: 0.75, learnedWeight: 0.25, phase: 'early_learning' };
+  }
+  if (completedDecisions <= BLEND_THRESHOLDS.BALANCED) {
+    return { defaultWeight: 0.5, learnedWeight: 0.5, phase: 'balanced' };
+  }
+  if (completedDecisions <= BLEND_THRESHOLDS.HEAVY_LEARNED) {
+    return { defaultWeight: 0.25, learnedWeight: 0.75, phase: 'maturing' };
+  }
+  return { defaultWeight: 0.0, learnedWeight: 1.0, phase: 'mature' };
+}
+
+/**
+ * Blend learned patterns with defaults based on blend ratio
+ */
+function blendPatterns(learned, defaults, blendRatio, decisionCount) {
+  const { defaultWeight, learnedWeight } = blendRatio;
+
+  // Insights: Include defaults during cold start, then fade them out
+  let insights = [...learned.insights];
+  if (defaultWeight > 0) {
+    const defaultInsights = defaults.insights.map(i => ({
+      ...i,
+      weight: defaultWeight,
+      is_default: true
+    }));
+    insights = [...defaultInsights, ...insights];
+  }
+
+  // Recommendations: Blend by_type and by_phase
+  const recommendations = {
+    by_type: blendRecommendationsByType(
+      learned.recommendations.by_type || {},
+      defaults.recommendations.by_type,
+      blendRatio
+    ),
+    by_phase: blendRecommendationsByPhase(
+      learned.recommendations.by_phase || {},
+      defaults.recommendations.by_phase,
+      blendRatio
+    ),
+    general: blendGeneralRecommendations(
+      learned.recommendations.general || [],
+      defaults.recommendations.general,
+      decisionCount
+    )
+  };
+
+  // Anti-patterns: Include all defaults, learned can override
+  const antiPatterns = blendAntiPatterns(
+    learned.antiPatterns,
+    defaults.anti_patterns,
+    blendRatio
+  );
+
+  // Correlations: Only use learned (no default correlations)
+  const correlations = learned.correlations;
+
+  return { insights, recommendations, antiPatterns, correlations };
+}
+
+/**
+ * Blend recommendations by type
+ */
+function blendRecommendationsByType(learned, defaults, blendRatio) {
+  const result = {};
+
+  // Start with defaults
+  Object.entries(defaults).forEach(([type, defaultRec]) => {
+    const learnedRec = learned[type];
+
+    if (learnedRec && learnedRec.sample_size >= 3) {
+      // Learned data is reliable enough - blend success rates
+      const blendedSuccessRate =
+        (defaultRec.success_rate * blendRatio.defaultWeight) +
+        (learnedRec.success_rate * blendRatio.learnedWeight);
+
+      result[type] = {
+        success_rate: parseFloat(blendedSuccessRate.toFixed(2)),
+        recommendation: learnedRec.recommendation,
+        sample_size: learnedRec.sample_size,
+        is_default: false,
+        tips: defaultRec.tips, // Always keep tips from defaults
+        default_success_rate: defaultRec.success_rate,
+        learned_success_rate: learnedRec.success_rate
+      };
+    } else if (learnedRec) {
+      // Some learned data but not enough - weight heavily toward defaults
+      result[type] = {
+        ...defaultRec,
+        sample_size: learnedRec.sample_size,
+        learning_in_progress: true
+      };
+    } else {
+      // No learned data - use defaults
+      result[type] = { ...defaultRec };
+    }
+  });
+
+  // Add any learned types not in defaults
+  Object.entries(learned).forEach(([type, learnedRec]) => {
+    if (!result[type]) {
+      result[type] = {
+        ...learnedRec,
+        is_default: false
+      };
+    }
+  });
+
+  return result;
+}
+
+/**
+ * Blend recommendations by phase
+ */
+function blendRecommendationsByPhase(learned, defaults, blendRatio) {
+  const result = {};
+
+  // Same logic as by_type
+  Object.entries(defaults).forEach(([phase, defaultRec]) => {
+    const learnedRec = learned[phase];
+
+    if (learnedRec && learnedRec.sample_size >= 3) {
+      const blendedSuccessRate =
+        (defaultRec.success_rate * blendRatio.defaultWeight) +
+        (learnedRec.success_rate * blendRatio.learnedWeight);
+
+      result[phase] = {
+        success_rate: parseFloat(blendedSuccessRate.toFixed(2)),
+        recommendation: learnedRec.recommendation,
+        sample_size: learnedRec.sample_size,
+        is_default: false,
+        tips: defaultRec.tips,
+        default_success_rate: defaultRec.success_rate,
+        learned_success_rate: learnedRec.success_rate
+      };
+    } else if (learnedRec) {
+      result[phase] = {
+        ...defaultRec,
+        sample_size: learnedRec.sample_size,
+        learning_in_progress: true
+      };
+    } else {
+      result[phase] = { ...defaultRec };
+    }
+  });
+
+  Object.entries(learned).forEach(([phase, learnedRec]) => {
+    if (!result[phase]) {
+      result[phase] = {
+        ...learnedRec,
+        is_default: false
+      };
+    }
+  });
+
+  return result;
+}
+
+/**
+ * Blend general recommendations
+ */
+function blendGeneralRecommendations(learned, defaults, decisionCount) {
+  const result = [];
+
+  // Add progress indicator based on decision count
+  if (decisionCount < BLEND_THRESHOLDS.FULL_LEARNED) {
+    result.push({
+      priority: 'info',
+      message: `Learning in progress: ${decisionCount}/${BLEND_THRESHOLDS.FULL_LEARNED} decisions recorded`,
+      action: 'Continue recording outcomes to improve recommendations',
+      progress: parseFloat((decisionCount / BLEND_THRESHOLDS.FULL_LEARNED).toFixed(2))
+    });
+  }
+
+  // Add defaults for cold start
+  if (decisionCount < COLD_START_THRESHOLD) {
+    result.push(...defaults);
+  }
+
+  // Add learned recommendations
+  result.push(...learned);
+
+  return result;
+}
+
+/**
+ * Blend anti-patterns
+ */
+function blendAntiPatterns(learned, defaults, blendRatio) {
+  const result = [];
+  const seenKeys = new Set();
+
+  // Add learned anti-patterns first (they take priority)
+  learned.forEach(ap => {
+    const key = `${ap.type}:${ap.decision}`;
+    seenKeys.add(key);
+    result.push({
+      ...ap,
+      is_default: false,
+      is_learned: true
+    });
+  });
+
+  // Add default anti-patterns that weren't overridden
+  defaults.forEach(ap => {
+    const key = `${ap.type}:${ap.decision}`;
+    if (!seenKeys.has(key)) {
+      result.push({
+        ...ap,
+        weight: blendRatio.defaultWeight
+      });
+    }
+  });
+
+  return result;
+}
+
 /**
  * Analyze decisions by type
  */
@@ -450,11 +1205,250 @@ function getAntiPatterns() {
   return insightsData.anti_patterns;
 }
 
+/**
+ * Get default patterns (for cold start or fallback)
+ */
+function getDefaults() {
+  return { ...DEFAULT_PATTERNS };
+}
+
+/**
+ * Get scenario-based pattern for a specific development task
+ * @param {string} scenario - The scenario name (e.g., 'new_feature', 'bug_fix')
+ * @returns {Object|null} Scenario pattern or null if not found
+ */
+function getScenario(scenario) {
+  const normalizedScenario = scenario.toLowerCase().replace(/[\s-]/g, '_');
+  const scenarioPattern = DEFAULT_PATTERNS.scenarios[normalizedScenario];
+
+  if (!scenarioPattern) {
+    // Try to find a partial match
+    const scenarios = Object.keys(DEFAULT_PATTERNS.scenarios);
+    const match = scenarios.find(s =>
+      s.includes(normalizedScenario) || normalizedScenario.includes(s)
+    );
+    return match ? DEFAULT_PATTERNS.scenarios[match] : null;
+  }
+
+  return scenarioPattern;
+}
+
+/**
+ * Get all available scenarios
+ * @returns {Object} All scenario patterns
+ */
+function getScenarios() {
+  return { ...DEFAULT_PATTERNS.scenarios };
+}
+
+/**
+ * Get pattern suggestions for a new project (cold start helper)
+ * Returns prioritized list of patterns for projects with no history
+ * @param {Object} context - Optional context about the project
+ * @returns {Object} Prioritized cold-start recommendations
+ */
+function getColdStartPatterns(context = {}) {
+  const patterns = {
+    immediate: [],    // Apply these right away
+    recommended: [],  // Highly recommended
+    optional: []      // Nice to have
+  };
+
+  // Security patterns are always immediate priority
+  patterns.immediate.push({
+    category: 'security',
+    pattern: DEFAULT_PATTERNS.scenarios.security,
+    recommendation: DEFAULT_PATTERNS.recommendations.by_type.security,
+    reason: 'Security should be built in from the start'
+  });
+
+  // Testing patterns are highly recommended
+  patterns.recommended.push({
+    category: 'testing',
+    pattern: DEFAULT_PATTERNS.scenarios.testing,
+    recommendation: DEFAULT_PATTERNS.recommendations.by_type.testing,
+    reason: 'Early testing reduces bugs and enables confident refactoring'
+  });
+
+  // Context-specific recommendations
+  if (context.hasDatabase) {
+    patterns.immediate.push({
+      category: 'database',
+      pattern: DEFAULT_PATTERNS.scenarios.database_migration,
+      recommendation: DEFAULT_PATTERNS.recommendations.by_type.database,
+      reason: 'Database changes need careful management from day one'
+    });
+  }
+
+  if (context.hasApi) {
+    patterns.recommended.push({
+      category: 'api',
+      pattern: DEFAULT_PATTERNS.scenarios.api_development,
+      recommendation: DEFAULT_PATTERNS.recommendations.by_type.api,
+      reason: 'Good API design prevents breaking changes later'
+    });
+  }
+
+  // Phase-based patterns
+  if (context.phase === 'planning') {
+    patterns.immediate.push({
+      category: 'planning',
+      recommendation: DEFAULT_PATTERNS.recommendations.by_phase.planning,
+      reason: 'Good planning prevents costly rework'
+    });
+  }
+
+  // Add general development patterns
+  patterns.recommended.push({
+    category: 'feature',
+    pattern: DEFAULT_PATTERNS.scenarios.new_feature,
+    recommendation: DEFAULT_PATTERNS.recommendations.by_type.feature,
+    reason: 'Structured feature development improves outcomes'
+  });
+
+  patterns.optional.push({
+    category: 'refactoring',
+    pattern: DEFAULT_PATTERNS.scenarios.refactoring,
+    recommendation: DEFAULT_PATTERNS.recommendations.by_type.refactoring,
+    reason: 'Refactoring practices help maintain code quality'
+  });
+
+  // Include relevant anti-patterns as warnings
+  patterns.warnings = DEFAULT_PATTERNS.anti_patterns.filter(ap =>
+    ['security', 'database', 'testing'].includes(ap.type)
+  );
+
+  return patterns;
+}
+
+/**
+ * Check if pattern learner has enough data for reliable recommendations
+ * @returns {Object} Status and details about learning progress
+ */
+function getLearningStatus() {
+  ensureInsightsFile();
+  const insightsData = JSON.parse(fs.readFileSync(insightsFile, 'utf-8'));
+  const summary = insightsData.analysis_summary || {};
+  const completedDecisions = summary.completed_decisions || 0;
+  const blendRatio = calculateBlendRatio(completedDecisions);
+
+  return {
+    phase: blendRatio.phase,
+    completedDecisions,
+    threshold: COLD_START_THRESHOLD,
+    isUsingDefaults: completedDecisions < COLD_START_THRESHOLD,
+    progress: {
+      toMinimum: Math.min(1, completedDecisions / COLD_START_THRESHOLD),
+      toFullLearning: Math.min(1, completedDecisions / BLEND_THRESHOLDS.FULL_LEARNED)
+    },
+    blendRatio,
+    message: getLearningStatusMessage(completedDecisions, blendRatio.phase)
+  };
+}
+
+/**
+ * Get human-readable learning status message
+ */
+function getLearningStatusMessage(decisionCount, phase) {
+  const messages = {
+    cold_start: `Cold start: Using default patterns. Record ${COLD_START_THRESHOLD - decisionCount} more decisions to start personalized learning.`,
+    early_learning: `Early learning: Blending defaults with ${decisionCount} recorded decisions.`,
+    balanced: `Balanced: Equal weight to defaults and learned patterns from ${decisionCount} decisions.`,
+    maturing: `Maturing: Recommendations primarily based on ${decisionCount} learned decisions.`,
+    mature: `Mature: Recommendations fully based on ${decisionCount} learned decisions.`
+  };
+  return messages[phase] || messages.cold_start;
+}
+
+/**
+ * Override or customize default patterns for a project
+ * Allows projects to provide their own baseline patterns
+ * @param {Object} customPatterns - Custom patterns to merge with defaults
+ * @returns {Object} Merged patterns
+ */
+function setProjectDefaults(customPatterns) {
+  // Deep merge custom patterns with defaults
+  const merged = {
+    insights: [
+      ...DEFAULT_PATTERNS.insights,
+      ...(customPatterns.insights || [])
+    ],
+    scenarios: {
+      ...DEFAULT_PATTERNS.scenarios,
+      ...(customPatterns.scenarios || {})
+    },
+    recommendations: {
+      by_type: {
+        ...DEFAULT_PATTERNS.recommendations.by_type,
+        ...(customPatterns.recommendations?.by_type || {})
+      },
+      by_phase: {
+        ...DEFAULT_PATTERNS.recommendations.by_phase,
+        ...(customPatterns.recommendations?.by_phase || {})
+      },
+      general: [
+        ...DEFAULT_PATTERNS.recommendations.general,
+        ...(customPatterns.recommendations?.general || [])
+      ]
+    },
+    anti_patterns: [
+      ...DEFAULT_PATTERNS.anti_patterns,
+      ...(customPatterns.anti_patterns || [])
+    ],
+    correlations: customPatterns.correlations || []
+  };
+
+  // Save to project-specific file if path provided
+  if (customPatterns.projectPath) {
+    const projectPatternsFile = path.join(
+      customPatterns.projectPath,
+      '.bootspring',
+      'custom-patterns.json'
+    );
+    const dir = path.dirname(projectPatternsFile);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+    fs.writeFileSync(projectPatternsFile, JSON.stringify(customPatterns, null, 2));
+  }
+
+  return merged;
+}
+
+/**
+ * Load project-specific custom patterns if they exist
+ * @param {string} projectPath - Path to the project root
+ * @returns {Object|null} Custom patterns or null
+ */
+function loadProjectDefaults(projectPath) {
+  const projectPatternsFile = path.join(projectPath, '.bootspring', 'custom-patterns.json');
+
+  if (fs.existsSync(projectPatternsFile)) {
+    try {
+      const customPatterns = JSON.parse(fs.readFileSync(projectPatternsFile, 'utf-8'));
+      return setProjectDefaults(customPatterns);
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}
+
 module.exports = {
   analyze,
   getSuggestions,
   getSummary,
   getInsights,
   getAntiPatterns,
-  CONFIDENCE_LEVELS
+  getDefaults,
+  getScenario,
+  getScenarios,
+  getColdStartPatterns,
+  getLearningStatus,
+  setProjectDefaults,
+  loadProjectDefaults,
+  CONFIDENCE_LEVELS,
+  DEFAULT_PATTERNS,
+  COLD_START_THRESHOLD,
+  BLEND_THRESHOLDS
 };