lean-claudient-core 0.1.0

package/src/automation/qualificationRules.ts

@@ -0,0 +1,304 @@
+/**
+ * Qualification Rules Engine
+ * Stage definitions, rule evaluators, and transition handlers for lead qualification
+ * Composable, testable rule system
+ */
+
+export type QualificationStage = 'cold' | 'warm' | 'hot' | 'sales-ready';
+
+export interface EnrichedLead {
+  id: string;
+  name: string;
+  email: string;
+  company?: string;
+  signalCount: number;
+  signals?: Array<{ type: string; strength: number }>;
+  competitorThreat: number; // 0-100
+  quality: number; // 0-100
+  enrichedAt?: string;
+  lastEnrichedAt?: string;
+}
+
+export interface RevenueProjection {
+  leadId: string;
+  projectedRevenue: number;
+  confidence: number; // 0-1
+  arpu?: number;
+  churnRisk?: number;
+}
+
+export interface QualificationResult {
+  leadId: string;
+  stage: QualificationStage;
+  confidence: number; // 0-1
+  nextAction?: string;
+  signals: string[];
+  blockers?: string[];
+}
+
+export interface StageTransition {
+  leadId: string;
+  fromStage: QualificationStage;
+  toStage: QualificationStage;
+  timestamp: string;
+  reason: string;
+  composioActionsQueued?: string[];
+}
+
+/**
+ * Stage Definitions with metadata and rules
+ */
+export const stageDefinitions: Record<QualificationStage, {
+  label: string;
+  description: string;
+  minQuality?: number;
+  minSignals?: number;
+  minRevenue?: number;
+  maxCompetitorThreat?: number;
+}> = {
+  cold: {
+    label: 'Cold',
+    description: 'New lead, no enrichment yet',
+  },
+  warm: {
+    label: 'Warm',
+    description: 'Market signals matched, low threat',
+    minSignals: 2,
+    minQuality: 40,
+    maxCompetitorThreat: 49,
+  },
+  hot: {
+    label: 'Hot',
+    description: 'Strong signals, active competitor threat',
+    minSignals: 3,
+    minQuality: 70,
+  },
+  'sales-ready': {
+    label: 'Sales-Ready',
+    description: 'Fully qualified, revenue validated',
+    minSignals: 3,
+    minQuality: 70,
+    minRevenue: 10000,
+  },
+};
+
+/**
+ * Cold Stage Rule: New lead, no enrichment yet
+ */
+export function isColdLead(lead: EnrichedLead): boolean {
+  // Lead with no signals or enrichment older than 24h
+  if (lead.signalCount === 0) return true;
+
+  if (lead.lastEnrichedAt) {
+    const enrichedAt = new Date(lead.lastEnrichedAt).getTime();
+    const now = Date.now();
+    const oneDayMs = 24 * 60 * 60 * 1000;
+    return (now - enrichedAt) > oneDayMs;
+  }
+
+  return false;
+}
+
+/**
+ * Warm Stage Rule: 2+ signals, low threat, quality >= 40
+ */
+export function isWarmLead(lead: EnrichedLead): boolean {
+  return (
+    lead.signalCount >= 2 &&
+    lead.competitorThreat < 50 &&
+    lead.quality >= 40
+  );
+}
+
+/**
+ * Hot Stage Rule: 3+ signals, quality >= 70, threat >= 50
+ */
+export function isHotLead(lead: EnrichedLead): boolean {
+  return (
+    lead.signalCount >= 3 &&
+    lead.quality >= 70 &&
+    lead.competitorThreat >= 50
+  );
+}
+
+/**
+ * Sales-Ready Stage Rule: All hot criteria + revenue >= $10k + no blockers
+ */
+export function isSalesReady(
+  lead: EnrichedLead,
+  projection?: RevenueProjection,
+  blockers?: string[]
+): boolean {
+  const hasBlockers = blockers && blockers.length > 0;
+  const meetsRevenue = projection ? projection.projectedRevenue >= 10000 : false;
+
+  return (
+    isHotLead(lead) &&
+    meetsRevenue &&
+    !hasBlockers
+  );
+}
+
+/**
+ * Evaluate all rules and determine stage
+ */
+export function evaluateStage(
+  lead: EnrichedLead,
+  projection?: RevenueProjection,
+  blockers?: string[]
+): QualificationStage {
+  // Check in order of specificity (most specific first)
+  if (isSalesReady(lead, projection, blockers)) return 'sales-ready';
+  if (isHotLead(lead)) return 'hot';
+  if (isWarmLead(lead)) return 'warm';
+  return 'cold';
+}
+
+/**
+ * Calculate confidence score for qualification
+ */
+export function calculateConfidence(lead: EnrichedLead, stage: QualificationStage): number {
+  let confidence = 0.5; // baseline
+
+  switch (stage) {
+    case 'cold':
+      confidence = 0.3;
+      break;
+    case 'warm':
+      // Increase with signal count and quality
+      confidence = 0.4 + (lead.signalCount * 0.05) + (lead.quality / 500);
+      confidence = Math.min(confidence, 0.75);
+      break;
+    case 'hot':
+      // Increase with signals and threat signal
+      confidence = 0.65 + (lead.signalCount * 0.05) + (lead.competitorThreat / 500);
+      confidence = Math.min(confidence, 0.95);
+      break;
+    case 'sales-ready':
+      confidence = 0.9 + (lead.quality / 1000);
+      confidence = Math.min(confidence, 1.0);
+      break;
+  }
+
+  return Math.max(0, Math.min(1, confidence));
+}
+
+/**
+ * Determine next action for a qualified lead
+ */
+export function getNextAction(stage: QualificationStage): string {
+  switch (stage) {
+    case 'cold':
+      return 'await-enrichment';
+    case 'warm':
+      return 'flag-for-review';
+    case 'hot':
+      return 'draft-email-and-jira';
+    case 'sales-ready':
+      return 'push-to-crm';
+    default:
+      return 'unknown';
+  }
+}
+
+/**
+ * Get Composio actions to queue on stage transition
+ */
+export function getComposioActionsForTransition(
+  fromStage: QualificationStage,
+  toStage: QualificationStage,
+  lead: EnrichedLead
+): string[] {
+  const actions: string[] = [];
+
+  if (toStage === 'hot') {
+    actions.push('composio:draft-sales-email');
+    actions.push('composio:create-jira-issue');
+  }
+
+  if (toStage === 'sales-ready') {
+    actions.push('composio:push-to-salesforce');
+    actions.push('composio:push-to-hubspot');
+    actions.push('composio:send-notification');
+  }
+
+  return actions;
+}
+
+/**
+ * Identify blockers that prevent qualification
+ */
+export function identifyBlockers(
+  lead: EnrichedLead,
+  projection?: RevenueProjection
+): string[] {
+  const blockers: string[] = [];
+
+  if (lead.quality < 40) {
+    blockers.push('quality-below-threshold');
+  }
+
+  if (projection && projection.projectedRevenue < 10000) {
+    blockers.push('revenue-below-minimum');
+  }
+
+  if (lead.competitorThreat > 80) {
+    blockers.push('competitor-threat-critical');
+  }
+
+  if (!lead.signals || lead.signals.length === 0) {
+    blockers.push('insufficient-signals');
+  }
+
+  return blockers;
+}
+
+/**
+ * Validate stage transition is allowed
+ */
+export function isValidTransition(
+  fromStage: QualificationStage,
+  toStage: QualificationStage
+): boolean {
+  const stageOrder: Record<QualificationStage, number> = {
+    'cold': 0,
+    'warm': 1,
+    'hot': 2,
+    'sales-ready': 3,
+  };
+
+  // Allow forward transitions and demotions (with approval)
+  return true;
+}
+
+/**
+ * Get human-readable reason for stage transition
+ */
+export function getTransitionReason(
+  lead: EnrichedLead,
+  fromStage: QualificationStage,
+  toStage: QualificationStage,
+  projection?: RevenueProjection
+): string {
+  const parts: string[] = [];
+
+  if (toStage === 'warm') {
+    parts.push(`${lead.signalCount} signals detected`);
+    parts.push(`competitor threat ${lead.competitorThreat}%`);
+  }
+
+  if (toStage === 'hot') {
+    parts.push(`strong signals (${lead.signalCount})`);
+    parts.push(`high quality (${lead.quality}/100)`);
+    parts.push(`competitor threat ${lead.competitorThreat}%`);
+  }
+
+  if (toStage === 'sales-ready') {
+    parts.push(`all hot criteria met`);
+    if (projection) {
+      parts.push(`revenue projection $${projection.projectedRevenue}`);
+    }
+  }
+
+  return parts.join(', ') || `transition from ${fromStage} to ${toStage}`;
+}

