Uncompromising empiricism
Metrics — measuring value, not activity
AIAD metrics inform decisions — they do not dictate them. Generated organically by the SDD cycle itself and persisted in .aiad/metrics/, they measure outcomes, never velocity.
Philosophy: outcome, not output
In a data-driven approach, the numbers decide. In AIAD's data-informed approach, the numbers illuminate: you optimise the value, not the metric, and you read trends rather than react to fluctuations. It is the framework's fifth value — uncompromising empiricism — applied to measurement itself.
The direct consequence: velocity is not measured. Counting story points or lines of code is measuring activity. SDD Mode measures what matters: does the delivered feature solve the problem, does it reflect the intent, and is the flow that produced it healthy? A good metric is actionable, understandable, comparable and honest — hard to game without genuine improvement (Goodhart's law).
The SQS — Spec Quality Score
The SQS is the cycle's entry metric: it determines whether the Execution Gate opens. Five scorable criteria — atomicity, precision, testability, non-ambiguity, defined scope — completed by a sixth, non-scorable criterion, the Stranger Test: would a person from outside the project understand the SPEC without any verbal context?
- SQS ≥ 4/5 → Gate open, the agent can start;
- SQS < 4/5 → back to revision, with a criterion-by-criterion remediation plan;
- SQS partially unscorable → score
?/5and Gate UNKNOWN — JNSP verdict, human decision required. Never any self-clearance.
An EARS-format SPEC whose strict lint (rules R1-R7) raises no violation earns a guaranteed +1 on the Testability criterion; a single violation forces that criterion to 0.
The SDD metrics
Specific to the cycle, they measure the health of the spec-anchored process. They are computed by /aiad retro and aggregated by the dashboards:
| Metric | What it measures | Target |
|---|---|---|
| Average SQS | Quality of the SPECs delivered over the period. | ≥ 4/5 — alert below 3.5/5 |
| Drift rate | SPECs out of sync with the code, detected by /sdd drift-check. | Downward trend |
| First-time success rate | Agent sessions that succeed on the first attempt, with no corrective iteration. | > 70% |
| Intent/delivery alignment rate | Intent Statements whose DRIFT CRITERION is honoured — checked at the Intent Workshop. | > 80% |
| Generated / manual code ratio | Share of code produced by agents vs written by hand. | > 80/20 |
A first-time success rate below 70% points to an outdated AGENT-GUIDE or poorly written SPECs; an alignment rate below 80% questions the quality of the Intent Statements themselves.
DORA Metrics
The four indicators from the DORA programme (Google) measure delivery performance. AIAD generates them organically from .aiad/metrics/deployments/ — no extra data entry. The command: /aiad dora.
| Metric | What it measures | Elite level |
|---|---|---|
| Deployment Frequency | How often code is deployed to production. | ≥ 1/day |
| Lead Time for Changes | Commit → production delay (AIAD also measures the extended Lead Time, intent → production). | < 1 hour |
| Change Failure Rate | Percentage of deployments causing an incident. | < 5% |
| MTTR | Mean time to recovery after an incident. | < 1 hour |
The report positions each metric on the Elite / High / Medium / Low scale, then traces back to verifiable AIAD causes: non-atomic SPECs, a Gate repeatedly closed, low SQS, governance skipped. Don't aim for Elite right away — one level per quarter is realistic progress, and an honest Change Failure Rate is worth more than an untraced hotfix.
Flow Metrics
Where DORA evaluates delivery, Flow Metrics evaluate the health of the value stream, from idea to deployment. The command: /aiad flow.
| Metric | What it measures | Benchmark |
|---|---|---|
| Cycle Time | Execution → deployment duration (85th percentile, robust to outliers). | < 3 days |
| Lead Time | Intent created → deployment duration, with a per-step breakdown. | < 2 weeks |
| Throughput | SPECs delivered per week. | Stable or rising |
| WIP | SPECs in progress simultaneously. | Explicit limit per PE |
| Flow Efficiency | Active time / total time. | 15-40% (normal) |
The most valuable analysis is the Lead Time breakdown, which locates the bottlenecks: a 15-day Lead Time with a 2-day Cycle Time reveals 13 days of hidden waiting — often between the Intent and the SPEC, or in Gate iterations. Little's law (Lead Time = WIP / Throughput) is the lever: to go faster, reduce WIP or increase Throughput.
The dashboards
| Command | Format | Usage |
|---|---|---|
/aiad dashboard | ASCII, in the chat | Team ritual — weekly (operational, 15-20 min) or monthly (strategic, 30-45 min, with stakeholders). |
/aiad dashboard-html | Static multi-page HTML in dashboard/ | Continuous steering — intents, SPECs, traceability, metrics, governance, drifts, changelog. Regenerated on demand, publishable (GitHub Pages). |
Both draw on the same .aiad/metrics/ persistence (deployments, specs, standup, drift, retro…). Three signals on the weekly dashboard trigger immediate action: a Cycle Time that doubles, an average SQS below 3.5/5, a Change Failure Rate above 15%.
An untraced deployment is not a hole to fill with an estimate — it is a signal that the process is leaking. The metrics commands alert explicitly rather than averaging over an incomplete sample.
Success indicators by responsibility
| Responsibility | Reference indicators |
|---|---|
| Product Manager | Outcome Criteria achievement > 70%, user satisfaction > 8/10, feature adoption > 60% within 1 month. |
| Product Engineer | Average SQS ≥ 4/5, intent/delivery alignment rate > 80%, Cycle Time < 3 days, drift trending down. |
| Agents Engineer | First-time success > 70%, agent adoption > 90%, generated/manual ratio > 80/20, false positives < 20%. |
| QA Engineer | Coverage > 80% backend / > 70% frontend, production bugs trending down (−20%/quarter), MTTD < 24 h. |
| Tech Lead | DORA improving, MTTR < 4 h, technical debt stable or shrinking. |
A faster review is not a better review: across 1.02 million pull requests studied in 2026, review involving agents saves time without gaining quality. Speed indicators (Cycle Time, Lead Time, Throughput) are therefore always read alongside quality and intent indicators (Change Failure Rate, drift, intent/delivery alignment). The gap between the productivity gain in writing code and the much smaller gain in delivering reliable software has a name — the Verification Tax — and it is what the upfront investment in the SPEC and the Gate seeks to reduce. See the QA Engineer's role and verification in the Validate loop.
The continuous improvement loop
Metrics only make sense plugged into a PDCA loop: identify a problem through the metrics, formulate a hypothesis, change at small scale, measure before/after, standardise or retry. Two commands support it:
/aiad retro— the retrospective collects Lessons Learned and Human Learnings, computes the iteration's metrics and commits to 1 to 3 actions at most, checked at the next retrospective;/sdd context— the post-session feedback loop compares the estimated Context Engineering Budget to the actual one (tokens, degradation, duration) and recommends optimisations for the next session.
Cadence: automatic daily monitoring, weekly team review (retrospective), monthly outcomes review (strategic sync), quarterly review of the framework itself. Start with five to seven essential metrics — measuring everything means steering nothing.