Use When
- measuring requirement quality and enforcing quantitative gates for ambiguity, completeness, traceability, volatility, and testability; use requirements-validation for content review.
- Use this procedure when the required source artefacts are available and
Requirements quality scorecardis the next lifecycle deliverable.
Do Not Use When
- Use
requirements-validationwhen that neighbouring route owns the decision or deliverable. - Do not invent missing project evidence, standards clauses, thresholds, or stakeholder decisions.
Required Inputs
| Artefact | Source or provider | Required? | Behaviour when missing |
|---|---|---|---|
| Requirements baseline, metric definitions, thresholds, and prior results | Requirements owner and quality standards | Yes | Stop the affected step, name the missing source, and return only a qualified gap record. |
Workflow
- Inspect the required inputs and log the exact sources, versions, and unresolved assumptions.
- Apply this skill's existing domain workflow and decision rules to produce
Requirements quality scorecard. - Stop when a required source, accountable decision owner, or deterministic test oracle is absent.
- Recover by preserving valid work, marking the blocked scope, and returning the narrowest qualified artefact plus the next evidence needed.
Outputs
| Artefact | Consumer | Acceptance condition |
|---|---|---|
| Requirements quality scorecard | Phase gate owner and remediation teams | Required sections are populated, source links resolve, and every material requirement or decision has an observable review or test oracle. |
Evidence Produced
| Evidence | Reviewer | Acceptance condition |
|---|---|---|
Source, decision, trace, and validation record for Requirements quality scorecard |
Requirements quality reviewer | Inputs used, decisions made, checks run, failures, and unassessed items are explicit. |
Capability and permission boundaries
Read and search are required. This procedure is read-only by default. Editing the reviewed artefact, publishing, production mutation, destructive action, spending, or certification requires explicit authority.
Degraded mode
Fallback: if a required file, reviewer, standard source, network check, renderer, or execution capability is unavailable, return the narrowest useful qualified result and mark the affected check not assessed; never convert an unassessed check into a pass.
Decision Rules
| Choice or condition | Action | Failure or risk avoided |
|---|---|---|
| A metric has no numerator, denominator, threshold, or sampling rule | Mark it unassessed until the metric contract is complete. | A quality pass based on unrepeatable scoring. |
| Required inputs and test oracles are complete | Continue through the existing workflow and record evidence. | A deliverable whose acceptance cannot be reproduced. |
| A mandatory source or owner is missing | Stop the affected branch and issue a qualified gap record. | Fabricated context or unauthorised decisions. |
Quality Standards
- Preserve stable identifiers and bidirectional traceability from project evidence to
Requirements quality scorecardand its acceptance checks. - Apply ISO/IEEE measures only with a named metric, method, threshold, evidence source, and responsible reviewer; run the anti-slop gate before release.
Anti-Patterns
- Producing
Requirements quality scorecardfrom assumed context. Fix: cite the project source or mark the scope blocked. - Accepting a material requirement without a deterministic oracle. Fix: add a measurable result, boundary, and verification method.
- Crossing into
requirements-validationwithout routing the decision. Fix: hand off the named input and preserve trace links. - Treating an unavailable check as passed. Fix: mark it
not assessedand state the release consequence. - Claiming standards, statutory, or stakeholder approval without evidence. Fix: cite the source and reviewer or qualify the claim.
References
Book-informed practice route
Use the scenario-spine and requirement-contract reference to measure verifiability, NFR specificity, uncertainty, and trace completeness.
Overview
Run this skill as the universal quality gate for both Waterfall and Agile pipelines. It reads all requirements artifacts, computes quantitative quality metrics, and issues a GREEN/YELLOW/RED gate verdict. No downstream activity (design, development, sprint planning) shall proceed until this gate passes at YELLOW or above.
When to Use This Skill
- After requirements baselining (
08-requirements-management) and traceability analysis (09-traceability-engineering). - As a pre-development quality gate in Waterfall workflows.
- As a sprint-entry quality gate in Agile workflows.
- Periodically during requirements evolution to track quality trends.
Quick Reference
- Inputs: All artifacts in
projects/<ProjectName>/<phase>/<document>/,projects/<ProjectName>/_context/vision.md - Outputs:
projects/<ProjectName>/<phase>/<document>/requirements_metrics_report.md - Tone: Quantitative, data-driven, pass/fail oriented
Input Files
| File | Source | Required? |
|---|---|---|
All *.md artifacts |
projects/<ProjectName>/<phase>/<document>/ |
Yes |
vision.md |
projects/<ProjectName>/_context/ |
Yes |
traceability_matrix.md |
projects/<ProjectName>/<phase>/<document>/ |
Recommended |
requirements_baseline.md |
projects/<ProjectName>/<phase>/<document>/ |
Recommended |
Output Files
| File | Contents | Destination |
|---|---|---|
requirements_metrics_report.md |
Per-metric scores, overall gate verdict, remediation guidance | projects/<ProjectName>/<phase>/<document>/ |
Core Instructions
Step 1: Read All Artifacts
Read every file in projects/<ProjectName>/<phase>/<document>/ and projects/<ProjectName>/_context/vision.md. Log each file path read. Build a consolidated requirements inventory with all requirement identifiers, their fields, and their trace links.
Step 2: Calculate Metrics
Compute each metric below. For metrics requiring historical data that is unavailable, note "Insufficient history -- baseline measurement recorded."
2a: Volatility Index
$$\text{Volatility Index} = \frac{R_{\text{changed}} + R_{\text{added}} + R_{\text{deleted}}}{R_{\text{total}}} \times 100$$
Where:
- $R_{\text{changed}}$: Requirements modified since last baseline.
- $R_{\text{added}}$: Requirements added since last baseline.
- $R_{\text{deleted}}$: Requirements deleted since last baseline.
- $R_{\text{total}}$: Total requirements in current baseline.
If this is the first baseline, record Volatility Index as 0% (initial measurement).
2b: Completeness Index
$$\text{Completeness Index} = \frac{R_{\text{complete}}}{R_{\text{total}}} \times 100$$
A requirement is complete when all mandatory fields are populated:
- Unique identifier
- Description with "The system shall..." phrasing
- Priority assigned
- Source stakeholder identified
- Acceptance criteria defined
- Requirement state assigned
2c: Ambiguity Index
Count occurrences of the following vague terms across all requirements:
| Prohibited Term | IEEE 830 Violation |
|---|---|
| fast | Missing quantitative performance target |
| easy | Subjective usability claim |
| intuitive | Undefined interaction metric |
| user-friendly | No measurable UX criterion |
| robust | Missing reliability specification |
| flexible | Undefined adaptability scope |
| scalable | Missing load/capacity targets |
| efficient | No resource utilization metric |
| appropriate | Undefined acceptance boundary |
| reasonable | Subjective judgment term |
| sufficient | Missing quantitative threshold |
| adequate | Undefined quality level |
| minimal | Missing lower-bound specification |
| maximize/minimize | Missing target value |
| support | Ambiguous capability claim |
$$\text{Ambiguity Index} = \sum \text{vague term occurrences}$$
Each occurrence shall be listed with the requirement ID and the offending term.
2d: Testability Score
$$\text{Testability Score} = \frac{R_{\text{testable}}}{R_{\text{total}}} \times 100$$
A requirement is testable when it has:
- Verifiable acceptance criteria with pass/fail conditions.
- Quantitative thresholds where applicable (response time, throughput, accuracy).
- No subjective terms from the Ambiguity Index list.
2e: Traceability Coverage
$$\text{Traceability Coverage} = \frac{R_{\text{traced}}}{R_{\text{total}}} \times 100$$
A requirement is traced when it links to both a business goal (upward) AND a test case (downward). Source this metric from traceability_matrix.md if available.
2f: Conflict Count
Count the number of unresolved contradictions between requirements. Source from traceability_matrix.md or perform a fresh scan for:
- Mutually exclusive behaviors for the same system element.
- Contradictory non-functional targets (e.g., "response time < 100ms" vs. "response time < 500ms" for the same operation).
- Conflicting priority assignments from different stakeholders.
2g: Data Quality Score
$$\text{Data Quality Score} = \frac{D_{\text{complete}} + D_{\text{consistent}}}{2 \times D_{\text{total}}} \times 100$$
Where:
- $D_{\text{complete}}$: Data requirements with all fields defined (type, format, constraints, validation rules).
- $D_{\text{consistent}}$: Data requirements with no naming or type conflicts across artifacts.
- $D_{\text{total}}$: Total data requirements identified.
2h: INVEST Compliance (Agile Only)
$$\text{INVEST Compliance} = \frac{S_{\text{passing}}}{S_{\text{total}}} \times 100$$
A user story passes INVEST when it satisfies all six criteria: Independent, Negotiable, Valuable, Estimable, Small, Testable. Apply only when user stories exist in projects/<ProjectName>/<phase>/<document>/.
Step 3: Apply Quality Gate Thresholds
Evaluate each metric against the following thresholds:
| Metric | GREEN (Pass) | YELLOW (Conditional) | RED (Fail) |
|---|---|---|---|
| Completeness Index | >= 95% | >= 80% | < 80% |
| Ambiguity Index | 0 | <= 5 | > 5 |
| Testability Score | >= 90% | >= 75% | < 75% |
| Traceability Coverage | >= 85% | >= 70% | < 70% |
| Conflict Count | 0 | <= 2 | > 2 |
| Data Quality Score | >= 90% | >= 75% | < 75% |
| INVEST Compliance | >= 90% | >= 75% | < 75% |
| Volatility Index | <= 10% | <= 25% | > 25% |
Step 4: Determine Overall Gate Verdict
The overall gate verdict is the lowest individual metric status:
- GREEN: All metrics are GREEN. Proceed to downstream activities.
- YELLOW: At least one metric is YELLOW, none are RED. Proceed with documented risk acceptance and remediation plan.
- RED: At least one metric is RED. Halt downstream activities. Return failing requirements to upstream skills for correction.
For YELLOW verdicts, the report shall include:
- Justification for proceeding despite deficiencies.
- Specific remediation actions with owners and deadlines.
- Escalation path if remediation is not completed on schedule.
Step 5: Generate Per-Metric Breakdown
For each metric, provide:
- The calculated score.
- The threshold status (GREEN/YELLOW/RED).
- A list of specific requirements contributing to deficiency (if not GREEN).
- Recommended remediation actions.
Step 6: Generate Output
Write projects/<ProjectName>/<phase>/<document>/requirements_metrics_report.md following the output format below.
Output Format
requirements_metrics_report.md
# Requirements Metrics Report: [Project Name]
**Generated:** [Date]
**Baseline:** BL-[PROJECT]-[VERSION]
**Standards:** IEEE 29148-2018, IEEE 982.1-2005
---
## Overall Gate Verdict: [GREEN / YELLOW / RED]
---
## Metrics Summary
| Metric | Score | Threshold | Status |
|--------|-------|-----------|--------|
| Completeness Index | N% | >= 95% | [GREEN/YELLOW/RED] |
| Ambiguity Index | N | 0 | [GREEN/YELLOW/RED] |
| Testability Score | N% | >= 90% | [GREEN/YELLOW/RED] |
| Traceability Coverage | N% | >= 85% | [GREEN/YELLOW/RED] |
| Conflict Count | N | 0 | [GREEN/YELLOW/RED] |
| Data Quality Score | N% | >= 90% | [GREEN/YELLOW/RED] |
| INVEST Compliance | N% | >= 90% | [GREEN/YELLOW/RED] |
| Volatility Index | N% | <= 10% | [GREEN/YELLOW/RED] |
---
## Per-Metric Detail
### Completeness Index: N%
[List of incomplete requirements with missing fields]
### Ambiguity Index: N
[List of requirements with vague terms, term identified]
### Testability Score: N%
[List of untestable requirements with deficiency noted]
[Continue for each metric...]
---
## Remediation Plan
| Priority | Requirement(s) | Issue | Action | Owner | Deadline |
|----------|----------------|-------|--------|-------|----------|
| Critical | REQ-xxx | Missing acceptance criteria | Add verifiable criteria | [Name] | [Date] |
---
## Historical Trend (if available)
| Date | Completeness | Ambiguity | Testability | Traceability | Verdict |
|------|-------------|-----------|-------------|--------------|---------|
| [Date] | N% | N | N% | N% | [Verdict] |
Common Pitfalls
- Gaming metrics: Marking requirements "complete" without genuine acceptance criteria inflates the Completeness Index. Audit field quality, not just field presence.
- Ignoring YELLOW status: A conditional pass is not a free pass. Every YELLOW metric requires a documented remediation plan with deadlines.
- Snapshot-only measurement: A single measurement is a snapshot, not a trend. Track metrics over time to detect quality degradation.
- Excluding NFRs: Non-functional requirements are often the hardest to make testable. Include them in all metric calculations.
Verification Checklist
- All eight metrics are calculated and reported.
- Each metric has a GREEN/YELLOW/RED status based on defined thresholds.
- Overall gate verdict equals the lowest individual metric status.
- Failing requirements are listed with specific deficiencies.
- Remediation plan is provided for all non-GREEN metrics.
- Vague terms list matches the prohibited terms catalog.
- INVEST Compliance is calculated only when user stories exist.
Integration
- Upstream:
08-requirements-management,09-traceability-engineering - Downstream: Development phase, sprint planning,
waterfall/08-semantic-auditing - Gate role: Universal quality gate for both Waterfall and Agile pipelines
Standards
- IEEE Std 29148-2018: Requirements quality characteristics.
- IEEE Std 982.1-2005: Measures to produce reliable software.
- IEEE Std 830-1998: Quality attributes for requirements (correct, unambiguous, complete, consistent, verifiable, modifiable, traceable).
- Laplante Ch.7.4: Requirements quality measurement.
- Wiegers Practices 19-20: Requirements quality metrics and process improvement.
- IEEE Std 610.12-1990: Terminology definitions.
Resources
references/metrics-catalog.md: Complete metrics catalog with formulas and benchmarks.references/quality-gate-thresholds.md: Gate configuration and escalation procedures.
Last Updated: 2026-03-07 Skill Version: 1.0.0