/metrics-pull

name: metrics-pull
description: "Pull snapshots from all configured metric sources, compute deltas against prior snapshots, flag unexplained signals, and draft evidence entries for canvas files. One entry point for all external product/market metrics."
metadata:
  instruction_budget: "47"
  framework_dependency: "mycelium"
  framework_dependency_note: "This skill is designed to run within the Mycelium framework (https://github.com/haabe/mycelium). Standalone use will skip the canvas state, theory gates, and harness behavior the skill assumes. Install: /plugin install mycelium@haabe-mycelium."

Metrics Pull Skill

Unified pull across all metric sources configured in `.claude/jit-tooling/active-metrics.yml`. Dispatches to per-source adapters (starting with `github`), normalizes to a shared schema, computes deltas, and drafts canvas evidence entries.

This skill is the L0/L1/L2/L5 evidence-gathering loop. Replaces manual "I checked the dashboard" reports with timestamped, sourced, diffable data.

When to Use

• Before `/mycelium:diamond-assess` at L0/L1/L2/L5, if the newest snapshot is >7 days old.
• After any public activity (launch, post, conference mention) — typically 24-48h later to capture the bump.
• Weekly baseline, regardless of activity.
• Ad hoc when the user wants a fresh read.

Precondition: .claude/jit-tooling/active-metrics.yml exists

If `.claude/jit-tooling/active-metrics.yml` does NOT exist:

1. Tell the user: "No metric sources are configured. Running `/mycelium:metrics-detect` first." 2. Invoke `/mycelium:metrics-detect` (or follow `${CLAUDE_PLUGIN_ROOT}/jit-tooling/metrics-detector.md`). 3. After detection completes, return to this skill.

Workflow

Step 1: Load configuration

Read `.claude/jit-tooling/active-metrics.yml`. Filter to sources with `status: active`. For each, verify the adapter file exists at `${CLAUDE_PLUGIN_ROOT}/jit-tooling/metrics-adapters/<source>.md`. If missing, follow `${CLAUDE_PLUGIN_ROOT}/jit-tooling/metrics-adapters/GENERATING.md` to generate it.

If `confirmed_by_user: false`, ask the user to confirm the source list before proceeding.

Step 2: Dispatch adapters in parallel

For each active source, follow its adapter's "Pull" and "Normalize" sections. Adapters are independent — run them in parallel (bash jobs, multiple tool calls in one message).

Per-source handling:

• Honor the adapter's `credential_requirement`. If missing, skip the source and report to user; do not fail the entire pull.
• Honor the adapter's rate-limit and retry rules.
• If the adapter returns `fetch_status: partial`, include partial data but mark the snapshot.

Step 3: Save raw snapshots

For each source, write the normalized snapshot to:

.claude/evals/metrics/<source>/YYYY-MM-DD.json

Use today's date. If today's snapshot already exists, OVERWRITE (the skill is idempotent within a day). Create directories as needed.

Step 4: Load prior snapshots

For each source, find the most recent snapshot in `.claude/evals/metrics/<source>/` that is NOT today's. If none exists, skip delta computation for that source and note "first snapshot" in the report.

Step 5: Compute deltas

Apply the adapter's "Delta rules" section. Common patterns:

• **Cumulative counts** (stars, forks, total subscribers): current minus prior, plus days-elapsed.
• **Windowed metrics** (14-day views/clones): highlight the newest day not present in the prior window. Avoid raw window-to-window subtraction when windows overlap.
• **Ranked lists** (referrers, top_paths, top-reviewed items): report new entries, dropped entries, rank shifts ≥3 positions.
• **Ratios** (clone-to-star, view-to-clone, churn rate): report current vs prior, flag drift >20%.

Step 6: Flag unexplained signals

Each adapter defines what "unexplained" means for its source. Typically this is:

• **traffic class**: referrers not in `known_referrers` with `unique >= 5`.
• **events class**: unusual spikes (>3x prior window), new event types.
• **reviews class**: sudden rating changes, new-language reviews.
• **support class**: ticket category shifts, volume spikes.

Review and ticket text is classified by meaning (the problem or need the person describes), with the quote kept verbatim: a change of wording is not a change of problem, and the same problem in new words is not new (`${CLAUDE_PLUGIN_ROOT}/engine/reading-for-meaning.md`).

For unexplained signals, attempt the investigation hooks defined in each adapter (e.g., GitHub's HN search) before presenting to the user.

Step 7: Generate combined report

Write a markdown report to `.claude/evals/metrics/YYYY-MM-DD.md` (project-level, not per-source) with this structure:

# Metrics Pull: YYYY-MM-DD
Sources pulled: N active, M skipped (credential issue)

## <source 1 name>
Target: <target>
Prior snapshot: YYYY-MM-DD (N days ago)

### Summary
[primary_counts with deltas]

### [class-specific sections]
- traffic class: Traffic (windowed), Top Referrers, Top Paths
- events class: Event counts, ratios
- reviews class: Rating summary, new reviews, [repurposed fields under their declared interpretation]
- support class: Ticket volume, top tags

### Unexplained signals
[list or "none"]

### Notable patterns
[ratio drift, Goodhart flags, cross-source correlations]

## <source 2 name>
...

## Cross-source observations
[if applicable — e.g., "GitHub traffic up + Stripe new customers up on the same day"]

## Proposed Evidence Entries
[yaml blocks from Step 8]

Display the report to the user.

Step 8: Draft evidence entries

For each source, consult the adapter's "Canvas routing" section. Draft a candidate evidence entry for each applicable canvas file. Never auto-write — always present for user confirmation.

Example entry (GitHub → purpose.yml):

- type: "market_signal"
  summary: "GitHub owner/repo on 2026-04-16: 342 stars (+12), 47 forks (+2), 943 views / 286 unique, 693 clones / 240 unique over 14 days. Top referrers: reddit.com, n