Skip to content

borghei/Claude-Skills / project-management/discovery/metrics-dashboard

metrics-dashboard

Verified

Designs a product metrics dashboard in four layers (North Star, inputs, guardrails, operational) with owners, comparisons and cadence, and audits the spec. Use when building a launch dashboard or pruning one nobody uses.

Metrics Dashboard

A dashboard architecture skill: which metrics go where, at which cadence, for which audience, with which visualization. Focused on producing the ONE artifact a team uses to make decisions — not the 30-chart dashboard nobody opens.

When to use this skill

  • New product / feature launch — what to instrument and watch
  • Existing dashboard audit — what to cut, add, refactor
  • Team-level OKR tracking — operational dashboard for the team
  • Exec readouts — board / monthly business review dashboard
  • Cross-functional alignment — what does "success" look like?

The 4 dashboard layers

  1. North Star — 1 metric that summarizes value delivered
  2. Input metrics (3-5) — the drivers of NS
  3. Guardrails (3-5) — what we DON'T want to sacrifice (counter-metrics)
  4. Operational metrics (4-8 per team) — what we actually act on weekly

A dashboard ≠ all metrics. A dashboard = these 11-22 metrics presented for fast decision-making.

Clarify First

Before designing the dashboard, settle the inputs below. When one is missing or vague and would change the result, ask about it; when it wouldn't, use a sensible default and say which one you used.

  • North Star metric: defined or not (it is the root of all 4 layers; if undefined, define it first via north-star-metric).
  • Audience: exec (board), team, all-hands, partner or ic (sets the max top-level metric count, from 12 for a team down to 3 for an IC).
  • Team structure: which teams act on this (operational metrics are 4-8 per team with named owners).
  • Available instrumentation: what data you actually capture (you can't show a metric you don't measure; bounds refresh cadence).

Ask about the two or three inputs that matter most for this request, not the whole list. If the user wants a result straight away, produce it and state your assumptions at the top.

Workflow

Step 1 — Confirm the North Star

Already defined? Use it. Not defined? See project-management/execution/north-star-metric.

A good NS:

  • Behavioral or business
  • Moves week-over-week
  • Hard to game without delivering real value
  • One number

Step 2 — Decompose to input metrics

For each NS, identify 3-5 inputs whose combined movement drives it.

Example for NS "Weekly Active Companies × Messages Sent per Company":

  • Acquisition rate
  • Activation rate (% reaching 50 messages in 14 days)
  • Retention rate (W4 cohort)
  • Expansion (adds users / channels)

Step 3 — Identify guardrails

What could move the NS up while damaging the underlying value?

Example guardrails:

  • Spam rate (if NS = messages, more messages can include spam)
  • User-reported complaints
  • Power-user churn (vs total churn)
  • Support ticket volume
  • Latency / error rate

Step 4 — Identify operational metrics per team

The 4-8 metrics each team needs to act weekly:

  • Growth team: funnel conversion, channel CAC, signup quality
  • Retention team: cohort retention, save-room saves
  • Platform team: SLO posture, on-call health, deploy freq
  • Trust & safety: spam reports, removed accounts, false-positive rate

Step 5 — Define visualization + cadence per metric

Each metric needs:

  • Visualization: line chart / funnel / cohort heatmap / bar
  • Comparison: vs prior period / vs target / vs cohort baseline
  • Refresh cadence: real-time / hourly / daily / weekly / monthly
  • Owner: named team

Step 6 — Audit the spec with dashboard_designer.py

