metric_tree_design v1.0.0

name: metric_tree_design description: Design a metric tree: pick one top outcome, break it into drivers a team can move, check that the drivers add up or multiply out, assign owners and guardrails, and review the tree when a driver stops predicting the outcome. Use when someone needs a North Star and input tree, a revenue or pipeline decomposition, a support metrics structure, or a fix for a dashboard nobody can act on.

Metric Tree Design

Purpose

Turn one vague outcome ("grow revenue", "improve retention", "fix support") into a tree a team can work from. The top of the tree is one outcome metric. Under it sit drivers that explain the outcome, and under those sit inputs that one team can move this cycle. Every arithmetic level reconciles, every leaf has an owner, and every targeted branch has a guardrail. A tree that fails those tests is a poster, not a management tool.

The distinction that does the work: outcome metrics are lagging, shared, and slow. Input metrics are leading, controllable, and owned. The tree is the map between them.

Workflow

1. Pick the top outcome. One metric only per tree. Prefer a count of customers doing the core job (weekly active teams that ran a report, nights booked, orders delivered) over a ratio on its own and over revenue. A ratio can rise while the business shrinks, and revenue is the business outcome the tree serves, not a lever a product or support team pulls directly. Write the top metric as a full definition: formula, window, inclusion rules, source system. If two analysts would compute different numbers from the definition, rewrite it before going further.

1. Classify the first split as identity or cause. Ask how the children relate to the parent.

• Identity: the children sum, multiply, or weight-average to the parent by definition. Example: active teams split into new plus retained plus resurrected. Example: pipeline velocity equals opportunities times average deal size times win rate, divided by cycle length.
• Cause: the children are claimed to influence the parent but do not compose it. Label these edges as causal claims. They get tested, not reconciled. Mixing the two without labels is the most common tree error. An identity that does not reconcile is broken data or a missing category. A causal claim that does not hold is a wrong theory. The fixes are different.

1. Decompose one level at a time. For identities, use the formula itself as the split. For broader outcomes, use breadth, depth, frequency, and efficiency as a starting scaffold: how many customers, how much each one does, how often, and what share of attempts succeed. Stop splitting a branch when its leaves pass the controllability test: one named team can move the leaf within one review cycle with work it controls. Most useful trees are 2 to 3 levels deep, with 3 to 5 drivers at level 1 and no more than about 12 leaves total.

1. Run the five driver checks on every node. Arithmetic, controllability, lead time, definition, and game check. The full checks with pass and fail examples are in references/checks.md. A driver that moves after the parent is a diagnostic: keep it for explanation, never target it as a lever. A driver with a cheap gaming path gets its guardrail added before it gets a target.

1. Reconcile and run the validator. Give every node you can a current value. Run bin/tree_check.py on the tree JSON (format documented at the top of the script, three worked files in bin/examples/):

   python3 bin/tree_check.py bin/examples/product-tree.json
   python3 bin/tree_check.py bin/examples/sales-tree.json
   python3 bin/tree_check.py bin/examples/support-tree.json
   

The tool checks that sum, product, and weighted-average nodes reconcile within a tolerance (default 2 percent), prints sensitivity per child, and flags missing owners, missing guardrails, duplicate ids, single-child splits, and excess depth. A FAIL means the tree does not ship. Find the missing category, the double count, or the window mismatch behind the gap.

1. Rank branches and pick where to work. Use sensitivity, not enthusiasm. In an additive tree, a 10 percent lift in a child lifts the parent by 10 percent times the child share, so a 65 percent share branch is worth about 8 times an 8 percent share branch at equal lift and cost. In a multiplicative tree, a 10 percent lift in any factor lifts the parent by 10 percent if the others hold still, so rank by cost and risk of the lift. Rank by expected parent lift per unit of effort, write the evidence for each plausible lift next to the ranking, and target one or two branches per cycle, not every leaf at once.

1. Add guardrails before targets. For each targeted branch, name at least one counter-metric that must not get worse while the target rises. Standard pairs: signups with activation rate of those signups, ticket close speed with reopen rate and satisfaction, bookings with discount rate and early churn, activity with support tickets per active customer. When a target improves and its guardrail worsens for two cycles, treat the branch as gamed or the trade off as real. Either way the target, not the team, is the first suspect.

1. Review the tree when it stops predicting. Triggers: a driver hit its target and the parent did not move within the expected lag, the parent moved and no driver explains it, the guardrail moved against the target twice, a definition or instrumentation change broke comparability, or segment mix shifted. Check driver drift with the series mode:

   python3 bin/tree_check.py --series bin/examples/drift.csv --driver trial_signups --outcome activated_teams
   

This example flags DRIFT: trial signups tracked activations closely in the first half and stopped tracking them in the second half. Follow the review procedure in references/checks.md: rule out definition changes, instrumentation breaks, window mismatches, mix shift, and seasonality first, then retest, demote, replace, or segment the failing driver. Record the change and the reason on the tree itself.

Worked trees for product, sales, and support, with numbers that reconcile, are in references/worked-trees.md.

Output Contract

Deliver the tree as one document with all of these parts:

markdown
## Metric Tree: {top outcome}
- Top metric definition: {formula, window, inclusions, source}
- Business outcome it serves: {revenue, retention, or cost outcome, if different}
- Review cadence / triggers: {dates or trigger list}

### Level 1 drivers
| Driver | Type (identity / causal) | Formula or definition | Current value | Share or sensitivity | Owner |
|---|---|---|---|---|---|

### Leaves targeted this cycle
- {leaf}: target {value by date}, owner {team}, guardrail {metric and limit}

### Reconciliation
- {node}: children combine to {value}, parent {value}, error {percent} - PASS / FAIL

### Guardrails
- {target} paired with {counter-metric}: limit {value}

### Open causal claims
- {driver} is claimed to move {parent} because {evidence}. Test: {how and by when}.
- Review trigger: if {driver} moves and {parent} does not within {lag}, reopen this tree.

A tree delivered without the reconciliation section and the guardrail list is incomplete.

Operating Rules

1. One top metric per tree. A team that needs two trees (bookings and product value, for example) gets two trees with a stated link, not one tree with two roots.
2. Never present a benchmark range from another company as a target. Ranges for coverage, satisfaction, or resolution vary by segment, channel, and model. Compute planning ratios from local rates where a formula exists, for example required pipeline coverage is roughly 1 divided by the local win rate.
3. Report counts beside every rate. A conversion rate, retention rate, or within-SLA rate ships with its numerator and denominator, or it does not ship.
4. Identities reconcile or the tree does not ship. Causal claims get an evidence note and a test, or they are marked as untested beliefs on the tree.
5. Every leaf has exactly one owner. Shared ownership on a leaf means no ownership.
6. No target without a guardrail. No guardrail, no target, no exceptions for "trusted" teams. Gaming is usually ordinary people responding to the incentive in front of them.
7. Correlation is a screening signal, never proof that a driver causes the outcome. The drift tool flags where to look. The review procedure in references/checks.md decides what to change.
8. Date every tree and keep its change history on the document. When a driver is retired or demoted, write why. Future planning cycles read the history before proposing the same dead branch again.
9. Keep the tree small enough to review in one meeting. Past about 12 leaves, split by team or move diagnostics to an appendix.
10. If the data cannot support a level (no instrumentation, mismatched windows, definitions in dispute), draw the tree down to the level the data supports and list the missing measurement as an explicit work item. Do not fill the gap with estimated numbers presented as actuals.