data-analytics
Use to understand the data an application houses and to identify high-value metrics, KPIs, and charts worth surfacing — the groundwork for dashboards. Invoke whenever exploring a schema/domain, planni
SKILL.mdskills/data-analytics/SKILL.md
GitHubData Analytics
Goal: build understanding of an app's data and propose the metrics/charts that would be genuinely useful — decision-driving, validated against real data — before any dashboard is built. The same method applies to any project.
Workflow
Work the steps in order. The ordering is the point: metrics proposed before the domain is understood, or shipped before the data is validated, are the two ways this work fails.
Step 1 — inventory the schema/domain
Check LEARNINGS.md beside this skill, when your copy keeps one, first — a catalog for
this project may already exist; extend it rather than re-deriving it. (This install's
catalogued projects: LOCAL.md beside this skill, when your copy keeps one — Existing
catalogs.)
- Identify the core entities, their tables/schemas, key columns, and the relationships (ownership, foreign keys, join/lookup tables, existing views/read models — pre-joined views are usually the best dashboard sources).
- Note the identity model (which id is canonical, how legacy/new ids map) — some apps
key much of their data on a legacy user id via an auth-bridge table; confirm which
id is canonical before building on it (this install's example:
LOCAL.mdbeside this skill, when your copy keeps one — Identity model example). - Note rough volumes and freshness (row counts, min/max of timestamp columns) — they determine whether a metric needs a rollup layer or can query the operational tables.
Step 2 — find the lifecycles and the business questions
- Most value lives in state over time: funnels, status transitions, created→completed timestamps. Locate the state machines and timestamp columns.
- Write down the questions the business actually asks of this data, per audience (internal admin vs partner vs end user) — a metric that answers no one's question is a vanity count. If the audience's questions aren't obvious, ask the user now (front-load; don't guess mid-build).
Step 3 — propose metrics, ranked by usefulness
For each candidate metric, state all four (a metric missing any of these isn't proposable yet):
- The question it answers and for whom (audience → also sets data-scoping/auth).
- The chart type it deserves: trend over time → line; funnel/stage conversion → funnel; categorical comparison → bar; current snapshot of one number → single stat; detail/ranking → table; distribution → histogram. Don't default everything to a stat card row.
- The grain (per user / partner / location / day) and roughly the query shape.
- The source (table/view/columns) — including whether the data is internal or needs an external integration (recalls, maintenance schedules, etc.).
Prefer a few decision-driving metrics over a wall of counts.
Step 4 — validate against real data (hard gate)
Before any metric is presented as buildable, run the candidate queries against a real database (local restore, staging):
- Do the columns actually exist, with the assumed types/values?
- Is the data populated — non-null, non-empty, covering the time range the chart implies? A column that exists but is 2% populated makes a chart that lies.
- Is the data current? A dev snapshot's empty/stale table proves nothing about prod (same trap as the code-quality "don't infer dead from stale data" rule) — check max(timestamp) against today before concluding either "no data" or "we have this".
- Spot-check that the numbers are plausible (compare a count against a known figure).
Mark each proposed metric: validated / data gap (what's missing) / needs external source.
Step 5 — map to UI and record the catalog
- Tie each surviving metric to the screen/section that would host it and its audience —
which also sets the scoping/auth (e.g. partner admins see only their
partner_id). - Flag where a rollup/materialized layer is warranted before heavy dashboarding (big scans on operational tables) — hand the query-tuning itself to database-optimization.
- Record the entity catalog, lifecycles, validated metrics, and gaps in
LEARNINGS.mdbeside this skill, when your copy keeps one — the catalog is the deliverable that outlives the session.
Common failure modes
- Dashboard-first: picking charts before understanding entities/lifecycles produces pretty vanity counts. Steps 1–2 come first, always.
- Proposing metrics on empty/stale/unpopulated columns — the schema says the column exists; only Step 4 says it has usable data. This is the most common way an analytics plan dies in review.
- Ignoring the audience/scoping — a metric without a "who sees this" has no auth model and no home screen; it isn't shippable.
- Wall-of-stats syndrome — 20 single-stat cards instead of 5 metrics that drive a decision. Rank and cut.
- Treating estimate/cost data as actuals — e.g. labor-time guides are legally "guide only"; present derived cost figures as non-binding ranges (see LEARNINGS).
- Skipping the existing catalog — re-deriving a domain that LEARNINGS already maps wastes the session and loses the recorded scoping rules.
Before you call this done
- Read (and extended, not duplicated) the project's LEARNINGS catalog.
- Every proposed metric names its question, audience, chart type, grain, and source.
- Every metric is marked validated / data-gap / needs-external-source, from queries run against real data — not schema-reading alone.
- Data gaps and rollup-layer needs are flagged explicitly.
- The catalog updates are written to LEARNINGS.md.
Capturing learnings (session-handoff protocol)
Accumulate per-project data knowledge in LEARNINGS.md beside this skill, when your
copy keeps one. On handoff / "update skills" / after data work: record the entity
catalog, ownership/scoping rules, useful timestamp/state columns, the candidate
metrics/charts identified (with their validation status), and known data gaps. Dedupe/merge, tag by project, and read it before
analytics work on a matching app.