grafana-jsonnet-refactor

What this skill does

# Grafana Jsonnet Refactor

Eliminate duplication and align existing Jsonnet dashboards with available unified libraries. Preserve behavior while modernizing legacy panels and standardizing patterns.

**Not suitable for**: Initial JSON to Jsonnet conversion (use `grafana-json-to-jsonnet`), content optimization (use `grafana-dashboard-optimize`), or Python report migration (use `grafana-report-to-dashboard`).

## Workflow with progress tracking

Copy this checklist and track your progress:

```
Refactor Progress:
- [ ] Step 1: Read refactor-checklist.md and align with conventions
- [ ] Step 2: Audit dashboard (panels, variables, datasources, patterns)
- [ ] Step 3: Choose refactor mode (direct/wrapper/hybrid)
- [ ] Step 4: Normalize config and shared selectors
- [ ] Step 5: Replace panels with unified constructors
- [ ] Step 6: Organize file structure (imports → config → variables/helpers → panels → rows → dashboard)
- [ ] Step 7: Compile and verify in Grafana
```

**Step 1: Read refactor-checklist.md**

Load `references/refactor-checklist.md` to understand local conventions and standards.
If the dashboard belongs to a specific repo or stack, review the local Jsonnet defaults and docs in the working directory (datasource config, time range, variables, panel types).

**Step 2: Audit the dashboard**

List all panels, variables, datasources, and identify repeated patterns. Note which panels use local helpers vs unified libraries, and whether annotations or dashboard metadata (`__inputs`, `__requires`, `schemaVersion`, `graphTooltip`, `version`) are present.

**Step 3: Choose refactor mode**

Select approach based on dashboard size:
- **Direct migration**: Remove helpers, use unified libs directly (recommended for small dashboards)
- **Wrapper pattern**: Keep helper signatures, call unified libs internally (for large dashboards with many callsites)
- **Hybrid**: Mix approaches where needed

**Step 4: Normalize config and shared selectors**

Extract common configuration (datasource, pluginVersion, timezone, and time range when present) into a `config` object.

**Step 5: Replace panels with unified constructors**

Replace local helpers with `panels.*Panel()` constructors. Apply `standards.*` for units/thresholds and `themes.*` for timeseries styling. Add `id` and `gridPos` via `panels.withIdAndPatches(...)` or `+ { id, gridPos }`.
For styling and table/override patterns, load `references/visual-style-guides.md`.

**Step 6: Organize file structure**

Structure the file: imports → config → constants → variables → selectors/helpers → panel wrappers → panels → rows → annotations → dashboard. Keep all panel definitions as `local` variables in the single file.

**Step 7: Compile and verify**

Run the repo's build/compile script if available. Fix any errors. Verify panel count and layout match the original dashboard in Grafana.

## Guardrails

- Preserve metric semantics and layout intent.
- Avoid broad rewrites; focus on de-duplication and standards alignment.
- Keep a single file; do not create dashboard-specific lib files.
- Only update shared lib files for truly reusable components.
- Do not run `jsonnetfmt` / `jsonnet fmt` on generated Jsonnet files.

## Quality checklist

- [ ] Build/compile succeeds (project script if available).
- [ ] Panel count and layout match the original dashboard.
- [ ] Units and thresholds use `standards.*`.
- [ ] Queries use `prom.*` helpers where applicable.
- [ ] No dashboard-specific lib files exist in final output.
- [ ] `__inputs` / `__requires` and manual import lines preserved when present.
- [ ] Variables return values in Grafana; no duplicate or extra variables.
- [ ] Regex filters preserved or added where needed.
- [ ] Row membership is correct (`gridPos.y` aligns to row `gridPos.y`, and rows include panels).
- [ ] Annotations remain consistent and intentional.
- [ ] Dashboard metadata (`schemaVersion`, `graphTooltip`, `version`) preserved when present.

## Minimal single-file skeleton

```jsonnet
local g = import 'github.com/grafana/grafonnet/gen/grafonnet-latest/main.libsonnet';
local helpers = import '../lib/helpers.libsonnet';
local layouts = import '../lib/layouts.libsonnet';
local panels = import '../lib/panels.libsonnet';
local prom = import '../lib/prometheus.libsonnet';
local standards = import '../lib/standards.libsonnet';
local themes = import '../lib/themes.libsonnet';

// Provisioning mode (real UID). For manual import, switch to ${DS_*}.
local DATASOURCE_UID = '<prometheus-uid>';
// local DATASOURCE_UID = '${DS_PROMETHEUS}';

local config = {
  datasource: { type: 'prometheus', uid: DATASOURCE_UID },
  pluginVersion: '12.3.0',
};

local qpsStat = panels.statPanel(
  title='QPS',
  targets=[prom.instantTarget('sum(rate(http_requests_total[1m]))', '')],
  datasource=config.datasource,
  unit=standards.units.qps,
  pluginVersion=config.pluginVersion
);

g.dashboard.new('Dashboard')
+ g.dashboard.withPanels([qpsStat])
```

## References (load as needed)

- `references/visual-style-guides.md`
- `references/full-refactor-playbook.md`
- `references/refactor-checklist.md`
- `references/examples.md`