Spoke

metrics-catalog

Catalog 1 — 102 seeded HR definitions with stable composite ids powering calculus soft validation.

Character

Every deck invents subtly different regrettable attrition numerators—you want one dictionary stamped into contracts.

Problem

External. KPI glossaries fracture between finance, TA, and people analytics; MCP agents hallucinate bogus metric keys.

Internal. Analyst stand-ups descend into numerator theology instead of insight.

Philosophical. Definitions deserve the same contract discipline as schemas.

Guide

Postgres-backed categories + HR metrics seeded from donor archives; public GET surfaces list/search/category flows; MCP discovery mirrors docs; calculus optionally warns when metricKey literals diverge (PAT-40 Phase 3 posture).metrics-catalog anchors methodology prose planned for enrichment (PAT-40-FU-A).

Abstract

Background. Fragmented KPI glossaries degrade benchmarking and AI tooling because enrichers mistrust ambiguous labels.

Methodology. Immutable composite ids (hr-metric.<category>.<slug>) keyed to curated rows backed by Drizzle accessors; MCP plus HTTP symmetrical contracts.

Scope. Dictionary only—does not ingest warehouses; ingestion remains toolbox.etl plus segmentation-studio.

Contribution. Gives calculus plus Insight Card routing deterministic handles with documentation hooks.

Evidence / Provenance. Donor commit 97510dce446b9657cb3640c09200ad1f237f432b annotated in README.

Plan

  1. 01

    Discover definitions

    LIST, SEARCH, and category routes for humans and agents before enriching envelopes downstream.

  2. 02

    Vendor into consumers

    Copy contracts/types.ts; lint analytics code against enumerated ids during CI.

  3. 03

    Compose with calculus

    Let stats-enrich warn or log unknown keys using catalog metadata as columns populate (PAT-40-FU-A).

  4. 04

    Plan enrichment

    Track PAT-40-FU-A for numerator typing and CI recommendations that auto-hydrate calculators.

Call to Action

Direct. curl list or search endpoints free today.

Transitional. Browse README category table listing the seeded 102 metrics.

Spoke I/O (visual language v1)

Every toolbox spoke shares the same abstract choreography: typed inputs on the left, distilled verbs in the center, typed outputs on the right, and (when relevant) cross-spoke HTTP composition along the bottom rail. Source package: @people-analytics-toolbox/spoke-illustrations.

Metrics catalogINPUTSMAIN ACTIONSOUTPUTSMetric definitionsMetricSpec[]Steward approvalsPublicationWorkflowNormalize + version metricsPublish tier catalogsTier=1 data sourcesDataSourceIndexVisualization catalogVizRecipeIndexAnalysis catalogAnalysisRecipeIndex↳ operator tier=NCOMPOSES WITHcalculus

Try it now

Copy this curl. Paste in any terminal. Public read — no auth needed.

metrics-catalog.list

GET

Public read sampling the HR metrics catalog.

curl -sS "https://people-analytics-toolbox.vercel.app/api/spokes/metrics-catalog/metrics?limit=5"

Vendor the contract

The Zod contract is the source of truth. Vendor a copy into your consumer app — you keep it; we don't break it underneath you. Re-vendor when the version bumps.

// Vendor canonical types:
// src/spokes/metrics-catalog/contracts/types.ts

Source path: src/spokes/metrics-catalog/contracts/types.ts · GitHub

Try in Dev ConsoleRead the explainerMetric-market uses catalog handlesBack to all spokes

Failure

Agents emit nonsense metric names; calculators drift from Finance truth unnoticed.

Success

Canonical ids unify decks, MCP tools, and calculus envelopes—fewer synonyms and sharper governance.