Decision First Dashboard

Decision-First Dashboard

Core principle

Decision-First does not mean Minimal-Data. Preserve rich evidence, create strong hierarchy, and expose only justified meaning.

Source / context → Worthiness Assessment → worthiness gate → Decision Brief → intake gate → Metric Routing Manifest → grounded evidence bundle → routing + grounding gates → deterministic renderer → canonical HTML / SVG + output.manifest.json

The agent may assess whether a dashboard is warranted, clarify decision intent, extract and classify evidence, and propose routing. It may not invent source support, bypass worthiness/intake/routing/grounding gates, or choose a free-form dashboard layout during ordinary compilation.

A dashboard earns first-view screen space only when the information can change a decision, trigger an action, surface an exception, explain a primary signal, or support deliberate drill-down.

Adaptive composition grammar

Do not add bakery, sales, SaaS, executive, or monitoring renderer branches. There is one composition engine and one renderer entrypoint. Evolve the existing pipeline as Decision Brief → Semantic Nodes → Node Presentation → Composition Modifiers → Coverage Manifest → Context Preservation Gate → deterministic renderer → delivered-artifact verifier.

Semantic nodes may be MetricCluster, Trend, Distribution, Breakdown, Ranking, Relationship, ExceptionList, or Drilldown. Audience and cadence modify priority, density, prominence, expansion, drilldown depth, and first-view budget; they are not renderer types and cannot discard context required by the confirmed decision.

Use structured contextRequirements on the existing Decision Brief when the decision and source structure require retained comparison, distribution, ranking, target, attribution, or decomposition context. Each requirement has a stable ctx_ id, subject, and minimum coverage. Infer unambiguous requirements, but ask only when an ambiguity would change the decision. Coverage is evaluated for the required subject, never satisfied by another node's compatible shape. Keep the full structure, use an explicit reachable drilldown, or fail closed; never silently replace it with a peak summary. The same source must keep its semantic nodes across audience/cadence changes; modifiers may alter priority, density, prominence, expansion, drilldown, or a node-owned presentation only when that variant preserves every required context.

Radar is only a MetricCluster presentation. It requires at least three comparable dimensions in one evaluation system, a shared meaningful scale or source-backed normalization, and a real profile/balance decision. Mixed counts, shares, ROI, and deltas fail the Profile Test and use comparison presentation. A local signal direction is not a visible overall business verdict in no-score mode. Every visible overall verdict must be a typed claim with claimType, scope, and source evidenceRefs, plus resolvable artifact markers; a verdict without evidence refs cannot render. Never synthesize IMPROVING, DETERIORATING, or MIXED without a source-backed score, target, health model, or explicitly confirmed user verdict.

The delivered gate reads the final HTML/SVG and a delivered manifest, not merely composition intent. Every delivered node must expose machine-readable data-semantic-node, data-presentation, data-coverage, and registered structure markers that cross-check the manifest and actual item markers in both artifacts. A manifest that says a node was delivered when the artifact does not show its marker or complete structure fails. The verifier alone issues the final verification block after success; it binds artifactHash and the final manifest manifestPayloadHash (with manifestHash compatibility), and a renderer- or composer-supplied stamp fails. Composition decisions use a stable reasonCode plus a parseable requirementRef or active modifierRef; unknown or unattributed promote/retain/collapse/drop decisions fail.

Mandatory execution contract

This contract applies whenever the skill is actually invoked for a dashboard redesign.

1. Do not render before intake passes. A screenshot, dataset, title, KPI mix, or domain pattern may establish source facts but cannot by itself confirm business intent. If Decision or Action is not explicitly confirmed, stop and ask one question. Do not generate an image, HTML, SVG, React app, dashboard artifact, Key Insights, or action recommendations first.
2. The agent must not render UI. The agent prepares structured inputs; compile-dashboard.js owns canonical production delivery.
3. No free-form fallback. If the runtime cannot execute the production scripts, stop at the unresolved question or structured state. Do not substitute an agent-authored dashboard.
4. Canonical After means exact compiler output. The primary After is the HTML bytes written by compile-dashboard.js. Do not treat that HTML as a reference and redraw it afterward.
5. Require provenance. Canonical HTML/SVG must carry the compiler provenance markers and the run must emit output.manifest.json. A visually similar artifact without canonical provenance is not the official Decision-First output.

Host-level skill discovery is outside the repository's control. A generic product request may still fail to invoke an installed skill in some environments; measure that separately with live product tests. Once this skill is invoked, the execution contract above is mandatory.

