metric-change-attribution
Skill1 starsChanged 3 months agoMITView on GitHub
Use when a metric moved between two periods (week-over-week, month-over-month, pre/post, A-vs-B) and you need to attribute WHY — which dimension members, segments, or factors drove it, ranked and drilled to root cause. Covers ratio/rate metrics (reach rate, CTR, conversion, retention, win rate, ARPU) and additive totals (revenue, events, DAU). Triggers: "why did X change", "what drove the drop/spike", "归因", "解释度", "拆解 WoW/MoM 变化", "which segment caused the change", "attribute the change".
In this repository12 other files it gives its agents.
- agent-fleet-guardSkill
- audience-briefSkill
- blind-ab-verifySkill
- change-triageSkill
- codex-review-gateSkill
- group-discussion-reviewer-methodologySkill
- group-discussion-reviewerSkill
- lark-comment-loopSkill
- lark-peer-feedback-draftingSkill
- meeting-notesSkill
- session-handoffSkill
- skill-evolve-loopSkill
The file
We split this skill into the rules it gives an agent
1 rule. About 0 are common, 1 is distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 31
NOT for: forecasting, single-series anomaly-point detection, or causal inference beyond decomposition of an observed change.
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Period-over-Period Metric-Change Attribution
A metric moved between two periods. This skill attributes why: it ranks the dimension members that drove the change (解释度/ep), optionally splits a ratio into multiplicative factors (structure × quality), drills the top contributor level by level to the root, and classifies old/new turnover at the leaf — while guarding against the dual-source denominator trap.
Metric-agnostic and config-driven: the same engine works for ratio metrics (numerator/denominator) and additive totals (a single measure). You declare the metric, dimensions, and sources in a small YAML config; you do not edit code.
When to use
- Two comparable periods of the same metric, sliceable by ≥1 categorical dimension.
- You want "which segment/factor/item is responsible", ranked and drilled.
- NOT for: forecasting, single-series anomaly-point detection, or causal inference beyond decomposition of an observed change.
The 6-step method
- Declare a config — period (prev/curr), metric (ratio or additive), the
dimension hierarchy, sources + column maps. Copy
templates/analysis.config.yaml. - Validate + dual-source check — long-format sanity; confirm the deduplicated source is the denominator truth and any leaf "pool" source is direction-only.
- Score the top dimension — ratio: ep / 解释度 (sums to 100%); additive: Δ-share.
- (ratio, optional) factor split — log-decompose the rate into structure × quality.
- Rank, noise-filter, drill Top-1 — skip near-zero-magnitude noise; recurse into the top contributor to the next level.
- Leaf turnover — at the leaf, classify each member expired / shrinking / stable / ramping / new; a pool-backed leaf attributes by the driver's Δ-share.
Quickstart
# run the worked example (bundled synthetic reach-rate sample):
python scripts/run_analysis.py --config examples/reach-rate.config.yaml
# your own analysis:
cp templates/analysis.config.yaml my.yaml # fill it in
python scripts/run_analysis.py --config my.yaml --json out.json
# verify the engine (synthetic invariants + frozen golden regression):
python scripts/selftest.pyOr import the stateless engine directly: from scripts import attribution as A
(see signatures in scripts/attribution.py).
Choosing the metric mode
- ratio — the metric is
numerator / denominator(a rate). Rich path: ep/解释度- optional structure×quality factor split. Use for reach rate, CTR, conversion, retention, win rate, ARPU-as-rate.
- additive — the metric is a single total (revenue, events, DAU). Lighter path: each member's share of the absolute Δ.
Reading the output
run_attribution returns {overall, tree, dual_source, drilled_path, warnings}.
overall— the headline (大盘) metric fromtotal_selector, separate from the decomposed partition.- each tree node —
membersranked by |解释度|/|contribution| (withis_noise), the pickedtop1, and achild(the drill). 解释度 sums to ±100% per level. - leaf node —
turnoverlabels per member. - a positive 解释度 means the member pushed the aggregate in the direction it
moved (a drag if the metric fell); negative means it pushed the other way
(reverse support).
metric.directiondrives the drag/support wording.
Critical correctness rules
- Dedup source is the only valid denominator. A finer "pool" source double-counts across overlapping segments (national/cross-segment drift) — never sum it as a denominator. A pool-backed leaf is attributed by the driver's Δ-share, not pool-ratio ep.
- Log factor decomposition fails at extreme/degenerate WoW (rate≈unchanged or a
factor ≤ 0) → it returns
status='unstable'; fall back to a magnitude narrative. - Drop near-zero-magnitude rows before trusting 解释度 — a tiny-volume row can show
a huge 解释度 and isn't a real driver. Tune via
noise.*.
References
- methodology-math.md — ep, log structure×quality, additive Δ derivations + failure modes.
- data-format-guide.md — long-format schema, the two-grain dual-source rule, validation.
- config-reference.md — every config field.
- worked-example-reach-rate.md — the 触达率 case mapped end-to-end on the bundled synthetic sample.
- pitfalls.md — drift double-count, log instability, noise rows, pp-vs-relative, leaf pool-ep.
Reference implementation (optional, out of scope here)
In a typical deployment this attribution feeds a separate rendering/orchestration
layer that turns the ep/解释度 output into a spreadsheet or report (period-string
replacement, formula tabs, conditional-format heat-maps, a narrative summary). That
rendering + orchestration layer is intentionally not part of this skill — this
skill is the portable, data-source-agnostic methodology + engine. See
worked-example-reach-rate.md for how the two relate.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

