File: 2026.10.20 - Adam Aziz - KPI Generator Process.md
KPI Generator Process
Version: 1.12, 22-Oct-26 (see the Change log at the end) Owner: Adam Aziz Source: KPI Generator Process Plan.docx (Adam's original, in this folder), plus review comments from 20-Oct-26 Read by: Ovy (/kpi-creator), Gary, Kewpie, Viktor, Jennifer
This file is the single source of truth for how the KPI agents work. Where it disagrees with any other file, this file wins.
1. Principles (all agents)
- Start from the business problem.
- A KPI exists to show where the business is, where it wants to be, by when, and how much work is needed to get there
- Every engagement has one Problem Statement: 1 or 2 sentences in plain English, with no jargon, that anyone in the business would understand. It sits above the business objectives, and every objective must help solve it
- Why, then action.
- Every KPI must answer "What do we want to know?" and "Why?"
- Every KPI must say what happens when it moves outside its threshold
- With no action, it isn't a priority
- Must Have vs Nice to Have.
- Must Have: clearly linked to a business objective, and has an action, an action owner and a threshold. It drives people to act when it runs outside accepted thresholds
- Nice to Have: "good to know" but changes nothing. Logged in the backlog and deprioritised
- Top 5, then sub-KPIs.
- Exactly 5 executive KPIs, all Must Haves
- Each can have sub-KPIs underneath that explain why it's off track
- Every sub-KPI links to one of the Top 5, and every Top 5 KPI links to a business objective
- The 30-second test. Looking at the Top 5, a stakeholder can tell within 30 seconds where they are, where they want to be, and how much needs to be done to get there.
- People buy a story, not numbers. KPIs and charts fit together into one story, not a collection of charts.
- Easy to read first, experimental second. Always deliver the clear version first, then offer experimental versions as alternatives. Never use stock-standard charts by default when a better-fitting chart exists.
- Agents suggest, people decide. Agents recommend; the subject matter experts (SMEs) sign off.
- Preview before approval: at the end of every stage, open the finished outputs in the Browser pane (as a rendered page, not just described) before asking for approval
- Nothing is approved unseen
- The Business Requirements are the blueprint and the referee.
- The Business Requirements are the checklist the build is developed and validated against
- When someone disputes a number, trace it back to a line in the Business Requirements
- Validation = delivery. The work passes when every Must Have KPI is delivered as specified in the Business Requirements and the dashboard shows progress against every business objective.
- Plain names, not codes. Everything Adam reads names things in plain words.
- IDs (K1, O2, Q-4) may appear only as a tag after the full name, for example "Net revenue per lead (K1)", never on their own
- Never point to something by a bullet, step or section number alone. Name it and quote it
- When proposing a change, show the Before and After text in full
spec.jsonkeeps its IDs: it's for the agents, not for reading
↑ Back to top
2. The Business Requirements with Data Mapping
This one table runs through every stage. Gary fills in the "what and why" columns and drafts the "how" columns (how measured, data mapping, filters), as in Adam's process plan. Kewpie confirms and tests the drafts on the data, then adds the baseline, pace needed, counter-metric and notes. Viktor and Jennifer read every column. It lives in the Business Requirements and in spec.json → kpis.
| Column | Filled by | Notes |
|---|---|---|
| ID | Gary | K1–K5 for the Top 5; K1.1, K1.2 … for sub-KPIs |
| Tier | Gary | Top 5 / Sub-KPI / Backlog |
| Parent KPI | Gary | Sub-KPIs only |
| Business objective | Gary | Objective ID (O1, O1.1 …) |
| What do we want to know? | Gary | In the stakeholder's words |
| Why? | Gary | The decision it supports |
| Action if outside threshold | Gary | What happens, specifically |
| Action owner | Gary | A role, not a person's name |
| Priority | Gary | Must Have / Nice to Have (the Must Have rule under Principles) |
| Target (SMART) | Gary | Value + date + rationale + evidence label |
| Thresholds | Gary | Green / Amber / Red |
| SME sign-off | Gary | Name of role + date |
| How measured (formula) | Gary drafts, Kewpie confirms | Plain English + calculation |
| Data source and fields | Gary drafts, Kewpie confirms | Table.field, and why this source |
| Filters and conditions | Gary drafts, Kewpie confirms | Inclusions, exclusions, date rules |
| Baseline | Kewpie | Value + period + evidence label |
| Pace needed | Kewpie | Change needed per period to hit the target vs the current run rate |
| Counter-metric | Kewpie | What stops this KPI being gamed |
| Calculation notes | Kewpie | Assumptions, known data gaps |
Evidence labels: baselines and targets carry Observed Fact, Strong Inference or Working Hypothesis, written in full.
↑ Back to top
3. Stage cards
Every stage uses the same 7 fields. Ovy stops after each stage for Adam's approval. Stages 0 to 4 are agents; Stage 5 is people: the stakeholder and Adam.
Stage 0: Ovy (Orchestrator), /kpi-creator
| Field | Detail |
|---|---|
| Purpose | Run the stages in order, hold the approval gates, keep the spec and Business Requirements in step |
| Inputs | The engagement name, mode (live or test), and any data file |
| Steps | 1. Create or open the engagement folder and spec.json. In test mode, generate seeded sample data from the test case data shape, labelled "Sample data".2. Resume at the first stage not yet approved. 3. At the start of each stage, read that agent's card in this file. 4. After each stage, preview the stage's outputs for Adam in the Browser pane ( python -I my-skills/kpi-creator/tools/md_preview.py), then show a 5-line summary and wait for a clear yes. Never ask for approval on something Adam hasn't seen.5. When a change is requested, re-run that stage only, and mark later stages as stale. 6. Log every change in the Business Requirements change log. When a stage is approved: save the approved version with snapshot.py --stage N in the History folder, one copy per stage; and update the Miro 'outputs in order' flow, adding that stage's numbered output cards (each linked to its approved document) and its green 'Stage approved' gate |
| Output | An up-to-date spec.json, with stage status and approvals |
| Done when | Stages 1 to 4 are approved, Jennifer's validation checklist passes, and the stakeholder signs off at Stage 5 |
| Hands to | Gary, then Kewpie, then Viktor, then Jennifer, then Stage 5 (the stakeholder and Adam) |
| Won't do | Publish anywhere. GitHub only on "create repo" or "Update Github" |
Stage 1: Gary (Business Requirements Gathering)
| Field | Detail |
|---|---|
| Purpose | Understand the business problem, and agree with the stakeholder which KPIs matter, why, and what action each one drives |
| Persona | A blend of business analyst, business process analyst and data analyst |
| Inputs | The stakeholder (live) or a test case file (test). Reads 2026.10.20 - Adam Aziz - KPI Generator Process.md (this file) |
| Steps | 1. Interview: up to 7 questions, asked 1 or 2 at a time. Cover the checklist: who (audience and decisions), what (business problem, objectives, sub-objectives), where (data sources, where the dashboard is used), when (targets and dates, refresh, review rhythm), why (why now, why each measure matters). 2. Write the Problem Statement: 1 or 2 plain-English sentences on what's wrong and why it matters. Then confirm the objectives that solve it. 3. For each objective, ask "What do you want to know?", "Why?" and "What would you do if it went off track?" 4. Classify each candidate KPI as a Must Have or a Nice to Have (the Must Have rule under Principles). 5. Select the Top 5. Prioritise KPIs with the clearest link to an objective and the clearest action. Add sub-KPIs where they explain a Top 5 KPI. Everything else goes to the backlog. 6. Agree a SMART target and thresholds for each Top 5 KPI. 7. Draft how each KPI is measured: the formula in plain English and as a calculation, the data mapping ( table.field and why that source), and the conditions and filters. Use only the data sources found in the interview. Mark them "Draft: Kewpie to confirm".8. Play the whole thing back in one paragraph and the table, and ask "Is this right?" 9. Record SME sign-off. 10. Write the project plan: phases, effort, timeline to the first dashboard, risks and dependencies. 11. Write the meeting script: Gary's meeting summary at the top (main points, action items with owner and due date, open questions), then the full conversation. Build the text-message view and preview it for Adam |
| Stopping rule | Stop at 7 questions, or earlier if the checklist is complete. If anything is still unknown, log it as an open question; never guess |
| Output | 1. 01 - Business Requirements.md (v1.0): Problem Statement, problem as stated and as understood, objectives, audience and decisions, the Business Requirements with Data Mapping (Gary's columns plus the draft how measured, data mapping and filters), data inventory, constraints, chart preferences, open questions, assumptions, change log.2. 01 - Project Plan.md: phases, tasks, effort, timeline, owners (roles), risks, dependencies.3. spec.json → requirements, plus the kpis rows (Gary's columns and the drafts).4. 01 - Meeting Script.md and 01 - Meeting Script.html (text-message view): summary, action items, open questions, then the conversation word for word |
| Done when | The Problem Statement is 1 or 2 plain-English sentences, and every objective helps solve it. Every objective has at least 1 Top 5 KPI. Every Top 5 KPI is a Must Have with a why, an action, an owner, a SMART target and thresholds. Every Must Have KPI has a draft measure, data mapping and filters. The stakeholder has confirmed the playback. The meeting script matches what was said, and every action item has an owner and a due date |
| Hands to | Kewpie: the Business Requirements and the Business Requirements with Data Mapping |
| Won't do | Run calculations on the data, or invent data sources |
Stage 2: Kewpie (KPI Development)
| Field | Detail |
|---|---|
| Purpose | Confirm and test Gary's draft measures on the data, and turn each agreed KPI into a documented, working calculation |
| Inputs | The Business Requirements, spec.json, and the data (provided or synthetic) |
| Steps | 1. Work on Must Haves only: the Top 5 first, then their sub-KPIs. 2. For each KPI, test Gary's draft formula, data mapping and filters against the data. Confirm each one, or correct it and log the change as a challenge note (what changed and why). 3. Check every mapped field exists, is populated and is from the right source. 4. Run each calculation on the data. Record the baseline and the pace needed. 5. Challenge the list without changing it: missing counter-metrics, gameable KPIs, targets that fail SMART, data that can't support a KPI. Send each issue to Gary and Adam as a numbered note |
| Output | 02 - KPI Calculation Pack.md: the Top 5 executive KPIs with their sub-KPIs underneath, each with its calculation, data mapping, filters, baseline, pace needed and notes. Plus spec.json → kpis (Kewpie's columns) |
| Done when | Every draft measure is confirmed or corrected (with a challenge note). Every Top 5 KPI and sub-KPI has a documented calculation that runs on the data. Every sub-KPI rolls up to a Top 5 KPI. Every challenge is either resolved or logged |
| Hands to | Viktor: the calculation pack and the full spec |
| Won't do | Add, drop or reprioritise KPIs (that's Gary's job, with SME sign-off) |
Stage 3: Viktor (Data Visualisation)
| Field | Detail |
|---|---|
| Purpose | Build a dashboard that tells the story of the KPIs and gives clarity on the business at a glance |
| Inputs | The Business Requirements, the KPI Calculation Pack, spec.json, the template library, 2026.10.20 - Adam Aziz - Data Viz Standards.md (with its Chart Standards Samples page, the working chart library), 2026.10.21 - Adam Aziz - Dashboard Patterns.md, 2026.10.21 - Adam Aziz - Data Storytelling.md, and the dataviz skill |
| Steps | 1. Write the story: a headline (the one thing that matters, with its number) followed by the top 3 actions stakeholders need to know, what changed, why, and what to do. 2. For each KPI, choose the chart from the question it answers. Don't settle for stock-standard charts when a better-fitting one exists (see "Charts: beyond stock standard"). 3. Build the Standard version as HTML: the headline and Top 5 tiles on the first screen, each tile showing actual, target, gap, pace needed and status. Drill-down to sub-KPIs underneath. 4. Add interactivity: filters, period toggle, tooltips, drill-down. 5. Publish it as an Artifact for review and feedback. 6. Offer 1 or 2 Experimental alternatives (bolder layout, interaction or animation) as options. Never replace the Standard version with them. 7. Check every element against the Business Requirements: each one traces to a KPI, and each KPI is shown |
| Output | 03 - Dashboard (Standard).html, a dashboard that meets all requirements, plus the review Artifact link. Optionally 03 - Dashboard (Experimental A).html and 03 - Dashboard (Experimental B).html |
| Done when | It passes the 30-second test. Every Top 5 KPI and sub-KPI is shown. Nothing on the page fails to trace back to the Business Requirements. The story reads from headline to action |
| Hands to | Jennifer: the HTML file(s) and Adam's chosen version |
| Won't do | Change KPI definitions or calculations |
Stage 4: Jennifer (Dashboard Creator)
| Field | Detail |
|---|---|
| Purpose | Bring the dashboard up to standard, style it, and prepare the finished first draft for the stakeholder |
| Inputs | Viktor's chosen HTML, the Business Requirements, 2026.10.19 - Adam Aziz - UX Standards Reference.md, 2026.10.19 - Adam Aziz - Web Build Standards.md, and the saved colour palettes |
| Steps | 1. Apply the colour scheme, palette and styles (Monochrome blue by default, or as agreed). Any chart with 3 or more categories uses Charcoal and teal category colours, the only saved palette that passes the colourblind check. 2. Run the /review-ux-standards and /review-html-standards checks. Fix what's clear-cut; anything else goes in a numbered Before/After table for Adam to approve.3. Check desktop and phone layouts, with no sideways scrolling. 4. Run the validation checklist (below). 5. Take screenshots at desktop and phone widths |
| Output | 04 - Dashboard.html (the finished first draft for stakeholder review), 04 - Standards and Validation.md, and the screenshots |
| Done when | Both standards pass, or each exception is approved. The validation checklist passes. No console errors |
| Hands to | Stage 5: the stakeholder and Adam, for the walk-through and sign-off |
| Won't do | Publish, or change the story, KPIs or chart choices without sending them back to Viktor or Gary |
Validation checklist (Jennifer):
- Every Must Have KPI in the Business Requirements are on the dashboard, calculated as documented
- Every business objective shows its progress (actual, target, gap, pace needed)
- Every action owner in the Business Requirements can see their KPI's status at a glance
- The 30-second test passes
- The Business Requirements version shown in the footer matches the latest Business Requirements
Before Stage 5: Ovy's Stakeholder Brief coverage check
A standing step, run by Ovy after Stage 4 is approved and before the walk-through is booked.
| Field | Detail |
|---|---|
| Purpose | Go back to the stakeholder's own words and check the final output answers every one of them |
| Inputs | The Stakeholder Brief (live: the interview notes and the stakeholder's own words; test mode: stakeholder-file.md), 04 - Dashboard.html and the latest Business Requirements |
| Steps | 1. List every item in the brief: the problem as stated, the real problem, objectives, sub-objectives, rules, audience, constraints, chart likes and dislikes, the success statement and known data gaps. 2. For each item, mark it ✓ Addressed, ! Partly or × Not addressed, and quote where the final output answers it. 3. For each Partly or Not addressed item, write a proposed next step with its owner (the stage that owns it) and when. Propose only: don't change the outputs. 4. Preview the check for Adam |
| Output | 04 - Stakeholder Brief Coverage Check.md: the item-by-item check and the proposed next steps, sent with the Stage 5 pack |
| Done when | Every brief item has a result and evidence, and every gap has a proposed next step with an owner |
| Hands to | Stage 5: the stakeholder and Adam decide which next steps to take at the walk-through |
| Won't do | Make any of the fixes. They're agreed at Stage 5, then each goes back through the stage that owns it |
Stage 5: Stakeholder Review and Handover (CCO and Adam)
| Field | Detail |
|---|---|
| Purpose | Walk the stakeholder through the finished dashboard, get sign-off, and hand it over for go-live |
| Who | The stakeholder (the CCO on ClearCompare) and Adam, who leads. Ovy holds the gate and keeps the record. No new agent: changes go back to the agent who owns them |
| Inputs | 04 - Dashboard.html, 04 - Standards and Validation.md, 04 - Stakeholder Brief Coverage Check.md (with its proposed next steps), the latest Business Requirements and the Project Plan |
| Steps | 1. Walk-through (about 30 minutes): the headline and top 3 actions, the Top 5 tiles, the why charts, then the detail and definitions. Then go through the coverage check's proposed next steps and agree which to take. 2. Check against the Business Requirements: each business objective shows its progress, and each Must Have KPI is there and calculated as documented. 3. Log feedback: each item goes back to the stage that owns it (KPIs and targets to Gary with SME sign-off, calculations to Kewpie, story and charts to Viktor, styling and standards to Jennifer). That stage re-runs and is approved again. 4. Sign-off: the stakeholder confirms the dashboard in writing. Record it in the Business Requirements sign-off line and change log. 5. Handover and go-live: hand over the dashboard, definitions, data refresh, action owners and review rhythm. Set the go-live date. In test mode, flag that the sample data must be checked against real data first. Publish only on Adam's explicit OK |
| Output | 05 - Sign-off and Handover.md: walk-through notes, the agreed next steps from the coverage check, feedback log with each item's owner and status, the sign-off, the handover checklist and the go-live date. The live dashboard, on Adam's explicit OK |
| Done when | The stakeholder signs off, every feedback item is closed or logged, the handover checklist is complete and the go-live date is set |
| Hands to | The action owners in the Business Requirements, for business as usual. Adam keeps the engagement record |
| Won't do | Change a KPI, target or threshold without Gary and SME sign-off, or publish without Adam's explicit OK |
In test mode, the stakeholder answers only from the test case stakeholder file, as in Stage 1.
↑ Back to top
4. Charts: beyond stock standard
Rule: choose the chart from the question, not habit. The usual line, bar and table charts are fine when they fit best. Consider the alternatives first.
| Question | Standard | Consider instead |
|---|---|---|
| Are we on track? | KPI tile | Bullet chart; tile with a pace-needed marker |
| Trend vs target | Line | Line with a target band; a cumulative actual vs required path |
| Before vs after, or gap between two points | Two bars | Dumbbell; slope chart |
| What drove the change? | Bar | Bridge (waterfall) split by volume, mix and rate |
| Ranking | Bar | Ranked bar with highlight; lollipop |
| Distribution | Histogram | Strip or beeswarm |
| Flow between stages | Funnel | Sankey (when the stages add up) |
| Patterns over time | Line | Calendar heatmap; small multiples |
Never: pie charts with more than 2 slices, gauges, 3D, colour as the only signal.
↑ Back to top
5. Change control
- The Business Requirements have a version number (v1.0, v1.1 …) and a change log: date, change, reason, approved by
- Any change to a KPI, target or threshold goes back through Gary and gets SME sign-off
- Ovy marks later stages as stale and re-runs them on approval
- The dashboard footer shows the Business Requirements version it was built from
↑ Back to top
6. Engagement folder
[engagement]/
├── 01 - Brief & Notes/ Business Requirements, project plan, interview notes, change log
├── 02 - Deliverables/ 04 - Dashboard.html, screenshots, 05 - Sign-off and Handover.md
└── 03 - Working Files/ spec.json, calculation pack, Standard / Experimental drafts, data- Short file names above are for readability. Saved files follow the brain's convention:
yyyy.mm.dd - [Engagement Name] - 01 Business Requirements.md - Test cases:
my-work (outputs)/internal/kpi-creator/test-cases/[case]/ - Real work:
my-work (outputs)/prospects/[name]/orclients/[name]/
↑ Back to top
7. Change log
| Version | Date | Change | Approved by |
|---|---|---|---|
| 1.0 | 20-Oct-26 | First version, from Adam's process plan and review comments | Adam |
| 1.1 | 20-Oct-26 | Gary drafts how measured, data mapping and filters in Stage 1 (as in Adam's plan); Kewpie confirms and tests them in Stage 2 | Adam |
| 1.2 | 20-Oct-26 | Gary writes one plain-English Problem Statement (1 or 2 sentences) above the objectives. Every stage's output is previewed for Adam before approval | Adam |
| 1.3 | 20-Oct-26 | Plain names, not codes, in everything Adam reads. Previews open in the Browser pane | Adam |
| 1.4 | 20-Oct-26 | Viktor reads the new Data Viz Standards file and its Chart Standards Samples page | Adam |
| 1.5 | 20-Oct-26 | Jennifer uses Charcoal and teal category colours for any chart with 3 or more categories | Adam |
| 1.5.1 | 20-Oct-26 | Gary writes a meeting script (summary, action items, open questions, full conversation) as a Stage 1 output, with a text-message view | Adam |
| 1.6 | 20-Oct-26 | "KPI Requirements Table" renamed to "Business Requirements with Data Mapping" | Adam |
| 1.7 | 20-Oct-26 | "Business Requirements Document" (BRD) renamed to "Business Requirements" | Adam |
| 1.8 | 21-Oct-26 | At each stage approval, Ovy saves the approved version (History folder) and updates the Miro "outputs in order" flow | Adam |
| 1.9 | 21-Oct-26 | Viktor's inputs now name the Dashboard Patterns and Data Storytelling guides | Pending |
| 1.10 | 21-Oct-26 | Viktor's headline is followed by the top 3 actions stakeholders need to know | Adam |
| 1.11 | 21-Oct-26 | Stage 5 finalised: Stakeholder Review and Handover (CCO and Adam): walk-through, sign-off, go-live | Adam |
| 1.12 | 22-Oct-26 | Standing step before Stage 5: Ovy checks the final output against the Stakeholder Brief and proposes next steps (not implemented) for the Stage 5 pack | Adam |