add-kpi
Add a new KPI to data/kpis.ts with every defensibility field the README requires (definition EN+ML, source, owner, refresh, target, comparators, direction, civic domain, owner dept). Use when adding a
SKILL.md.claude/skills/add-kpi/SKILL.md
GitHubAdd KPI
Adds a new KPI fixture to data/kpis.ts with the full metadata schema. Every
published number on the dashboard must be defensible in public — that means no
shortcuts on this checklist.
The defensibility rule
From the README: "A number with no target is propaganda." Same logic applies to every other field. If you can't fill it, the KPI does not ship — it goes to a tracking issue instead.
Tooltip rule (non-negotiable): Every new piece of information added to the
dashboard MUST display a tooltip that surfaces its source data — at minimum
meta.source and, when available, meta.sourceUrl. A number the citizen can't
trace back to a primary source is not a public number. No tooltip = no merge.
Checklist (must all pass before commit)
- id is namespaced as
<domain>.<short-slug>(e.g.fiscal.debt-to-gsdp) - title (English) AND titleMl (Malayalam) both present
- domain is one of:
fiscal | health | education | livelihood | safety | transport | environment | sustainability | trust | delivery | other - ownerDeptId points to a real id in
data/departments.ts(andcontributingDeptIdsif cross-cutting) - value, unit, target all set. Target may equal an external
ceiling (FRBM, SDG, etc.) — note that in
comparators. - direction:
higher-betterorlower-better— drives ▲/▼ semantics inTrendArrow.tsx - trend, trendDelta, trendWindow describe the most recent change with a human-readable window (e.g. "vs last quarter")
- status is hand-set here (production version computes from distance-to-target + direction)
- comparators[] include at least one external benchmark (peer state, national avg, statutory target). A KPI without comparators looks like an unfalsifiable claim.
- meta.definition AND meta.definitionMl — a citizen and a journalist must read the same definition
- meta.source names the actual document/agency (not "internal dashboard")
- meta.sourceUrl when the source is publicly linkable — strongly preferred
- Tooltip present on the rendered card — the UI component for this data
point MUST show a tooltip exposing at least
meta.source(andmeta.sourceUrlas a link if set). This is mandatory for every new data point, not optional. - meta.owner is the accountable official's designation, not "Mission Control"
- meta.updateFrequency matches the source's actual cadence
- meta.lastRefreshed is an ISO datetime with
+05:30offset
Template
{
id: "<domain>.<slug>",
title: "<English title>",
titleMl: "<മലയാളം തലക്കെട്ട്>",
domain: "<civic-domain>",
ownerDeptId: "dept.<id>",
// contributingDeptIds: ["dept.<id>"],
value: 0,
unit: "<unit>",
target: 0,
direction: "higher-better", // or "lower-better"
trend: "flat", // up | down | flat
trendDelta: 0,
trendWindow: "vs <comparator window>",
status: "on-track", // on-track | slipping | off-track | improving
comparators: [
{ label: "<peer / benchmark>", value: 0 },
],
meta: {
definition: "<one sentence, citizen-readable>",
definitionMl: "<മലയാളത്തിൽ ഒരു വാക്യം>",
source: "<Department / agency / report name>",
sourceUrl: "<https://... if public>",
owner: "<Designation, e.g. Principal Secretary (Finance)>",
updateFrequency: "quarterly", // real-time|daily|weekly|monthly|quarterly|annual
lastRefreshed: "2026-05-18T09:30:00+05:30",
// methodologyUrl: "<https://... if a methodology note exists>",
},
},
After editing
- Append to
HEADLINE_KPISarray indata/kpis.ts - Bump
SEED_VERSIONindata/db.ts(forces a reseed on next cold start; existing index entries get wiped) - Run
deno task check— must pass fmt + lint + type check - Verify on
/— KPI card renders with correct trend arrow and status badge
Common mistakes
- Using
owneras the only ownership field — the legacy free-textownerstays for display, butownerDeptIdis the link the governance pages traverse - Skipping
definitionMlbecause "we'll translate later" — bilingual parity is a product promise, not a stretch goal - Setting
direction: higher-betterfor a metric like Infant Mortality Rate (it's lower-better — fewer dead babies is good) - Forgetting the
SEED_VERSIONbump — your new KPI silently won't appear because seed is idempotent on version match