Write the spec as JSON (shape in the script's --help; a sound and a flawed sample ship in assets/) and run the audit. Done when it exits 0 and the remaining warnings are either fixed or accepted with a reason.

python3 project-management/discovery/metrics-dashboard/scripts/dashboard_designer.py \
  --input project-management/discovery/metrics-dashboard/assets/sample_dashboard_spec.json --format markdown   # exit 0
python3 project-management/discovery/metrics-dashboard/scripts/dashboard_designer.py \
  --input project-management/discovery/metrics-dashboard/assets/sample_dashboard_spec_flawed.json --format markdown   # exit 1

Findings: fail for no North Star, no input metrics or no guardrails; warn for vanity terms (page views, total signups, total users, session count, time on site), missing owners, definitions or comparisons, guardrails without threshold alerts, over 6 inputs, more than 3 real-time metrics, too many top-level or per-team metrics; info for missing targets, under 3 inputs or guardrails, unconfirmed actionability. Exit codes: 0 no fail, 1 at least one fail, 2 bad input (missing file, invalid JSON).

Step 7 — Sunset stale metrics

Quarterly: remove metrics no team looked at; a dashboard nobody prunes stops being read.

Decision frameworks

Top-level limits per audience (exec/board 8, team 12 plus 8 operational per team, all-hands 5, partner 6, ic 3) and the vanity test ("if this moved 10% next week, what would we do?") are in references/dashboard-architecture.md section 14.

Anti-Patterns

The wall of metrics

Mistake: 30+ metrics on one screen, shown to every audience. Why it happens: Adding a chart is cheap and removing one feels like losing information. Instead: Keep to the audience limit above, give each audience its own view, and let the audit's top-level count check enforce it.

A North Star with no counterweight

Mistake: The dashboard has a North Star and inputs but no guardrails. Why it happens: Guardrails measure what you do not want, so nobody asks for them. Instead: Add 3-5 guardrails with threshold alerts, each tied to a way the North Star could be gamed (more messages could mean more spam). The audit fails a spec with none.

Orphan metrics

Mistake: Metrics with no owner and no review cadence. Why it happens: The dashboard is built as a project and handed to nobody. Instead: Name an owning team per metric and a review meeting per layer; the audit warns on every missing owner.

Real-time everything

Mistake: Every metric refreshes in real time. Why it happens: Real time feels more serious. Instead: Reserve real time for triage metrics (3 or fewer); most decisions run weekly. More detail and fixes: references/dashboard-anti-patterns.md.

Scope & Limitations

In Scope:

  • Dashboard architecture in four layers: North Star, 3-5 input metrics, 3-5 guardrails and 4-8 operational metrics per team
  • Visualization, comparison anchor, refresh cadence and named owner for each metric
  • Top-level metric limits by audience and the vanity-versus-actionable test
  • A spec audit for too many top-level metrics, missing guardrails, vanity metrics, missing owners and missing comparisons (dashboard_designer.py)
  • Audits of existing dashboards and mapping OKRs to metrics

Out of Scope:

  • Defining the North Star itself (see project-management/execution/north-star-metric/)
  • Building the dashboard in a BI tool or writing its queries (see data-analytics/business-intelligence/)
  • Event tracking and instrumentation (see marketing/analytics-tracking/)
  • Metric trees, cohort and funnel analysis on real data (see product-team/product-analytics/)

Important Caveats:

  • dashboard_designer.py audits a hand-written JSON spec. It reads no live data and does not check that a metric is instrumented.
  • Flags such as drives_ns and actionable_test_passed are self-reported in the spec. The tool trusts them.
  • Which metrics count as guardrails or vanity, and the targets behind them, stay team judgments.
  • Dashboards go stale. The skill expects a quarterly prune, which the tool does not schedule.

References

  • references/dashboard-architecture.md — layers, cadence, visualization patterns
  • references/dashboard-anti-patterns.md — common failures + fixes

Related skills

  • project-management/execution/north-star-metric — define THE one number
  • product-team/product-analytics — metric tree + cohort + funnel
  • product-team/ab-test-setup — experimentation
  • c-level-advisor/chief-data-officer-advisor — platform context

Files

FilePurpose
scripts/dashboard_designer.pyAudits a dashboard spec for layering, owners, comparisons and vanity terms
assets/sample_dashboard_spec.json, assets/sample_dashboard_spec_flawed.jsonRunnable specs: sound (exit 0) and flawed (exit 1)
assets/dashboard_spec_template.mdSpec worksheet to fill in
references/dashboard-architecture.md, references/dashboard-anti-patterns.mdLayers, cadence, visualization; failures and fixes
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall