tracksolid_timescale_grafana_prod/docs/KPI_FRAMEWORK.md

# KPI Framework — Telco Field Service Fleet
## Fireside Communications · Co-developed with client

> **Status:** Draft — pending client review and validation.  
> Update this file after each client feedback session. Move KPIs from Proposed → Active → Retired as the programme matures.

---

## How to Use This Document

1. **Proposed** — KPI defined, not yet validated with client
2. **Active** — Client confirmed this matters; query written; FleetOps panel exists or is in progress
3. **Baseline set** — Enough historical data exists to set a meaningful target
4. **Retired** — No longer tracked (document reason)

Each active KPI should link to:
- The SQL query (or reference to `01_BusinessAnalytics.md`)
- The FleetOps panel name/dashboard
- The refresh frequency
- The person who reviews it

---

## KPI Status Register

### Fleet Utilisation

| KPI | Status | SQL ref | FleetOps panel | Reviewed by | Cadence |
|---|---|---|---|---|---|
| Utilisation rate (%) | Proposed | `01_BusinessAnalytics.md §2.1` | — | — | Daily |
| Idle time % of shift | Proposed | `01_BusinessAnalytics.md §2.2` | — | — | Daily |
| Vehicles not moved today | Proposed | `01_BusinessAnalytics.md §2.3` | — | — | Daily |
| Fleet km today | Proposed | `01_BusinessAnalytics.md §5.1` | — | — | Daily |
| Fleet km this week | Proposed | `01_BusinessAnalytics.md §5.2` | — | — | Weekly |

### Technician Productivity *(requires job system integration)*

| KPI | Status | SQL ref | FleetOps panel | Reviewed by | Cadence |
|---|---|---|---|---|---|
| Jobs completed per tech per day | Proposed | TBD | — | — | Daily |
| First-time fix rate | Proposed | TBD | — | — | Weekly |
| Mean time to arrive (MTTA) | Proposed | TBD | — | — | Weekly |
| Mean time to repair (MTTR) | Proposed | TBD | — | — | Weekly |
| SLA compliance rate | Proposed | TBD | — | — | Weekly |

### Driver Behaviour

| KPI | Status | SQL ref | FleetOps panel | Reviewed by | Cadence |
|---|---|---|---|---|---|
| Speeding events per 100 km | Proposed | `01_BusinessAnalytics.md §3.1` | — | — | Weekly |
| Harsh driving index | Proposed | `01_BusinessAnalytics.md §3.2` | — | — | Weekly |
| Late starts (count per driver) | Proposed | `01_BusinessAnalytics.md §3.3` | — | — | Monthly |
| Early knock-off | Proposed | `01_BusinessAnalytics.md §3.3` | — | — | Monthly |
| After-hours movement | Proposed | `01_BusinessAnalytics.md §3.4` | — | — | Daily |

### Asset Health & Cost

| KPI | Status | SQL ref | FleetOps panel | Reviewed by | Cadence |
|---|---|---|---|---|---|
| Estimated idle fuel cost (KES) | Proposed | `01_BusinessAnalytics.md §2.2` | — | — | Monthly |
| Vehicles at service threshold | Proposed | TBD | — | — | Weekly |
| Alarm rate per vehicle/week | Proposed | `01_BusinessAnalytics.md §6` | — | — | Weekly |
| GPS offline rate | Proposed | — | — | — | Daily |

---

## Severity & Threshold Reference

Adjust with client after first month of live data:

| Metric | Green | Amber | Red |
|---|---|---|---|
| Fleet utilisation rate | > 60% | 40–60% | < 40% |
| Idle time % of shift | < 15% | 15–30% | > 30% |
| Speeding per 100 km | < 0.5 | 0.5–2.0 | > 2.0 |
| Harsh driving index | < 0.5 | 0.5–2.0 | > 2.0 |
| Late starts / month | 0–1 | 2–4 | ≥ 5 |
| Alarm rate / vehicle / week | 0–2 | 3–7 | > 7 |
| GPS offline rate | < 5% | 5–15% | > 15% |
| MTTA (minutes) | < 30 | 30–60 | > 60 |
| First-time fix rate | > 85% | 70–85% | < 70% |
| SLA compliance | > 95% | 85–95% | < 85% |

---

## Client Feedback Log

| Date | Session | Feedback | Action |
|---|---|---|---|
| — | Initial framework | Draft created | Awaiting first client review |

---

## Next Review Checklist

- [ ] Confirm shift hours (start, end, lunch, working days)
- [ ] Confirm SLA tiers (home vs business customer)
- [ ] Confirm which KPIs the ops manager wants on a daily digest
- [ ] Confirm reporting format (FleetOps link, PDF, WhatsApp summary)
- [ ] Identify job management system / ticketing tool for MTTA/MTTR
- [ ] Confirm vehicle categories (motorcycle, van, 4WD) for per-type benchmarks