f9834564ab
CLAUDE.md: cached context file covering project identity, tech stack, codebase map, schema quick-ref, API gotchas, fix history, working rules, fleet state, and open items. Structured for maximum cache efficiency — stable content first, dynamic state at the end. docs/CONNECTIONS.md: connection parameter shapes (no secrets) for SSH, DB, API, container resolution, Forgejo, Grafana, n8n. docs/PROJECT_CONTEXT.md: client business context (telco field service, 3 cities, service types), data quality gaps, KPI framework by domain, integration roadmap. docs/KPI_FRAMEWORK.md: living KPI register with status tracking, thresholds, client feedback log, and review checklist. To be co-developed with client iteratively. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
101 lines
4.1 KiB
Markdown
101 lines
4.1 KiB
Markdown
# 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; Grafana 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 Grafana panel name/dashboard
|
||
- The refresh frequency
|
||
- The person who reviews it
|
||
|
||
---
|
||
|
||
## KPI Status Register
|
||
|
||
### Fleet Utilisation
|
||
|
||
| KPI | Status | SQL ref | Grafana 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 | Grafana 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 | Grafana 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 | Grafana 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 (Grafana link, PDF, WhatsApp summary)
|
||
- [ ] Identify job management system / ticketing tool for MTTA/MTTR
|
||
- [ ] Confirm vehicle categories (motorcycle, van, 4WD) for per-type benchmarks
|