dashboards-as-code

dashboards-as-code — migrate hand-authored dashboards to code, provably lossless

A hand-port of a dashboard fleet is silently lossy by default; nobody notices the dropped panel until an on-call engineer opens it mid-incident. This skill drives the migration through a round-trip fidelity gate so an as-code migration CANNOT land unless it is provably lossless.

The five-part harness

• Golden originals are IMMUTABLE — never hand-edited. One JSON export per dashboard, extracted from the running platform, is the diff oracle for the whole migration. Fixing a diff by editing the golden is falsifying the oracle.
• The emitter uses a generic panel factory, and its unknown-kind fallback FLAGS — never silently guesses. Common panel kinds (time-series, stat, gauge, table, logs, pie, bar) map through one factory; rows, template variables, and library-panel references are first-class. A panel kind the factory does not know routes to a default kind WITH the x_foundry_unverified flag set — the gate then refuses green on it, so it becomes a human-review item instead of a silent guess. A dashboard too irregular to emit cleanly may be hand-authored — it still goes through the same gate.
• The renderer compiles code → platform JSON, auto-discovering every compiled dashboard (a dashboard that fails to render is a gate failure, not a skipped file).
• The semantic-signature extractor reduces both sides to parity-bearing fields only — panels → {kind, queries, layout position}, template variables, datasource references. Byte comparison is useless (a newer builder SDK emits a different schemaVersion and injects defaults the old export lacks); the signature is the symmetric normalization. Layout is enforced — the right panels in the wrong places still fails.
• ONE shared definition of MATCH, two call sites. The signature() predicate in scripts/foundry-dashboard-fidelity.py is invoked by BOTH the per-dashboard convert self-verify (emit → compile → render → round-trip vs golden in one command) AND the fleet gate (gate --golden <dir> --rendered <dir> → N/N MATCH, fail-closed on any mismatch, missing pair, flagged panel, or zero pairs). A converter can never self-certify green under a looser rule than the merge gate enforces.