gilde

← All craftbooks

KPI Scorecard Page

Data and analysisevalv1.0.0released 2026-06-05workflow: build-loop

Build a single-page KPI scorecard that rolls a dataset up into the handful of numbers a team tracks, each shown with its current value, target, and period-over-period change. Defines the KPIs and their exact formulas and targets FIRST (so a number is never ambiguous), then computes the rollups, then builds a clean self-contained HTML scorecard with KPI tiles, deltas, and a tiny trend sparkline each. Use this for a KPI dashboard, a metrics scorecard, an executive summary page, a North Star metrics view, or rolling raw data into headline numbers.

Steps

Entry step: kpi-scope. Each step names the specialist role it wants; the full working prompt is expandable.

  1. Scope the KPIsplannerentry

    lock each KPI's formula, target, and comparison period

    Show working prompt
    Define each KPI precisely before computing anything. Step 1: list the 4-8 KPIs the scorecard shows, ordered by importance. Step 2: for each, write the exact formula (numerator / denominator), the unit and format (count, %, currency), and the time window. Step 3: define the comparison — period-over-period (this month vs last) or vs a target — and the target value where one exists. Step 4: define 'good' direction (up is good vs down is good) so deltas can be colored. Step 5: write an acceptance-criteria checklist ('every KPI has a precise formula and unit', 'each tile shows current value + delta vs comparison', 'targets shown where defined', 'good/bad direction is correct', 'a small trend is shown per KPI'). Call write_task_note and write the KPI definitions + targets + checklist to notes/kpi-scope.md.
  2. Compute the rollupsdata-analyst

    compute each KPI's value, delta, and trend series

    Show working prompt
    Compute every scoped KPI from the data. Step 1: for each KPI apply its exact formula over the current window and record the value. Step 2: compute the same for the comparison window and derive the absolute and % delta and whether it's an improvement given the good-direction. Step 3: build a short trend series (e.g. last 6-12 periods) per KPI for the sparkline. Step 4: attach the target and the gap to target where defined. Step 5: emit data/kpis.json — per KPI { name, value, unit, delta, delta_pct, improved, target, trend[] }. Double-check a denominator isn't zero and a % isn't mis-scaled. Call write_task_note with the headline KPI values and deltas.
  3. Build the scorecarddeveloper

    render a self-contained KPI scorecard page

    Show working prompt
    Build a single self-contained index.html scorecard from data/kpis.json. Step 1: render one KPI tile per metric in priority order, each showing the formatted current value, the metric name, and the delta vs comparison with an up/down arrow colored by improvement (green good, red bad per the good-direction). Step 2: show the target and gap where defined. Step 3: draw a tiny inline sparkline (canvas/SVG) of the trend series in each tile — no external chart CDN that could fail offline. Step 4: lay the tiles out in a responsive grid, headline KPIs largest. Step 5: ensure values are real (from the JSON), formatting is correct, and there are no console errors. On a loop-back, fix only the named gaps. Call write_task_note with the path and KPI count.
  4. Evaluatereviewer

    Grade the deliverable against every acceptance criterion. All pass → finish; any fail → loop back and fix the gap.

    Show working prompt
    Open index.html (render it if possible, else trace the source) and check against notes/kpi-scope.md and data/kpis.json. Verify: every scoped KPI appears as a tile with its formatted current value; each tile shows a delta vs the comparison with the correct good/bad color direction; targets and gaps are shown where defined; a trend sparkline renders per KPI from real data; and there are no console errors. Re-derive one KPI's value and delta from the data. Write PASS/FAIL per criterion; any FAIL loops back to build.

Then route — this is the whole point of the loop:

- **Every criterion PASSES →** call `advance_task_step({ ref, stepId: "evaluate", next: "finish" })`.
- **Any criterion FAILS →** write the specific gaps to notes, then call `advance_task_step({ ref, stepId: "evaluate", next: "build" })` to loop back. The builder fixes exactly those gaps.

Never route to `finish` while any criterion is unmet. The build phase's completion gate already blocked a grossly-incomplete deliverable; your job is the judgment an automated check cannot make (does it actually work, read well, look right). After ~3 unproductive loops, stop and report DONE_WITH_CONCERNS so the user can step in.
  5. Finishdeveloper

    All acceptance criteria met. Stamp a short summary and report DONE.

    Show working prompt
    Every acceptance criterion passed. Write a one-paragraph DONE summary to task notes via `write_task_note`: what was built, the deliverable path(s), and a one-line confirmation that each criterion is met. Then report DONE.

Triggers

Phrases that suggest this craftbook to a crew.

Source

View this craftbook on GitHub · MIT license