# KPI Profiles

Per-use-case KPI definitions with green/yellow/red thresholds. Used by `/cortex-qa`, `/cortex-monitor`, and `/cortex-status` to evaluate agent health and trigger alerts.

All metric sources reference columns from `fetch_metrics.sh` (28-column output defined in `src/sql/performance.sql`).

---

## Appointment-Setting

Agents focused on qualifying leads and booking calls with a sales/admissions team.

| KPI | Metric Source | Green | Yellow | Red | Weight |
|-----|--------------|-------|--------|-----|--------|
| Booking Effectiveness | `booking_send_rate` | > 0.15 | 0.08–0.15 | < 0.08 | 0.20 |
| Qualification Quality | `pct_calls_booked_low_lead_score` | < 0.10 | 0.10–0.25 | > 0.25 | 0.20 |
| Happy Path Compliance | `avg_happy_path_score` | > 75 | 60–75 | < 60 | 0.15 |
| Premature Rate | `premature_rate_refined` | < 0.10 | 0.10–0.25 | > 0.25 | 0.20 |
| Nurturing Quality | `avg_nurturing_score` | > 70 | 55–70 | < 55 | 0.15 |
| Risk Score | `risk_score_0_100` | < 30 | 30–60 | > 60 | 0.10 |

**Key signals**: booking_send_rate is the primary conversion metric; premature_rate guards quality; nurturing indicates lead warming ability.

---

## Low-Ticket Offering

Agents selling lower-priced products directly through DM (courses, challenges, digital products).

| KPI | Metric Source | Green | Yellow | Red | Weight |
|-----|--------------|-------|--------|-----|--------|
| Resource Share Rate | `booking_send_rate` | > 0.20 | 0.10–0.20 | < 0.10 | 0.25 |
| Happy Path Compliance | `avg_happy_path_score` | > 75 | 60–75 | < 60 | 0.20 |
| Engagement Quality | `avg_engagement_score` | > 30 | 20–30 | < 20 | 0.15 |
| Nurturing Quality | `avg_nurturing_score` | > 70 | 55–70 | < 55 | 0.20 |
| Dead-End Rate | `pct_lead_score_eq_1` | < 0.20 | 0.20–0.40 | > 0.40 | 0.20 |

**Key signals**: Resource share drives conversion; dead-end rate shows if the agent is losing leads too early; nurturing determines warmth and trust-building.

---

## Community-Building

Agents focused on engagement, relationship building, and community growth rather than direct sales.

| KPI | Metric Source | Green | Yellow | Red | Weight |
|-----|--------------|-------|--------|-----|--------|
| Engagement Quality | `avg_engagement_score` | > 35 | 25–35 | < 25 | 0.30 |
| Happy Path Compliance | `avg_happy_path_score` | > 75 | 60–75 | < 60 | 0.20 |
| Nurturing Quality | `avg_nurturing_score` | > 70 | 55–70 | < 55 | 0.20 |
| Participation Depth | `pct_lead_score_eq_1` | < 0.15 | 0.15–0.30 | > 0.30 | 0.15 |
| Funnel Movement | `avg_funnel` | > 2.5 | 1.5–2.5 | < 1.5 | 0.15 |

**Key signals**: Engagement is the primary metric; participation depth shows if the community is engaged or passive; funnel movement measures relationship progression.

---

## Support / Educational

Agents providing customer support, answering questions, or delivering educational content.

| KPI | Metric Source | Green | Yellow | Red | Weight |
|-----|--------------|-------|--------|-----|--------|
| Happy Path Compliance | `avg_happy_path_score` | > 80 | 65–80 | < 65 | 0.30 |
| Engagement Quality | `avg_engagement_score` | > 30 | 20–30 | < 20 | 0.20 |
| Nurturing Quality | `avg_nurturing_score` | > 75 | 60–75 | < 60 | 0.25 |
| Dead-End Rate | `pct_lead_score_eq_1` | < 0.15 | 0.15–0.30 | > 0.30 | 0.15 |
| Risk Score | `risk_score_0_100` | < 30 | 30–60 | > 60 | 0.10 |

**Key signals**: Happy path and nurturing are paramount for support quality; risk score catches operational issues early.

---

## KPI Health Score Calculation

For each agent, compute a weighted KPI health score (0–100):

```
For each KPI in the agent's use_case profile:
  if value in GREEN range → kpi_score = 100
  if value in YELLOW range → kpi_score = 50
  if value in RED range → kpi_score = 0

health_score = sum(kpi_score × weight) / sum(weights)
```

**Health classification**:
- GREEN: health_score > 75
- YELLOW: health_score 50–75
- RED: health_score < 50

**Alert triggers**:
- INFO: any KPI moves from GREEN → YELLOW
- WARNING: any KPI moves from YELLOW → RED, or health_score drops > 15 points in 7 days
- CRITICAL: 2+ KPIs in RED simultaneously, or health_score < 30

---

## Per-Agent Overrides

Agents can override default thresholds in their `meta.md` under a `**KPI Overrides**` field:

```
**KPI Overrides**: booking_send_rate_green: 0.20, premature_rate_red: 0.30
```

When present, these values take precedence over the use-case defaults. Use sparingly — only when an agent's business model justifies different expectations.

---

## Adding New Use Cases

When a new use case is identified:
1. Add a new section to this file following the same table format
2. Define 5–6 KPIs with green/yellow/red thresholds and weights (weights must sum to 1.0)
3. Document the key signals
4. Update `/cortex-monitor` and `/cortex-qa` to recognize the new use case