# Metric Change Attribution

> >-

- **Type:** Skill
- **Install:** `agentstack add skill-aaronartistzhang-afk-dailywork-metric-change-attribution`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [aaronartistzhang-afk](https://agentstack.voostack.com/s/aaronartistzhang-afk)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [aaronartistzhang-afk](https://github.com/aaronartistzhang-afk)
- **Source:** https://github.com/aaronartistzhang-afk/DailyWork/tree/main/skills/metric-change-attribution
- **Website:** https://aaronzhang.ai

## Install

```sh
agentstack add skill-aaronartistzhang-afk-dailywork-metric-change-attribution
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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
```bash
# 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](references/methodology-math.md) — ep, log structure×quality, additive Δ derivations + failure modes.
- [data-format-guide.md](references/data-format-guide.md) — long-format schema, the two-grain dual-source rule, validation.
- [config-reference.md](references/config-reference.md) — every config field.
- [worked-example-reach-rate.md](references/worked-example-reach-rate.md) — the 触达率 case mapped end-to-end on the bundled synthetic sample.
- [pitfalls.md](references/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.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [aaronartistzhang-afk](https://github.com/aaronartistzhang-afk)
- **Source:** [aaronartistzhang-afk/DailyWork](https://github.com/aaronartistzhang-afk/DailyWork)
- **License:** MIT
- **Homepage:** https://aaronzhang.ai

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-aaronartistzhang-afk-dailywork-metric-change-attribution
- Seller: https://agentstack.voostack.com/s/aaronartistzhang-afk
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.