Three layers

Layer 1 — Agent intelligence

The agent may:

• produce a structured Worthiness Assessment from explicit user/context evidence;
• build a structured adaptive Decision Brief;
• extract literal source facts;
• classify every extracted metric with the Metric Router;
• produce a Metric Routing Manifest;
• choose a proposed evidence mode;
• create evidence anchors and claim references.

The agent must not render UI, fabricate score-model evidence, or decide its own worthiness transition. The agent does not choose or set the transition; the compiler owns the transition.

Layer 2 — Compiler contract

The production compiler validates, in order:

1. Worthiness Assessment against schemas/worthiness-assessment.schema.json plus semantic consistency rules;
2. Decision Brief against schemas/decision-brief.schema.json;
3. confirmed Decision + Action before routing, plus exact binding into the routing manifest;
4. Metric Routing Manifest against schemas/metric-routing.schema.json and semantic rules;
5. exact agreement between routed primary_signal metrics and visible center metrics/components;
6. exact agreement between no-score diagnostics routed as supporting and decisionState.supportingSignals;
7. active-exception surfacing rules;
8. the closed grounded-bundle and decision-state contracts;
9. source SHA-256, evidence integrity, exact JSON Pointer/text-span grounding, and required claim coverage;
10. composite score mathematics and score-band semantics;
11. semantic-node composition coverage and a machine-readable decision log;
12. delivered HTML/SVG markers, delivered manifest, and verifier-issued hash-bound stamp.

Worthiness transitions:

• BUILD_DECISION_BRIEF
• ASK_WORTHINESS_QUESTION
• REDIRECT_NON_DASHBOARD
• FIX_WORTHINESS_ASSESSMENT

Decision Brief intake transitions:

• ALLOW_ROUTING
• ASK_DECISION_BRIEF_QUESTION
• FIX_DECISION_BRIEF

Downstream transitions:

• PASS
• FIX_METRIC_ROUTING
• RETURN_TO_EVIDENCE_EXTRACTION
• FALLBACK_TO_NO_SCORE
• FIX_DECISION_STATE

Layer 3 — Deterministic renderer

render.js consumes only validated decision state plus the selected semantic-node composition and fills deterministic SVG/HTML compositions. It does not inspect hidden routing inventory, source data, or invent business meaning. Node presentation variants belong to their semantic node; no use-case, audience, or fixture-specific template registry is allowed.

drilldown, scorecard_only, and diagnostics routed on_demand remain preserved for traceability without becoming eager first-view clutter. Only diagnostics explicitly routed with visibility: "supporting" may enter the closed supportingSignals layer and render as subordinate context.

Semantic Visual Grammar — explicit HOW contract

After composition selects the semantic nodes, the canonical compiler builds one Internal Visual Spec per selected node. The spec records nodeId, semanticType, presentation, mark, orientation, encoding, scale, comparability, and attributed layout. It is the only source of visual HOW; render-semantic.js must consume it and must not infer a chart from labels, audience, fixture, or use case.

The grammar uses one shared registry and one renderer pipeline. Trend full charts are ordered temporal plots, Distribution full charts preserve the complete ordered distribution, full Rankings compare ordered magnitudes, both-end Rankings use an explicit high/low pair, and MetricCluster comparison uses independent metric tiles. Radar remains legal only after the existing Profile Test. No G2, Vega-Lite, Observable Plot, Recharts, ECharts, or other external rendering dependency is permitted.

Shared position, length, area, or scale requires compatible unit, comparison group, comparability domain, normalization, and scale. Same unit is not sufficient. Mixed-unit metrics use independent scales; an illegal shared encoding or paired layout fails closed. Non-default layout patterns require a registered reasonCode plus a resolvable requirement, modifier, or evidence reference. The delivered verifier cross-checks these specs and their markers against both final HTML and SVG; a manifest-only composition claim is not delivery.

Workflow

1. Run the Dashboard Worthiness Test

Before starting the Decision Brief or committing to dashboard output, ask whether the request deserves to become a persistent dashboard at all. Reuse context already supplied, ask one question at a time only when needed, and count Worthiness questions toward the same five-question total intake budget used by the Decision Brief.

A dashboard is justified when the workflow has a real recurring decision or recurring monitoring loop, a clear accountability path, and a meaningful response that changes when an important signal changes. An accountability path may be a single owner, an on-call team, a distributed responsible team, or a recurring shared decision forum.

