common-sdlc-metrics git:20261029.c32fa3dA

Immutable. This exact content never changes and is served at /api/v1/blob/0cd1696e8b4d5e12.

---
name: common-sdlc-metrics
description: Define delivery metrics from authorized observations and labeled artifact/git proxies; use for DORA, SDLC outcomes, reporting, or control bands.
metadata:
  triggers:
    files:
      - "docs/ops/bands.yaml"
      - "artifacts/sdlc-metrics.md"
    keywords:
      - dora metrics
      - lead time
      - change failure rate
      - plan adherence
      - control band
      - delivery metrics
---

# SDLC Metrics Standard

## **Priority: P2 (MEDIUM)**

Measure handoffs, not keystrokes. A missing input is unavailable, never zero; a proxy is never a measurement.

## Use and verify

- Emit `artifacts/sdlc-metrics.md` at a workflow terminal state, alongside `artifacts/session-cost.md`.
- Direct delivery measures come only from the authorized local export `artifacts/metrics/delivery-observations.json`; never read it from the network or place it under `artifacts/runs/`.
- Load [the metrics schema](references/metrics-schema.md) for the report skeleton, input contract, and derivation details.
- Generate the report with `rtk pnpm metrics:report --json`; run `rtk pnpm test:metrics` for the metrics suite. Do not overwrite existing metrics/history artifacts.

## DORA

Measured rows require linked deployment/defect observations and complete relevant coverage.

- **Deployment frequency:** production deployments by `deployed_at`.
- **Lead time:** `first_change_at` to `deployed_at`.
- **Change failure rate:** deployments with a hotfix/rollback defect divided by eligible deployments. Without incident coverage, a deployment is not failure-free.
- **Time to restore:** `restored_at` minus `detected_at`; restoration beyond coverage or the report horizon is censored.
- Select deployment and incident populations by domain timestamps, never export `observed_at`. Use the half-open report period `[currentSince, currentUntil)`.
- Incomplete population coverage yields a partial count or unavailable rate, never a complete result.
- Without observations, keep measured DORA unavailable. Label deploy-tag frequency, commit-to-tag lag, and revert/fix-commit tag share as git proxies.

## Accepted-change measures

- Cohort accepted changes by acceptance time in `[currentSince, currentUntil)`. Bound review, wait, correction, and cost to linked submissions/attempts/revisions through acceptance; later revisions and post-acceptance work are separate activity.
- Complete totals require continuous declared kind+revision coverage across the linked lifecycle. Gaps, uncovered relevant events, and unresolved waits never imply zero or completion.
- Report human review effort per accepted change, completed and pending decision waits, correction rounds, first-pass acceptance, escaped defects/rollbacks, and cost per accepted change.
- Count escaped defect observations, including `remediation: none`, separately from affected, hotfix/rollback, and rollback deployment counts.
- Cost is per currency. Total cost requires complete lifecycle coverage and explicitly observed agent, human, and tooling components for every cohort member. Otherwise report observed component-level partials; never infer human cost from elapsed time.

## Evidence and control bands

- Every available value names its source and declares `measured` or `proxy`, sample size, coverage (`complete`, `partial`, `unknown`), and limitations. Git, document, and run-record derivations are proxies with unknown coverage.
- Report trends only against comparable previous-period coverage. Do not combine metrics into a productivity score or infer identity/effort from author names.
- Keep private reviewer identity and raw customer data out of exports. Source labels are attribution, not authenticated origin.
- Define bands in `docs/ops/bands.yaml` against a rolling baseline. Detect deterministically; route `log` → read-only `diagnose` → `propose`, within declared tools/routes and to a named owner.
- Use dismissals to tune bands; frequent breaches signal miscalibration, not urgency.
- New measured rows do not enter control bands until their source and baseline are separately reviewed.

## Anti-patterns

- Guessing unavailable values, promoting proxies, or treating missing coverage as zero.
- Using commit counts/lines of code as delivery outcomes or ranking individuals.
- Acting beyond a band's declared tools/routes or treating a frequent breach as urgent without recalibration.
- Measuring plan adherence without the committed `docs/srs/srs-task-list-[slug].md`.

## References

- [Metrics Report Schema and derivations](references/metrics-schema.md)
- [Control Bands Template](references/bands-template.yaml)

## Canonical terms

`artifacts/sdlc-metrics.md` · DORA · plan adherence · rolling baseline · `docs/ops/bands.yaml` · `report unavailable` · `artifacts/runs/<slug>/` · `artifacts/metrics/delivery-observations.json`