success-metrics-and-evidence

name	success-metrics-and-evidence
description	Defining measurable outcomes tied to evidence artifacts. Use when writing agent specs, closing waves, authoring handoffs, running release gates, or making any "done" claim.
when_to_use	Wave close, handoff authoring, release gate, agent spec authoring, any 'done' claim, scope definition.

Success Metrics and Evidence

When to Use

Load this skill when you need to:

• Author or review Success Metrics for an agent spec
• Define acceptance criteria for a wave, gate, or handoff
• Validate a "done" claim before marking work complete
• Write external-facing language that cites product capabilities (coordinate with security-compliance-evidence)

Core Principle

Every metric must be evidence-anchored: tied to a testable artifact, not a slogan.

Bad: "Deliver high-quality code" Good: "Zero regressions in your pytest (or CI) baseline after each PR merge — evidence: pytest [PRODUCT_CODE_ROOT]/ exit code 0 (or equivalent)"

Writing Success Metrics for Agent Specs

Use the "You're successful when:" pattern followed by 3-7 bullets.

Structure per bullet

- [Quantitative threshold OR binary check] — evidence: [specific artifact or command]

Evidence types (pick the most concrete available)

Evidence Type	Example	When to Use
pytest suite	pytest [PRODUCT_CODE_ROOT]/ -q — N tests pass, 0 fail	Code correctness, regression gates
Playwright spec	tests/e2e/*.spec.ts — smoke pass	Frontend workflow validation
Gate report	docs/gates/<milestone>_gate_report.md — PASS	Milestone promotion
Memory log ID	HQ-YYYYMMDD-NNN status=done	Decision or task closure
Claims matrix row	CL-006 status=approved_now	External messaging approval
Artifact existence	File at path/to/artifact.md exists and is non-empty	Documentation deliverables
RT-006 row	Roundtable action register item — status closed	Roundtable follow-through
Handoff YAML	Bound shared_context/handoff_*.yaml or pack_private/handoff_*.yaml accepted	Cross-org delivery — not public pack shared_context/
Command output	Your stack’s service status command — required processes healthy	Operational readiness

Few-shot examples (role-specific)

Backend Architect Lead:

## Success Metrics

You're successful when:
- Zero regressions in pytest baseline after API changes — evidence: `pytest [PRODUCT_CODE_ROOT]/tests/ -q`
- All new endpoints have contract tests before merge — evidence: test file exists in `[PRODUCT_CODE_ROOT]/tests/test_<module>.py`
- API response times under 200ms for core routes at single-tenant load — evidence: benchmark log
- Schema migrations are reversible or have documented rollback — evidence: migration notes in PR

Frontend Developer:

## Success Metrics

You're successful when:
- All client pages render without console errors across target browsers — evidence: Playwright smoke specs pass
- PrimeReact component usage follows design system tokens, not inline styles — evidence: zero `style=` in JSX grep
- Bundle size delta under 5% per feature PR — evidence: Vite build output comparison
- Onboarding flow completes end-to-end without manual workarounds — evidence: E2E test pass

Validating "Done" Claims

Before marking any task, wave, or gate as done, run this checklist:

1. Metric exists — Is there a written success metric for this deliverable?
2. Evidence collected — Can you point to a specific artifact (test result, file, log ID)?
3. Threshold met — Does the evidence meet the quantitative threshold or binary check?
4. No silent gaps — Are there criteria you skipped or deferred? If so, log them with a next_action.
5. Cross-org impact — If the claim crosses orgs, is it logged in shared_context/ with an HQ- or XD- ID?

Linking to Claims Evidence Matrix

When success metrics touch external-facing language (marketing, sales, website):

1. Find the relevant row in your claims evidence matrix under [YOUR_PLANS_DIR]/ (not shipped in this pack)
2. Verify claim status is approved_now or conditional — if blocked_now, do not reference externally
3. Cite the claim_id (e.g. CL-NNN) in your metric's evidence field
4. If no matrix row exists for the claim, flag it — HQ Chief of Staff owns the matrix process

Revisit Triggers

Set a revisit trigger on any metric that depends on:

• A test suite count (baseline changes over time)
• A deferred item (e.g. e2e specs waived to a future milestone)
• An assumption about stack behavior (e.g. "single-tenant load" — changes if multi-tenant ships)

Certainty Tags on Metrics

Tag	Use when
known	Metric is proven by existing tests/artifacts
risk	Metric is plausible but depends on untested conditions
hypothesis	Metric is aspirational — no evidence path defined yet

If a metric is tagged hypothesis, it must have a next_action to either validate or remove it.

Stop Conditions

• Do not declare "done" without at least one evidence artifact per success metric
• Do not use percentage-based KPIs (e.g. "95% uptime") without defining measurement method and data source
• Do not copy metrics from external templates (Agency, DAIR, etc.) without mapping to [ORG_NAME] evidence paths