Metrics

craft:metrics — usage-telemetry front door

Standalone session-owned skill. You (the session) probe the current repo's transcript directory, invoke the miner, and report the output paths. No worker agent is spawned. This skill is ADVISORY — an absent, empty, or malformed transcript directory produces a recorded no-op and exits 0; it is never a blocker.

Input: $ARGUMENTS (zero-argument; optional pass-through flags accepted if the user supplies them — see Step 1).

Shell entry: scripts/mine-transcripts.sh is a shell convenience wrapper around the same miner for direct terminal use (e.g. bash scripts/mine-transcripts.sh). It is equivalent to invoking this skill but bypasses the skill preamble checks.

---

Preamble — read-only probe

Before invoking the miner, confirm the environment and resolve where transcripts would live.

1. Plugin root

Confirm ${CLAUDE_PLUGIN_ROOT} is set and the entrypoint exists:

test -f "${CRAFT_ROOT:-${CLAUDE_PLUGIN_ROOT}}/engine/bin/usage-mine.js"

If the test fails, surface a diagnostic and stop — the plugin installation is incomplete.

2. Transcript directory

The miner resolves the transcript directory for the current working directory internally (cwd → dashes mapping). You do not need to construct or validate the path yourself. An absent or empty directory is within the miner's advisory contract — it writes a no-data report and exits 0. Never abort the skill on a missing directory.

---

Procedure

Step 1 — Mine

Run the miner with zero arguments (or forward any flags the user explicitly supplied):

node "${CRAFT_ROOT:-${CLAUDE_PLUGIN_ROOT}}/engine/bin/usage-mine.js"

Optional flags (pass through verbatim when the user supplies them):

Flag	Purpose
--dir <path>	Override the resolved transcript directory
--baseline <path>	Baseline report for delta comparison and drift detection — e.g. the committed docs/contributing/metrics-baseline.report.json snapshot
--threshold <n>	Relative-delta threshold for the drift signal (default 0.25); only used when --baseline is also supplied
--since <date>	Restrict to transcripts on or after this date
--prices <path>	Custom pricing table (JSON)
--no-inline	Exclude the main-loop usage group (included by default)

Passing --baseline docs/contributing/metrics-baseline.report.json compares the current run against the committed snapshot: report.json gains a drift array flagging any (phase, dimension) pair whose per-occurrence mean token cost or duration moved beyond --threshold relative to the baseline's mean — corpus-size-invariant, so re-mining a grown corpus is not drift; a phase with no baseline activity carries a null delta (rendered "new") — and report.md gains a "Phases drifted since baseline" section when any phase drifted. This is a prompt-regression signal only — advisory, never a gate (see error semantics below).

The bin writes two artefacts inside the repo and exits 0 in all handled cases:

• report.json — machine-readable usage summary (consumed by craft:init and by the workflow-improvement loop)
• report.md — human-readable narrative (cache performance, cost breakdown, model-routing recommendations)

Refreshing the committed baseline

docs/contributing/metrics-baseline.report.json is the drift reference. Refreshing it is a deliberate, reviewed act — never a side effect of running the miner:

1. Refresh when the prompt surface changed on purpose — a run that edited skills/ or agents/ lands with intentionally different per-phase economics, and drift measured against the pre-change baseline would flag the intended shift forever. The integrate phase offers this step when the merged run touched those paths.
2. Re-mine over the full transcript corpus, then copy report.json over docs/contributing/metrics-baseline.report.json and commit it in the same PR/change that altered the prompts (chore(metrics): refresh drift baseline), so the diff review sees old-vs-new economics side by side.
3. Never refresh to silence an uninvestigated drift flag — that converts the alarm into the regression.

---

Done

After the bin exits 0, report:

• Artefact paths: report.json and report.md (relative to the repo root)
• One-line summary: surface the cache-creation hotspot and the top model-routing recommendation read from the bin's stdout or from report.json (e.g. "Highest cache-creation overhead: implementation phase — consider an explicit checkpoint. Top recommendation: route reviewer to a lighter model tier.")

Downstream consumers of report.json:

1. Workflow improvement — review the cache and cost breakdown to tune phase ordering, checkpoint placement, and model-routing hints across the craft pipeline.
2. craft:init — the initialiser reads report.json to pre-fill model-routing suggestions and gate recommendations in a new named manifest.

---

Error semantics

Condition	Behaviour
Absent transcript directory	Advisory no-op: miner writes a zero-data report, exits 0; skill reports the no-data report paths and continues
Empty transcript directory	Same as absent — recorded no-op, exit 0
Malformed transcript files	Miner skips unparseable entries; exits 0 with a partial report; skill surfaces a warning from the bin's stderr and reports the partial paths
--dir path out of bounds	Miner enforces path containment, writes a no-data report, exits 0; skill reports the paths and continues
Plugin root missing	STOP; surface "engine/bin/usage-mine.js not found — check CLAUDE_PLUGIN_ROOT"; do not invoke the bin
Bin stderr output	Surface stderr diagnostic as a warning; report what artefacts are available and continue — the miner always exits 0
--baseline absent or unreadable	Drift is advisory: report.drift is empty and no "Phases drifted" section is rendered; exits 0 and continues — never a gate