# Reporting Architecture > Use when the user says "our dashboards disagree", "build a scorecard", "board reporting", "what should we report", "metric definitions", "too many dashboards", "nobody trusts the numbers", "what's our source of truth for reporting". Builds the metrics dictionary with one definition and one owner per metric, then a layered reporting stack that stops the recurring definition argument. Writes workspace/reports/metrics-dictionary.csv. - Skill: `guerrilla2799/reporting-architecture` (Agent Skill) - Install (CLI): `npx skillmds@latest add guerrilla2799/reporting-architecture` - Raw SKILL.md: https://api.skillmd.com/api/skills/guerrilla2799/reporting-architecture/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Data & Analytics - Author: guerrilla2799 (https://skillmd.com/u/guerrilla2799) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/guerrilla2799/reporting-architecture --- # Reporting Architecture One metric, one definition, one owner. An undefined metric is not a measurement, it is a position in an argument. ## When to use - Two dashboards report different numbers for the same thing - Board or investor reporting needs building - Dashboard count is growing and trust is falling - Somebody proposes buying BI to solve a disagreement ## Inputs - Needs from user: every report currently in use, the metrics on each, who reads them, and the two reports that disagree - Reads: `workspace/reports/attribution-model.md`, `workspace/reports/lifecycle.md` ## Workflow ### 1. Run the definition test first Ask three people to define one important metric independently, in writing. Do this before building anything. Three different answers, which is the usual result, means the problem is definitional. No tool fixes that. A warehouse lets the same three definitions disagree faster and at higher resolution. ### 2. Build the metrics dictionary One row per metric. This is the artifact the whole skill exists to produce. ``` Metric | Definition (one sentence) | Formula | Source system | Object counted | Date field used | Filters and exclusions | Owner | Refresh cadence ``` The four columns that resolve almost every real disagreement: **object counted, date field used, filters, exclusions**. When two numbers differ, one of those four differs, and finding which one is the entire investigation. **Every metric has one named owner.** The owner arbitrates when a number is questioned. An unowned metric gets a new definition every time somebody builds a report. ### 3. Layer the reporting, three layers only | Layer | Audience | Cadence | Contains | |---|---|---|---| | **Operational** | The people doing the work | Daily or live | Queues, SLAs, what to act on today | | **Management** | Function leads | Weekly | Trends against target, stage conversion, what changed | | **Executive** | Board, exec team | Monthly or quarterly | Outcomes, efficiency, the small number of things that matter | Each layer has a different job, and mixing them produces a dashboard nobody uses. An executive view with operational detail is unreadable, and an operational view with only monthly rollups is useless. **One dashboard per layer per function.** Every additional dashboard is a maintenance liability and another place a definition can drift. ### 4. Write the executive scorecard to fit on one page ``` GTM SCORECARD: OUTCOME Pipeline created $n vs target $n n% Pipeline from $n Win rate n% prior n% Sales cycle, median n days prior n EFFICIENCY CAC payback n mo target <18 Cost per qualified meeting $n prior $n Stack spend / ARR n% band 4-8% SYSTEMS Tier 1 data coverage n% Speed to lead, median n min Attribution coverage n% Model: ``` The model line at the bottom is not optional. It is what makes the numbers above it interpretable, and its absence is what starts the argument. ### 5. Kill the metrics that reward the wrong thing | Stop reporting | Report instead | |---|---| | Records enriched | Cost per usable record | | Total leads in database | Tier 1 accounts with current data and mapped contacts | | Emails found | Verified deliverable contacts on target accounts | | Agent runs executed | Runs kept without edit | | Average eval score | Pass rate and gate trip rate, separately | | MQLs | Qualified opportunities and the stage rates behind them | | Number of integrations | Sync failure rate and tool utilization | | Dashboard count | Metrics with one agreed definition and a named owner | Each left-column metric rewards volume over value, and a team measured on it will produce more of the wrong thing competently. ### 6. Set the change protocol Definitions will need to change. Changing one silently invalidates every prior period. ``` A definition change requires: the owner's approval, a dated note in the dictionary, and a statement of which historical periods are affected. Never restate history silently. ``` ## Output - Writes: `workspace/reports/metrics-dictionary.csv`, `workspace/reports/scorecard.md` - Uses: `templates/metrics-dictionary.csv` - Prints: the definition test result, the dictionary, the three-layer map, the one-page scorecard, and the stop-reporting list ## Rules & quality bar - **Run the definition test before building anything** - **One definition, one owner, one refresh cadence per metric** - **Object counted, date field, filters, and exclusions are mandatory columns** - **Three layers, one dashboard per layer per function** - **The attribution model appears on every report that uses it** - **Never buy BI to solve a definitional problem** - **Definition changes are dated, approved, and state what history they affect** - **Publish the stop-reporting list.** Removing a bad metric is as valuable as adding a good one ## Related skills - Requires: `attribution-architecture`, `lifecycle-and-routing` - Routes from: `martech-stack-audit` when a purchase was proposed for a definitional problem - See also: `docs/metrics.md`, `docs/field-notes.md` story 5