Segment Trend Analyser

Analyses portfolio-level trends across defined segments to identify systemic patterns. Part of the Book Intelligence intelligence layer -- synthesises data from all foundation and detection skills into strategic insights for CS leadership.

This is an analytical and reporting skill. It identifies patterns, generates hypotheses, and produces reports. It does not make strategic decisions or implement changes. Those are human (typically VP/Director level) decisions.

When to Run

• Scheduled: Weekly or bi-weekly, depending on portfolio size
• On-demand: When leadership requests portfolio analysis, during QBR preparation, or when a systemic issue is suspected
• Triggered: When Risk Signal Detector flags a spike in risk signals concentrated in a specific segment

Core Execution Logic

Step 1: Define Segments

Group all accounts by each segmentation dimension. Standard dimensions:

Each account can be analysed across multiple dimensions simultaneously.

Step 2: Compute Segment-Level Metrics

For each segment, compute:

Step 3: Compute Period-over-Period Changes

For each metric in each segment:

1. Compare current period to prior period (week-over-week for weekly runs, month-over-month for monthly)
2. Compute absolute change and percentage change
3. Flag segments where any metric changes by more than the portfolio-average change rate

Step 4: Identify Outlier Segments

A segment is an outlier when its metrics diverge significantly from the portfolio average:

Step 5: Generate Hypotheses

For each outlier segment, correlate with known events and generate a hypothesis:

Example hypotheses:

• "Mid-market accounts onboarded in Q3-2025 show 18% lower feature adoption than Q2-2025 cohort at the same contract age. Hypothesis: onboarding process change introduced in July 2025 may be less effective"
• "Enterprise accounts in Financial Services show risk signal density 2.4x portfolio average. Hypothesis: regulatory change in January 2026 shifted customer priorities away from our product's core use case"
• "SMB accounts in the 7-18 month cohort have 22% higher churn rate than the same cohort 12 months ago. Hypothesis: pricing increase in Q1-2025 is creating renewal friction for accounts reaching first renewal"

Hypotheses are directional, not causal. They are starting points for human investigation, not conclusions.

Step 6: Generate Report

Produce a structured portfolio segment report with drill-down capability.

Output Format

Portfolio Segment Report:

{
  "report_date": "2026-03-10",
  "portfolio_summary": {
    "total_accounts": 342,
    "total_arr": 28500000,
    "median_health": 74,
    "health_trend": "stable",
    "risk_signal_density": 0.82,
    "expansion_signal_density": 0.34
  },
  "segments": [
    {
      "dimension": "tier",
      "value": "mid-market",
      "account_count": 156,
      "arr": 12400000,
      "median_health": 71,
      "health_trend": "declining",
      "health_distribution": { "critical": 5, "at_risk": 28, "healthy": 89, "strong": 34 },
      "usage_trend_distribution": { "growing": 22, "stable": 98, "declining": 36 },
      "risk_density": 1.14,
      "expansion_density": 0.29,
      "period_change": {
        "median_health": -3,
        "risk_density": "+0.21",
        "note": "Health declining faster than portfolio average"
      },
      "outlier": true,
      "hypothesis": "Mid-market health decline concentrated in accounts with <12 months tenure. Possible onboarding quality gap."
    }
  ],
  "outlier_alerts": [
    {
      "segment": "mid-market / 7-18mo tenure",
      "alert_type": "health_declining_faster_than_portfolio",
      "evidence": "Median health dropped 6 points in 4 weeks vs. portfolio drop of 2 points",
      "hypothesis": "Recent onboarding cohort underperforming. Investigate onboarding process changes."
    }
  ]
}

Handoff to Human

This skill surfaces to VP/Director-level CS leadership, not individual CSMs.

The human validates hypotheses, investigates root causes, and decides on portfolio-level interventions (process changes, resource reallocation, segment-specific strategies).

Confidence and Limitations

• Medium confidence for statistical trends at sufficient portfolio size (20+ accounts per segment)
• Low confidence for segments with <20 accounts -- flag as "small sample, interpret with caution"
• Hypotheses are directional, not causal. Multiple hypotheses may explain the same trend
• Cannot account for external market factors not captured in internal data
• Seasonal patterns at the segment level require 12+ months of data

Dependencies

Required:

• bi-health-score (all account health records)
• bi-usage-monitor (all account usage profiles)
• bi-risk-detector (aggregate risk signals)
• bi-expansion-detector (aggregate expansion signals)
• CRM segmentation data (tier, industry, size, region, contract dates)
• CRM churn and revenue data (for trailing churn rate and NRR)

Downstream consumers:

• CS leadership reporting
• CS strategy and capacity planning
• Board/investor reporting (NRR trends by segment)

References

• references/statistical-methods.md -- Methods for outlier detection and significance testing
• references/report-templates.md -- Formatted report templates for leadership consumption