ANALYTICS & REPORTING

Dashboard spec writing

Use before anyone builds a dashboard, so the build is not a pile of charts nobody uses.

dashboard-spec-writing.md

Download .md

You are specifying a dashboard before it gets built. Write the spec, not the dashboard.

Who uses it: {{USERS_AND_ROLES}}
Decisions it must support: {{DECISIONS}}
Cadence they will look at it: {{CADENCE}}
Data sources available: {{DATA_SOURCES}}

Output:
1. Decision-to-metric map: a table of Decision | Metric that informs it | Threshold or comparison that triggers action | Source. Every metric must map to a decision. Drop any metric that does not.
2. Layout: sections top to bottom, what goes in each, and why that order for this reader.
3. For each tile: name, metric definition in one sentence, comparison (versus last period, versus target, versus forecast), granularity, and default date range.
4. Filters and segments that must be present, and which are defaults.
5. Definitions appendix: every metric written so two people would calculate it identically.
6. Explicitly out of scope: metrics people will ask for and why they are not here.
7. Refresh frequency and what to show when data is late or incomplete.

Rules:
- No vanity tiles. If a number cannot change a decision, it goes in section 6.
- Do not specify a metric the listed sources cannot produce. Flag those as blocked and say what is needed.
- Keep the main view to at most {{MAX_TILES}} tiles.

Fill in before running

Replace each placeholder with your own detail. The more specific you are, the less the model invents.

{{USERS_AND_ROLES}}
{{DECISIONS}}
{{CADENCE}}
{{DATA_SOURCES}}
{{MAX_TILES}}

Getting a better result

Do section 1 with the actual users in the room; the arguments there are the real spec.
The definitions appendix prevents the quarterly argument about what a session is.
Section 6 saves you from scope creep during the build.

Questions about this prompt

When do I use this rather than just building the dashboard?

Before anyone opens the BI tool. Building first produces a wall of charts followed by an argument about which ones matter. The spec starts from the decisions the dashboard must support and drops any metric that does not map to one, and that conversation is far cheaper on paper than in a built dashboard.

What do I need in front of me?

Who uses it and in what role, the decisions it must support, how often they will look, the data sources available, and a maximum tile count. Do the decision to metric map with the actual users present. The disagreement about which decision a metric informs is the real spec and cannot be reconstructed later.

What comes back?

A decision to metric map, a layout with reasoning for the order, per tile definitions with comparison and default date range, filters, a definitions appendix, an out of scope list, and what to show when data is late. The definitions appendix keeps paying, because it ends the quarterly argument about what a session is.

What is the mistake that costs me here?

Treating the out of scope section as filler. It is what you point at during the build when someone asks for one more tile, and without it the spec grows back into the wall of charts you were avoiding. Flag blocked metrics honestly too, rather than specifying something the listed sources cannot produce.