customer-health-scorer

Overview

Scores customer accounts across multiple health dimensions, classifies them into risk zones, and generates prioritized intervention recommendations. Produces a visual scorecard with trend indicators and segment-aware benchmarks so teams can act on early warning signals before churn materializes.

Workflow

<Definition - Health Dimensions> The five measurable facets of customer health:

• Usage: Product adoption depth and breadth. Metrics include DAU/MAU ratio, feature penetration, session frequency, and time-in-product.
• Engagement: Proactive interaction with the vendor. Metrics include event attendance, content consumption, community participation, and training completion.
• Support: Ticket volume, severity distribution, resolution satisfaction, and escalation frequency. Lower volume with high satisfaction indicates health; high volume with low satisfaction indicates risk.
• Relationship: Strength of human connections. Metrics include executive sponsor access, multi-threading depth (number of distinct contacts engaged), meeting cadence, and NPS/CSAT responses.
• Commercial: Financial trajectory. Metrics include expansion rate, contraction signals, payment timeliness, discount dependency, and renewal pipeline status. </Definition - Health Dimensions>

<Definition - Scoring Zones> Three classification bands applied after dimension scores are computed:

• Healthy (score above 75): Account shows strong signals across measured dimensions. No immediate intervention required. Monitor for regression.
• At-Risk (score 40 to 75): Account shows degradation in one or more dimensions. Requires proactive outreach within 2 weeks. Specific risk signals should drive the intervention type.
• Critical (score below 40): Account shows severe degradation or multi-dimension failure. Requires immediate intervention plan within 48 hours. Escalate to account leadership. </Definition - Scoring Zones>

<Definition - Segment Benchmarks> Baseline expectations vary by customer segment because behavior patterns differ structurally:

• Enterprise: Higher relationship and engagement expectations. Usage patterns tend toward broad but less frequent. Support tickets skew toward feature requests over break-fix. Benchmark calibration: relationship weight increased to 25%, usage weight reduced to 15%.
• Mid-Market: Balanced expectations across all dimensions. Usage tends toward moderate depth with consistent frequency. Benchmark calibration: equal 20% weight across all five dimensions.
• SMB: Higher usage and commercial sensitivity. Relationship depth is naturally limited (fewer contacts). Benchmark calibration: usage weight increased to 30%, relationship weight reduced to 10%.
• All: Applies mid-market weights as the neutral baseline when segment is unknown or mixed. </Definition - Segment Benchmarks>

<Workflow - Score Customer Health description="End-to-end customer health scoring from raw data to actionable scorecard." tools=[file_read, file_write, run_python, open_in_session_tab] triggers=["score customer health", "account health check", "which customers are at risk", "customer health report", "renewal risk assessment", "portfolio health overview"]

1. [Decide] Determine the input type:

   • File path provided: Read using file_read (CSV/JSON) or run_python with pandas (Excel). Inspect the first 10 rows, all column names, data types, row count, and missing value percentages per column.

   • Pasted data: Parse the tabular data from the conversation. Normalize into a structured format for analysis.

   • Description only: Ask the user what system their data lives in (CRM like Salesforce/HubSpot, analytics like Mixpanel/Amplitude, spreadsheet, data warehouse) and guide them on which fields to export. Provide a template CSV structure showing the columns needed for each selected dimension.

2. [Ask user] Present the discovered file structure: column names, row count, sample values. Propose a column-to-metric mapping for each selected health dimension. Ask the user to confirm or correct the mappings. Flag any dimensions where fewer than 2 input metrics are available and recommend marking those as low confidence per Rule 6.

3. [Agent] Determine the segment benchmark weights to apply based on the user's segment selection. If "all" was selected, apply the neutral mid-market weights. Log the weight distribution: which percentage each dimension contributes to the composite score.

4. [Think] Evaluate data quality across the mapped columns. Identify accounts with excessive missing values (more than 50% of mapped metrics absent). Identify potential new customers (accounts with creation dates under 90 days if that field exists). Determine if historical periods are available for trend computation. Decide whether to flag any dimensions as low confidence.

5. [Agent] Execute the scoring computation in a single Python script:

   • Normalize each metric to a 0-100 scale using min-max normalization within the dataset (or against segment benchmarks if prior benchmark data is provided).
   • Compute per-dimension scores as the weighted average of normalized metrics within that dimension.
   • Compute the composite health score as the segment-weighted sum of dimension scores.
   • Classify each account into Healthy, At-Risk, or Critical zones.
   • Compute trend direction for each dimension if multiple time periods exist.
   • Flag low-confidence dimensions and new-customer exclusions. Save the scoring script to the artifacts folder for reproducibility.

6. [Agent] Generate intervention recommendations for every At-Risk and Critical account. For each flagged account:

   • Identify the weakest dimension(s) driving the classification.
   • Map the specific degraded metrics to a concrete recommended action.
   • Assign urgency (immediate for Critical, within 2 weeks for At-Risk).
   • Note any compounding risk factors (multiple dimensions declining simultaneously).

7. [Agent] Build the health scorecard output using the Health Scorecard template. Write the scorecard as an HTML file with sortable tables, color-coded risk zones, and dimension breakdowns. Save to artifacts and open in the session tab using open_in_session_tab.

8. [Ask user] Present the summary statistics: total accounts scored, distribution across zones, top 5 most critical accounts with their primary risk drivers. Ask if the user wants to drill into specific accounts, adjust weights, or export the results in a different format.

</Workflow - Score Customer Health>

<Template - Health Scorecard>

# Customer Health Scorecard

**Generated:** {{date}}
**Segment:** {{segment}} | **Benchmark weights:** {{weight_distribution}}
**Accounts scored:** {{total_accounts}} | **Excluded (new/insufficient data):** {{excluded_count}}

## Portfolio Summary

| Zone | Count | Percentage |
|------|-------|------------|
| Critical (below 40) | {{critical_count}} | {{critical_pct}}% |
| At-Risk (40-75) | {{at_risk_count}} | {{at_risk_pct}}% |
| Healthy (above 75) | {{healthy_count}} | {{healthy_pct}}% |

## Critical Accounts (Immediate Action Required)

For each critical account:

| Account | Composite Score | Weakest Dimension | Key Signal | Trend | Recommended Action |
|---------|----------------|-------------------|------------|-------|-------------------|
| {{account_name}} | {{score}} | {{weakest_dim}} | {{signal_detail}} | {{trend_direction}} | {{recommendation}} |

## At-Risk Accounts (Action Within 2 Weeks)

Same table structure as Critical, sorted by composite score ascending.

## Dimension Breakdown (All Accounts)

For each account, show individual dimension scores:

| Account | Usage | Engagement | Support | Relationship | Commercial | Composite | Zone |
|---------|-------|------------|---------|--------------|------------|-----------|------|
| {{account_name}} | {{usage_score}} | {{engagement_score}} | {{support_score}} | {{relationship_score}} | {{commercial_score}} | {{composite}} | {{zone}} |

## Data Quality Notes

- Dimensions marked low confidence: {{low_confidence_dims}}
- Accounts excluded (under 90 days): {{new_accounts_list}}
- Metrics with high missing rates: {{missing_metrics}}

## Methodology

- Normalization: Min-max within dataset, scaled 0-100
- Dimension weights ({{segment}}): Usage {{usage_wt}}%, Engagement {{engagement_wt}}%, Support {{support_wt}}%, Relationship {{relationship_wt}}%, Commercial {{commercial_wt}}%
- Classification thresholds: Healthy above 75, At-Risk 40-75, Critical below 40
- Trend calculation: Period-over-period comparison where historical data exists

</Template - Health Scorecard>