Use three tests:

1. Recurring Loop Test — recurring decision, review, or exception-monitoring loop rather than a one-off question.
2. Accountability Path Test — identifiable person, team, or shared forum accountable for responding.
3. Response Change Test — when a material signal changes, an action, priority, escalation, intervention, or coordination changes.

Visibility alone is not a decision and is not sufficient justification for a dashboard.

The compiler, not the agent, determines the transition. If the request fails the Worthiness Test, do not build or render a dashboard by default. Recommend the smallest fitting alternative such as a one-off analysis, scheduled summary, alert, report, or chat/query workflow.

If the user explicitly chooses a dashboard after seeing that trade-off, userOverride: true may enter the Decision Brief, but it does not bypass intake, Metric Router, grounding, or rendering contracts.

Worthiness is design context, not source evidence. The machine gate verifies schema and semantic consistency; it does not prove the agent interpreted natural-language intent correctly.

2. Build an adaptive Decision Brief

Before routing metrics or choosing a visual mode, establish the minimum decision context needed to design the dashboard. Ask one question at a time, ask no more than five questions total across Worthiness + Decision Brief intake, and stop immediately once enough information exists.

Intent-confirmation gate: a screenshot cannot satisfy the Decision Brief by itself. Unless the user has explicitly stated both the Decision and the Action in the request or prior conversation, ask at least one question and obtain confirmation before Metric Router classification or rendering.

The intake dimensions are a question pool, not a fixed questionnaire:

• Decision — what should the dashboard help determine?
• Action — what decision or action changes when an important signal changes?
• Exception — what condition deserves immediate attention?
• Diagnosis — where should the user investigate next after a problem appears?
• Audience / cadence — who uses it, how quickly, and how often?

Use two notions of known:

• Observed source fact — directly visible or mechanically extracted. Never ask the user to repeat source facts already available.
• Business intent — Decision, Action, exception policy, diagnosis priority, and audience/cadence. It is confirmed only when explicitly supplied or explicitly confirmed by the user.

Prefer plain business language for the first intent question:

> When you open this dashboard, what are you trying to figure out or do next?

If the answer remains abstract, follow with:

> What would make that job easier?

The abstract “What decision does this dashboard support?” wording is a fallback, not the only allowed intake phrasing. The goal is to confirm the user's real decision or next action without asking them to translate their work into framework terminology.

An inferred candidate requires confirmation. Do not use “inferable from the data” to skip confirmation of business intent.

After each answer, evaluate sufficiency. The zero-question path is narrow: use it only when the user's request or already-established context explicitly states both Decision and Action and Worthiness is already resolved. Source data alone never qualifies.

If the user is unsure:

1. offer 2–4 concrete choices grounded in known context;
2. include an “I'm not sure — help me decide” path;
3. infer the most defensible answer from the data only as a candidate and ask for confirmation;
4. otherwise leave the dimension unresolved.

Do not invent a threshold.

Support both intake orders:

• data-first — profile the uploaded data before asking, then ask only for missing decision context;
• question-first — clarify decision context first, then request only the data needed.

The Decision Brief is internal design context. It is not automatically source evidence and no compiler/framework methodology labels in visible UI are permitted.

The structured brief must match schemas/decision-brief.schema.json. scripts/intake.js requires both Decision and Action to have status: "confirmed". Otherwise the pipeline returns ASK_DECISION_BRIEF_QUESTION and produces no dashboard artifact.

The brief also carries structured intent slots questionShape and actionShape (same slot format). state+observe classifies a MONITOR archetype and priority+rank classifies a PRIORITIZE_READONLY archetype; anything else — missing, inferred, or an unsupported combination — returns ASK_COMPOSITION_INTENT with a ready-to-ask question and produces no artifact. Archetypes are compiler-owned: routing manifests cannot set them, and free-form decision/action prose never overrides the structured slots. A priority+rank intent additionally requires a grounded ordering basis (source-declared explicit ranks, or a grounded actual/target/gap structure); without one the pipeline asks for the basis instead of ever ordering candidates by raw values.

3. Extract verified facts only

Capture only source-supported metrics, deltas, states, events, targets, thresholds, and score rules. Never invent scores, targets, thresholds, customer states, events, workflows, actions, or causal claims. Direction is not the same as health.

4. Route

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: fourleaf13-hue
• Source: fourleaf13-hue/decision-first-dashboard
• License: MIT

Install and usage instructions live in the source repository linked above.