gilde

← All craftbooks

Dashboard Specification

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

Specify a dashboard from the questions it must answer, before anyone builds it — the artifact that prevents a chart-salad dashboard nobody uses. Scopes the audience, the decisions, and the questions FIRST, then designs the dashboard layout: which widgets/charts answer which question, their metric definitions, filters, refresh, and visual hierarchy. The output is a build-ready spec, not the dashboard itself. Use this for planning a dashboard, a BI/reporting spec, a metrics dashboard design, deciding what charts a dashboard needs, or a dashboard requirements doc.

Steps

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

  1. Scope the questionsplannerentry

    lock the audience, decisions, and questions the dashboard answers

    Show working prompt
    Establish why the dashboard exists before designing widgets. Step 1: name the primary audience and the recurring decisions they make. Step 2: list the 5-10 specific questions the dashboard must answer for those decisions, ordered by importance. Step 3: for each question, name the metric(s) that answer it and define each metric precisely (numerator/denominator, time window). Step 4: identify the filters/segments users need (date range, team, region) and the refresh cadence. Step 5: write an acceptance-criteria checklist ('every widget traces to a listed question', 'each metric has a precise definition', 'top question is most prominent', 'required filters are listed', 'no orphan chart that answers no question'). Call write_task_note and write the audience + questions + metric definitions + checklist to notes/question-scope.md.
  2. Design the dashboarddesigner

    produce a build-ready layout: widgets, metrics, filters, hierarchy

    Show working prompt
    Design the dashboard as a build-ready specification (a spec, not the live dashboard). Step 1: choose the widget per question — KPI tile for a single headline number, line for trend, bar for comparison, table for detail — and justify each choice. Step 2: lay out the screen in priority order: a top KPI strip for the headline numbers, then trend and breakdown sections; describe the grid/wireframe in markdown. Step 3: for each widget specify title, chart type, the exact metric + its definition, dimensions/filters it responds to, and the data source/field. Step 4: specify global filters, default date range, and refresh cadence. Step 5: confirm every widget maps to a scoped question and there are no orphans. Write the full spec to dashboard-spec.md and call write_task_note with the widget count. On a loop-back, fix only the named gaps.
  3. Evaluatereviewer

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

    Show working prompt
    Read dashboard-spec.md and check it against notes/question-scope.md. Verify: every widget traces explicitly to a listed question (and no orphan widget answers nothing); each widget names a chart type with a justification; each metric has a precise definition (numerator/denominator/window); the layout puts the top question most prominently; and required global filters, default date range, and refresh cadence are specified. Confirm a developer could build it without re-asking what a metric means. Write PASS/FAIL per criterion; any FAIL loops back to design.

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: "design" })` 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.
  4. 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