Purpose
/verification:measure answers "did the claimed improvement actually happen, by how much?". It MEASURES a delta (before → after) against a baseline captured before the change. It is the measurable-delta twin of /verification:confirm (which confirms intent/outcome) and is distinct from a review gate (which reviews design quality for ship-readiness on an absolute axis).
Core rule: never claim improvement without a baseline captured before the change. If no baseline exists, report honestly, "Baseline not captured. Current measurement: X. Cannot quantify improvement.", and never fabricate a delta.
Two-phase model
The measurement mechanism is SSOT here; the planning stage routes to it when a plan states a measurable goal, /verification:confirm redirects improvement claims to it.
| Phase |
Stage |
Who invokes |
What it does |
baseline |
planning time (plan states a measurable goal) |
/verification:measure <family> baseline |
Capture pre-change measurements → store under the topic's memory-tier baselines/ + record baseline + target in the plan |
compare |
after the change (default phase) |
/verification:measure <family> |
Re-measure under the same conditions → compare to the stored baseline → verify the claim |
Baseline storage: the topic's memory tier. <memory_dir>/<slug>/baselines/ (default .work/), resolved per the topic-docs binding (${CLAUDE_PLUGIN_ROOT}/reference/topic-docs.md). Baselines are machine-bound measurements and are never committed; the plan artifact is contract-tier at <contract_dir>/<slug>/PLAN.md (default docs/topics/), a separate tier from the baselines. The plan records the baseline values + target; the comparison summary surfaces in the plan and the PR body.
Measurement tooling: use whatever harness the consuming project wires (BenchmarkDotNet, pytest-benchmark, a metrics collector); when none exists, run both phases manually per the context-file discipline. Do not add a harness speculatively.
Mode dispatch
Parse $ARGUMENTS for a metric family first, then a phase (baseline / compare; default compare).
| Signal |
Family |
Read |
performance, "is it faster", "before/after" runtime numbers, memory / allocations / throughput / latency |
performance |
context/performance.md |
metrics, "is it simpler/cleaner", complexity / coverage / CRAP / coupling / duplication |
metrics |
context/metrics.md |
No family argument → infer from the claim: runtime-resource claims → performance; code-shape claims → metrics. If the claim is ambiguous ("more efficient"), ask which resource before measuring.
Each context file owns its family's full discipline: claim-to-metric mapping, measurement methodology, report template, verdict vocabulary, and pitfalls.
Prerequisite. Green mechanical state (both phases)
Measuring broken code is meaningless, and a baseline captured on a broken tree poisons every later comparison. Before EITHER phase, baseline capture or compare, confirm the mechanical pass is green: reuse a /toolchain:check or /verification:confirm Stage-1 result from this conversation if nothing changed since; otherwise invoke /toolchain:check via the Skill tool when the toolchain plugin is installed, or run the project's own build/test command when it is absent. Do not reimplement build/test/lint here.
Integration
| Condition |
Action |
| An approved plan states a measurable goal |
Run the baseline phase BEFORE implementation |
Improvement claimed without data (in /verification:confirm, review, or conversation) |
Redirect here. performance or metrics per the claim |
| Verdict is DEGRADED or NOT CONFIRMED |
Surface immediately; the claim does not hold. Fix or withdraw it |
| Measurement complete |
Feed the comparison table into the /verification:confirm outcome report; surface the summary in the plan artifact / PR body |
What this skill does NOT do
- Does not confirm intent/outcome. "did we build the right thing" is
/verification:confirm (outcome / fix / refactor criteria).
- Does not review for ship-readiness. That's the project's review gate; the measure-delta vs review-for-ship boundary is stated in "Purpose" above.
- Does not capture baselines after the fact, a post-change "baseline" is not a baseline. Missing baseline → honest "cannot quantify", plus a current-state measurement for the record.
- Does not run the mechanical pass.
/toolchain:check owns build+test+lint; this skill only requires its result to be green.
Gotchas
- Baseline BEFORE the change, compared under the SAME conditions after. Condition drift invalidates the comparison, the run/warm-up/conditions methodology is owned by context/performance.md.
- Noise floor first. If the projected saving sits within run-to-run variance, the change is unmeasurable. Surface that before the work, not after (detail: context/performance.md).
- A drifting host needs more than a noise-floor warning. When the machine's own spread makes a wall-clock comparison meaningless (a bimodal no-op-spawn signature, arms that cannot be run in one pass, no drift-immune counter agreed), route to
/performance:snapshot when the performance plugin is installed: it qualifies the host before measuring, interleaves the arms within one run, ranks a drift-immune counter above any duration, and refuses a wall-clock claim this skill would still report with a warning. This skill remains SSOT for baseline capture, storage, and the compare mechanics that plugin builds on.
- Never fabricate numbers. No baseline, high variance, or differing conditions → INCONCLUSIVE / NOT CONFIRMED, stated plainly.
1---2name: measure3description: Verify a measurable-improvement claim against a baseline captured BEFORE the change. Two metric families (`performance`: wall time, memory, allocations, throughput, latency; `metrics`: complexity, coverage, coupling), each with a `baseline` phase at planning time and a `compare` phase after the change. Never claims improvement without a baseline (no baseline → honest 'cannot quantify'). Use when: 'is it faster', 'before/after', 'prove the improvement', 'did that actually speed it up', 'how much faster is it', 'measure this', 'capture a baseline', 'benchmark before and after', 'did complexity go down'; intent/outcome confirmation stays with /verification:confirm.4---56## Purpose78`/verification:measure` answers **"did the claimed improvement actually happen, by how much?"**. It MEASURES a delta (before → after) against a baseline captured before the change. It is the measurable-delta twin of `/verification:confirm` (which confirms intent/outcome) and is distinct from a review gate (which reviews design quality for ship-readiness on an absolute axis).910Core rule: **never claim improvement without a baseline captured before the change.** If no baseline exists, report honestly, "Baseline not captured. Current measurement: X. Cannot quantify improvement.", and never fabricate a delta.1112## Two-phase model1314The measurement mechanism is SSOT here; the planning stage *routes* to it when a plan states a measurable goal, `/verification:confirm` *redirects* improvement claims to it.1516| Phase | Stage | Who invokes | What it does |17|-------|-------|-------------|--------------|18| `baseline` | planning time (plan states a measurable goal) | `/verification:measure <family> baseline` | Capture pre-change measurements → store under the topic's memory-tier `baselines/` + record baseline + target in the plan |19| `compare` | after the change (default phase) | `/verification:measure <family>` | Re-measure under the same conditions → compare to the stored baseline → verify the claim |2021Baseline storage: the topic's memory tier. `<memory_dir>/<slug>/baselines/` (default `.work/`), resolved per the topic-docs binding ([`${CLAUDE_PLUGIN_ROOT}/reference/topic-docs.md`](${CLAUDE_PLUGIN_ROOT}/reference/topic-docs.md)). Baselines are machine-bound measurements and are **never committed**; the plan artifact is contract-tier at `<contract_dir>/<slug>/PLAN.md` (default `docs/topics/`), a separate tier from the baselines. The plan records the baseline values + target; the comparison summary surfaces in the plan and the PR body.2223**Measurement tooling:** use whatever harness the consuming project wires (BenchmarkDotNet, pytest-benchmark, a metrics collector); when none exists, run both phases manually per the context-file discipline. Do not add a harness speculatively.2425## Mode dispatch2627Parse `$ARGUMENTS` for a metric family first, then a phase (`baseline` / `compare`; default `compare`).2829| Signal | Family | Read |30|--------|--------|------|31| `performance`, "is it faster", "before/after" runtime numbers, memory / allocations / throughput / latency | **performance** | [context/performance.md](context/performance.md) |32| `metrics`, "is it simpler/cleaner", complexity / coverage / CRAP / coupling / duplication | **metrics** | [context/metrics.md](context/metrics.md) |3334No family argument → infer from the claim: runtime-resource claims → `performance`; code-shape claims → `metrics`. If the claim is ambiguous ("more efficient"), ask which resource before measuring.3536Each context file owns its family's full discipline: claim-to-metric mapping, measurement methodology, report template, verdict vocabulary, and pitfalls.3738## Prerequisite. Green mechanical state (both phases)3940Measuring broken code is meaningless, and a baseline captured on a broken tree poisons every later comparison. Before EITHER phase, `baseline` capture or `compare`, confirm the mechanical pass is green: reuse a `/toolchain:check` or `/verification:confirm` Stage-1 result from this conversation if nothing changed since; otherwise invoke `/toolchain:check` via the Skill tool when the `toolchain` plugin is installed, or run the project's own build/test command when it is absent. Do not reimplement build/test/lint here.4142## Integration4344| Condition | Action |45|-----------|--------|46| An approved plan states a measurable goal | Run the `baseline` phase BEFORE implementation |47| Improvement claimed without data (in `/verification:confirm`, review, or conversation) | Redirect here. `performance` or `metrics` per the claim |48| Verdict is DEGRADED or NOT CONFIRMED | Surface immediately; the claim does not hold. Fix or withdraw it |49| Measurement complete | Feed the comparison table into the `/verification:confirm` outcome report; surface the summary in the plan artifact / PR body |5051## What this skill does NOT do5253- **Does not confirm intent/outcome**. "did we build the right thing" is `/verification:confirm` (`outcome` / `fix` / `refactor` criteria).54- **Does not review for ship-readiness**. That's the project's review gate; the measure-delta vs review-for-ship boundary is stated in "Purpose" above.55- **Does not capture baselines after the fact**, a post-change "baseline" is not a baseline. Missing baseline → honest "cannot quantify", plus a current-state measurement for the record.56- **Does not run the mechanical pass**. `/toolchain:check` owns build+test+lint; this skill only requires its result to be green.5758## Gotchas5960- **Baseline BEFORE the change, compared under the SAME conditions after.** Condition drift invalidates the comparison, the run/warm-up/conditions methodology is owned by [context/performance.md](context/performance.md).61- **Noise floor first.** If the projected saving sits within run-to-run variance, the change is unmeasurable. Surface that before the work, not after (detail: [context/performance.md](context/performance.md)).62- **A drifting host needs more than a noise-floor warning.** When the machine's own spread makes a wall-clock comparison meaningless (a bimodal no-op-spawn signature, arms that cannot be run in one pass, no drift-immune counter agreed), route to `/performance:snapshot` when the `performance` plugin is installed: it qualifies the host before measuring, interleaves the arms within one run, ranks a drift-immune counter above any duration, and refuses a wall-clock claim this skill would still report with a warning. This skill remains SSOT for baseline capture, storage, and the compare mechanics that plugin builds on.63- **Never fabricate numbers.** No baseline, high variance, or differing conditions → INCONCLUSIVE / NOT CONFIRMED, stated plainly.
melodic-software