version: "1.0.0" name: build-workflow description: > START HERE when building, modifying, or iterating on a data app or dashboard. Defines the fast, iterative "time to wow" workflow: ship one real hero visual first, preview every visual against live data, then expand breadth and polish. Deploy with rayfin up for review. Orchestrates the dax, fabric-data, visuals, headless-preview, and app-design skills so you don't front-load all of them.

Build Workflow — Ship fast, then iterate

Optimize time to wow: the time until the user sees a real, compelling result in the deployed app. Build a thin vertical slice, preview it, then iterate. Do not front-load exhaustive schema discovery, perfect DAX, or perfect theming before anything is visible — that is the slowest possible path.

Headless preview is the agent validation loop. Preview each visual

against live data (npm run preview → PNG + report), wire it into the app, and

deploy with rayfin up to ship the result for review.

The loop

Edit → preview each visual (headless) → wire it in → (milestone) deploy with `rayfin up` → review → refine. Keep each edit/preview loop small and local: the headless preview is your fast inner loop, so rayfin up is a milestone step, not a per-visual one. One reviewed change beats a big-bang build every time.

• All visuals: render the spec headlessly against live data to a PNG +

report — npm run preview — and critique it before it ships. Use it to choose a visual type, check the data fits, and catch clipping/overlap/contrast. (→ headless-preview)

Phases

Phase 1 — Hero slice (time to wow)

Get ONE compelling, real visual wired to live data, previewed, and on screen — as fast as possible.

Scaffold first, then start here. npm run pack:add -- analytics already

gave you the dashboard kit + a runnable demo (src/demo). Don't re-read setup

or re-copy files — go straight to the hero slice, then swap the demo for it.

1. Pick an archetype — decide the dashboard's shape from the request: executive

summary, operational monitoring, or analytical deep-dive. This frames the hero tile and the breadth that follows. Default to executive summary when unsure. (→ app-design: Dashboard archetypes)

1. Minimum schema scan — discover just enough to find one compelling metric:

one scope probe + the one or two tables/measures behind your hero visual. Don't enumerate the whole model. (→ dax: Fast path)

1. One hero query — write a single DAX query at the visual's grain,

quick-test it once, ship it. (→ dax: Fast path)

1. One hero visual — render it the simplest way: map the hero query with

toChartData, author one Graphein spec, and pass it to a ChartCard (or render a KpiCard / DataTableCard with a table / matrix spec) — pass the mapped spec + loading/error, don't hand-write chart code. (→ visuals: Fast path)

1. Preview it against live data — `npm run preview --

--spec hero.json --query <alias> --dax-file q.dax, view the PNG + report, and tune the spec until it reads well. KPI/table/matrix/slicers/dashboard rasterize to PNG too, so preview them before shipping. (→ headless-preview`)

1. Sensible default theme — pick a characterful font pairing + a primary

color and move on. Do not perfect theming yet. (→ app-design: Fast path)

1. Drop the hero tile into `src/App.tsx` — the scaffold renders a bundled

all-Graphein demo (src/demo/) so a fresh app is never blank; delete `src/demo/ and replace <DemoDashboard />** with your hero visual (its providers + slicers + cross-filter wiring are the pattern to copy). Deploy with rayfin up` for review.

Stop after the hero slice and use user feedback before going further.

Phase 2 — Breadth

Add the rest of what the user asked for — more KPIs, charts, table/matrix specs, filters. Preview each new visual against live data as you author it — not once at the end. Pull in interactivity (cross-filtering / cross-highlighting) only when the user actually needs it. (→ dax, visuals, headless-preview)

Phase 3 — Polish

Now refine, driven by what the running app actually shows:

• Theme/typography depth, layout rhythm, and the app-design Final Audit.
• Loading / empty / error states for every async visual.
• Edge-case DAX correctness, number/date formatting, dark mode.

(→ app-design and dax reference files — read on demand.)

Rules

• Preview every visual before it ships. A npm run preview against

live data is the validation loop for getting one visual right.

• Validate visuals headlessly before you deploy. A npm run preview against

live data catches problems far faster than a deploy round-trip.

• Deploy sparingly — `rayfin up` is a slow round-trip. Use it for milestone

review: once after the hero slice, then after a batch of Phase 2 work — never per visual. Headless preview is the per-visual loop, so a "simple dashboard" should reach the user in one or two deploys, not one per tile.

• One reviewed change at a time. Small loops surface problems immediately.
• Read references lazily. The sibling skills carry deep references (DAX

patterns, visual recipes, style recipes). Open them only when a specific problem demands it — not as upfront reading.

• Don't gold-plate Phase 1. Exhaustive discovery and perfect theming are

Phase 3 concerns; they must never block the first ship.

Skill read order

Don't load every skill upfront. Pull each one in as its phase needs it, and stop at its Fast path section until you genuinely need more.