kianiadee/tracksolid_timescale_grafana_prod
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1
tracksolid_timescale_grafan.../docs/KPI_FRAMEWORK.md
David Kiania f9834564ab Add CLAUDE.md and project docs for structured Claude project 
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>
2026-04-12 20:59:15 +03:00

4.1 KiB
Raw Permalink Blame History

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