package/src/automation/responseTemplates.ts

@@ -0,0 +1,419 @@
+/**
+ * Response Templates
+ * Email and Jira templates for competitive responses
+ * Phase 8C Task 11
+ */
+
+/**
+ * Email template data
+ */
+export interface EmailTemplate {
+  name: string;
+  subject: string;
+  bodyTemplate: string;
+  cta: string;
+  priority: 'urgent' | 'high' | 'normal';
+}
+
+/**
+ * Jira template data
+ */
+export interface JiraTemplate {
+  name: string;
+  titleTemplate: string;
+  descriptionTemplate: string;
+  storyPoints: number;
+  labels: string[];
+  priority: 'Highest' | 'High' | 'Medium' | 'Low';
+}
+
+/**
+ * Email templates for different threat levels and scenarios
+ */
+export const emailTemplates: Record<string, EmailTemplate> = {
+  critical_threat: {
+    name: 'Critical Competitor Threat',
+    subject: 'URGENT: Critical Competitor Threat - {{competitorName}} Response Required',
+    bodyTemplate: `
+Dear Sales Leadership,
+
+We have identified a CRITICAL threat from {{competitorName}} that requires immediate action.
+
+THREAT OVERVIEW:
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+• Competitor: {{competitorName}}
+• Threat Level: CRITICAL (Score: {{threatScore}}/100)
+• Affected Accounts: {{affectedLeadCount}}
+• Key Account IDs: {{topLeadIds}}
+• Detection Date: {{detectionDate}}
+
+COMPETITIVE THREAT ANALYSIS:
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+1. Market Position: {{competitorStrengths}}
+2. Key Vulnerabilities: {{competitorWeaknesses}}
+3. Our Advantage: {{ourDifferentiation}}
+
+IMMEDIATE ACTION ITEMS (Next 24 Hours):
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+□ Executive briefing on threat
+□ Review customer risk assessment
+□ Prepare customer retention calls
+□ Activate crisis communication plan
+□ Review pricing/packaging response
+
+ESCALATION: {{escalationPath}}
+
+This requires immediate leadership attention and coordinated customer engagement.
+Expected response time: 4-6 hours.
+
+Best regards,
+Competitive Intelligence Team
+`,
+    cta: 'Schedule immediate response call',
+    priority: 'urgent',
+  },
+
+  high_threat: {
+    name: 'High Competitor Threat',
+    subject: 'Competitor Update: {{competitorName}} Gaining Traction',
+    bodyTemplate: `
+Dear Sales Team,
+
+We've detected a HIGH priority competitive threat from {{competitorName}} in your pipeline.
+
+THREAT SUMMARY:
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Competitor: {{competitorName}}
+Threat Level: HIGH
+Affected Accounts: {{affectedLeadCount}}
+Key Accounts: {{topLeadIds}}
+
+WHAT CHANGED:
+• {{competitorStrengths}}
+• Market momentum indicators show increased activity
+
+OUR RESPONSE STRATEGY:
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+1. Differentiation: {{ourDifferentiation}}
+2. Unique Value Props:
+   • {{uniqueValue1}}
+   • {{uniqueValue2}}
+   • {{uniqueValue3}}
+
+RECOMMENDED SALES ACTIONS:
+□ Prepare competitive comparison deck
+□ Schedule account review meetings
+□ Document customer pain points we solve better
+□ Create response talking points
+
+Timeline: Handle within 48-72 hours
+`,
+    cta: 'Review competitive positioning',
+    priority: 'high',
+  },
+
+  medium_threat: {
+    name: 'Medium Competitor Threat',
+    subject: 'Market Update: {{competitorName}} Activity Detected',
+    bodyTemplate: `
+Dear Team,
+
+We have identified MEDIUM priority competitive activity from {{competitorName}}.
+
+OVERVIEW:
+• Competitor: {{competitorName}}
+• Affected Accounts: {{affectedLeadCount}}
+• Threat Level: MEDIUM
+
+KEY INSIGHTS:
+{{competitorInsights}}
+
+OUR POSITIONING:
+{{ourPositioning}}
+
+RECOMMENDED FOLLOW-UP:
+• Monitor {{competitorName}} announcements
+• Document customer feedback
+• Prepare messaging for relevant accounts
+
+No immediate action required, but stay alert.
+`,
+    cta: 'Review market intelligence',
+    priority: 'normal',
+  },
+
+  lost_deal: {
+    name: 'Lost Deal to Competitor',
+    subject: 'Deal Loss Analysis: {{competitorName}} - {{accountName}}',
+    bodyTemplate: `
+Dear Sales Leadership,
+
+We have recorded a lost deal to {{competitorName}} at {{accountName}}.
+
+DEAL ANALYSIS:
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Account: {{accountName}}
+Expected Revenue: {{projectedRevenue}}
+Competitor: {{competitorName}}
+Loss Reason: {{lossReason}}
+Customer Feedback: {{customerFeedback}}
+
+ROOT CAUSE ANALYSIS:
+• {{rootCause1}}
+• {{rootCause2}}
+• {{rootCause3}}
+
+RECOMMENDED PRODUCT/MARKETING RESPONSE:
+□ Feature gap analysis
+□ Pricing strategy review
+□ Customer testimonial collection
+□ Win-back opportunity assessment
+
+This information is being fed into our competitive strategy.
+`,
+    cta: 'Schedule loss review meeting',
+    priority: 'high',
+  },
+};
+
+/**
+ * Jira templates for different threat levels
+ */
+export const jiraTemplates: Record<string, JiraTemplate> = {
+  critical_epic: {
+    name: 'Critical Competitor Response Epic',
+    titleTemplate: 'CRITICAL: Counter {{competitorName}} Threat ({{threatScore}})',
+    descriptionTemplate: `
+h1. Critical Competitive Response Epic
+
+h2. Overview
+{{competitorName}} (Threat Level: {{threatLevel}}) is gaining traction and poses a critical threat to our market position.
+
+h2. Market Impact
+* Market Share Risk: {{marketRiskAssessment}}
+* Affected Customer Base: {{affectedLeadCount}} accounts
+* Revenue at Risk: {{revenueAtRisk}}
+* Customer Churn Risk: {{churnRisk}}
+
+h2. Competitor Analysis
+h3. Key Strengths
+* {{competitorStrength1}}
+* {{competitorStrength2}}
+* {{competitorStrength3}}
+
+h3. Key Weaknesses
+* {{competitorWeakness1}}
+* {{competitorWeakness2}}
+
+h3. Our Differentiation
+* {{ourAdvantage1}}
+* {{ourAdvantage2}}
+* {{ourAdvantage3}}
+
+h2. Feature Gaps to Address
+* {{featureGap1}} - *{{priority1}}*
+* {{featureGap2}} - *{{priority2}}*
+* {{featureGap3}} - *{{priority3}}*
+
+h2. Action Items
+h3. Product Team
+* [ ] Complete feature gap analysis
+* [ ] Prioritize roadmap items
+* [ ] Assess implementation effort
+* [ ] Create customer-facing roadmap
+
+h3. Marketing/Sales
+* [ ] Create competitive comparison guide
+* [ ] Prepare sales enablement materials
+* [ ] Brief customer success team
+* [ ] Plan win-back campaigns
+
+h3. Leadership
+* [ ] Strategic positioning review
+* [ ] Pricing strategy reassessment
+* [ ] Partnership opportunities evaluation
+
+h2. Success Criteria
+* [ ] Competitive threat reduced to HIGH or below
+* [ ] Customer retention rate >95%
+* [ ] Win rate improvement documented
+* [ ] Roadmap response planned
+
+h2. Timeline
+CRITICAL: Complete strategic assessment within 1 week
+
+h2. Labels
+competitor-response, urgent, {{competitorName|lowercase}}
+
+h2. Epic Link
+Link to quarterly product roadmap
+
+h2. Priority
+Highest
+`,
+    storyPoints: 21,
+    labels: ['competitor-response', 'urgent', 'critical'],
+    priority: 'Highest',
+  },
+
+  high_epic: {
+    name: 'High Priority Competitive Response',
+    titleTemplate: 'Counter {{competitorName}} High Threat ({{threatScore}})',
+    descriptionTemplate: `
+h1. Competitive Response Epic
+
+h2. Overview
+{{competitorName}} (Threat Level: {{threatLevel}}) is gaining market traction.
+
+h2. Competitive Threat
+* Threat Score: {{threatScore}}/100
+* Affected Accounts: {{affectedLeadCount}}
+* Key Vulnerabilities: {{competitorWeaknesses}}
+
+h2. Our Competitive Advantages
+{{ourDifferentiation}}
+
+h2. Product Response Roadmap
+h3. Priority Features
+* {{feature1}} - {{effort}}
+* {{feature2}} - {{effort}}
+
+h3. Messaging Updates
+* [ ] Update competitive positioning
+* [ ] Create customer comparison guide
+* [ ] Prepare sales training
+
+h2. Success Metrics
+* Win rate against {{competitorName}}: Target >60%
+* Customer satisfaction maintained >4.5/5
+* Market share maintained
+
+h2. Timeline
+1-2 weeks for strategic response planning
+
+h2. Labels
+competitor-response, {{competitorName|lowercase}}
+
+h2. Priority
+High
+`,
+    storyPoints: 13,
+    labels: ['competitor-response', 'standard'],
+    priority: 'High',
+  },
+
+  medium_epic: {
+    name: 'Medium Priority Competitive Monitoring',
+    titleTemplate: 'Monitor {{competitorName}} Medium Threat ({{threatScore}})',
+    descriptionTemplate: `
+h1. Competitive Monitoring Epic
+
+h2. Overview
+{{competitorName}} shows MEDIUM competitive threat indicators.
+
+h2. Details
+* Threat Score: {{threatScore}}/100
+* Affected Accounts: {{affectedLeadCount}}
+* Key Signals: {{signals}}
+
+h2. Monitoring Tasks
+* [ ] Track {{competitorName}} announcements
+* [ ] Monitor customer feedback
+* [ ] Assess feature roadmap impact
+* [ ] Prepare contingency plans
+
+h2. Timeline
+Ongoing monitoring with quarterly reviews
+
+h2. Labels
+competitor-response, monitoring
+
+h2. Priority
+Medium
+`,
+    storyPoints: 5,
+    labels: ['competitor-response', 'monitoring'],
+    priority: 'Medium',
+  },
+};
+
+/**
+ * Template renderer
+ */
+export function renderTemplate(
+  template: string,
+  variables: Record<string, any>
+): string {
+  let result = template;
+
+  Object.entries(variables).forEach(([key, value]) => {
+    const regex = new RegExp(`{{${key}(?:\\|[^}]+)?}}`, 'g');
+    result = result.replace(regex, String(value || ''));
+  });
+
+  return result;
+}
+
+/**
+ * Get email template by threat level
+ */
+export function getEmailTemplate(
+  threatLevel: 'CRITICAL' | 'HIGH' | 'MEDIUM' | 'LOW',
+  scenario: 'new_threat' | 'escalation' | 'lost_deal' = 'new_threat'
+): EmailTemplate {
+  if (threatLevel === 'CRITICAL') {
+    return emailTemplates.critical_threat;
+  } else if (threatLevel === 'HIGH') {
+    return emailTemplates.high_threat;
+  } else if (scenario === 'lost_deal') {
+    return emailTemplates.lost_deal;
+  } else {
+    return emailTemplates.medium_threat;
+  }
+}
+
+/**
+ * Get Jira template by threat level
+ */
+export function getJiraTemplate(
+  threatLevel: 'CRITICAL' | 'HIGH' | 'MEDIUM' | 'LOW'
+): JiraTemplate {
+  if (threatLevel === 'CRITICAL') {
+    return jiraTemplates.critical_epic;
+  } else if (threatLevel === 'HIGH') {
+    return jiraTemplates.high_epic;
+  } else {
+    return jiraTemplates.medium_epic;
+  }
+}
+
+/**
+ * Format email for sending
+ */
+export function formatEmailForSending(
+  templateKey: string,
+  variables: Record<string, any>
+): { subject: string; body: string; cta: string } {
+  const template = emailTemplates[templateKey] || emailTemplates.medium_threat;
+  return {
+    subject: renderTemplate(template.subject, variables),
+    body: renderTemplate(template.bodyTemplate, variables),
+    cta: template.cta,
+  };
+}
+
+/**
+ * Format Jira epic for creation
+ */
+export function formatJiraForCreation(
+  templateKey: string,
+  variables: Record<string, any>
+): { title: string; description: string; storyPoints: number; labels: string[] } {
+  const template = jiraTemplates[templateKey] || jiraTemplates.medium_epic;
+  return {
+    title: renderTemplate(template.titleTemplate, variables),
+    description: renderTemplate(template.descriptionTemplate, variables),
+    storyPoints: template.storyPoints,
+    labels: template.labels,
+  };
+}