agentleFS
aaronartistzhang-afkaaronartistzhang-afk/DailyWork/skills/metric-change-attribution/SKILL.md

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".

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
  1. Distinctive:

    NOT for: forecasting, single-series anomaly-point detection, or causal inference beyond decomposition of an observed change.

    line 31

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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

  1. Declare a config — period (prev/curr), metric (ratio or additive), the dimension hierarchy, sources + column maps. Copy templates/analysis.config.yaml.
  2. Validate + dual-source check — long-format sanity; confirm the deduplicated source is the denominator truth and any leaf "pool" source is direction-only.
  3. Score the top dimension — ratio: ep / 解释度 (sums to 100%); additive: Δ-share.
  4. (ratio, optional) factor split — log-decompose the rate into structure × quality.
  5. Rank, noise-filter, drill Top-1 — skip near-zero-magnitude noise; recurse into the top contributor to the next level.
  6. 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.py

Or 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 from total_selector, separate from the decomposed partition.
  • each tree node — members ranked by |解释度|/|contribution| (with is_noise), the picked top1, and a child (the drill). 解释度 sums to ±100% per level.
  • leaf node — turnover labels 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.direction drives 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.