| name | score-spec |
| description | Evaluate a software specification for AI agent readiness using the 9-dimension quality scorecard. Use this skill whenever someone asks to score, evaluate, grade, or audit a spec before implementation begins — or asks "is this spec ready?", "can agents implement this?", or "what's missing from our spec?". Also triggers on requests to improve a spec, find ambiguities, or prepare a spec for AI-assisted development. This is the gate that must pass before pre-implementation begins.
|
Spec Quality Scorer
Evaluate a specification for AI agent readiness. Produce a weighted score across
9 dimensions and a prioritized improvement plan.
When to Use
- Before pre-implementation begins (the primary gate)
- After major spec revisions (to track improvement)
- When an implementation produces unexpected results (to diagnose root cause)
- When asked: "is this spec ready?", "score this spec", "what's ambiguous?"
Inputs
The spec file to evaluate. If not provided, look for: SPEC.md, spec.md,
README.md (if it contains requirements), or ask the user to specify.
Read the full spec before scoring. For large specs (>500 lines), read in sections.
The Scoring Rubric
Score each dimension 1–10. See rubric.md for detailed criteria per score.
| # | Dimension | Weight | Core question |
|---|
| 1 | Unambiguity | 25% | Could two agents read this and make the same implementation decision? |
| 2 | Completeness | 20% | Are all modules, models, failure modes, and cross-cutting concerns described? |
| 3 | Consistency | 15% | Do all sections agree with each other? |
| 4 | Verifiability | 15% | Can each requirement be turned into a passing/failing test? |
| 5 | Implementation Guidance | 10% | Does the spec say how to work, not just what to build? |
| 6 | Forward Traceability | 5% | Can a ticket reference a specific spec section? |
| 7 | Singularity | 5% | Does each requirement describe exactly one thing? |
| 8 | Failure Mode Coverage | 3% | Is the unhappy path as specified as the happy path? |
| 9 | Interface Contracts | 2% | Are inputs, outputs, and types defined at every stage boundary? |
Threshold: Weighted score ≥ 7.0 = implementation-ready.
Below 7.0 = do not begin implementation. Improve the spec first.
Scoring Process
- Read the full spec.
- For each dimension, identify 2–5 specific findings (evidence from the spec text).
- Score the dimension based on the findings. Do not round generously — a 7 means
"an agent could implement this without major divergence." A 5 means "significant
gaps that would cause two agents to produce structurally different code."
- Calculate weighted total.
- Identify the top 3 improvements by weighted impact.
Output Format
SPEC QUALITY SCORECARD
═══════════════════════════════════════════════════════
Spec: [filename]
Evaluated: [date]
DIMENSION SCORES
────────────────────────────────────────────────────────
# Dimension Weight Score Weighted
1 Unambiguity 25% X.X X.XX
2 Completeness 20% X.X X.XX
3 Consistency 15% X.X X.XX
4 Verifiability 15% X.X X.XX
5 Implementation Guidance 10% X.X X.XX
6 Forward Traceability 5% X.X X.XX
7 Singularity 5% X.X X.XX
8 Failure Mode Coverage 3% X.X X.XX
9 Interface Contracts 2% X.X X.XX
────────────────────────────────────────────────────────
WEIGHTED TOTAL 100% X.XX
VERDICT: [IMPLEMENTATION-READY ✓ / NOT READY ✗]
(Threshold: 7.0)
DIMENSION FINDINGS
────────────────────────────────────────────────────────
[For each dimension, 2–5 bullet points of specific evidence.
Quote or reference the spec section. Explain what's present
and what's missing. Be precise — vague findings are not actionable.]
TOP 3 IMPROVEMENTS BY IMPACT
────────────────────────────────────────────────────────
1. [Title] (+X.XX–X.XX weighted points)
What: [specific gap]
How to fix: [concrete action]
Affects: [which dimensions improve]
2. [Title] (+X.XX–X.XX weighted points)
...
3. [Title] (+X.XX–X.XX weighted points)
...
OVERALL ASSESSMENT
────────────────────────────────────────────────────────
[2–4 sentences. Would two independent agents produce compatible
implementations? What is the highest-risk gap? What should
happen before implementation begins?]
═══════════════════════════════════════════════════════
Calibration Notes
- Score 9–10: Exhaustive. Two agents produce nearly identical implementations.
- Score 7–8: Implementation-ready. Agents may differ in minor details only.
- Score 5–6: Significant gaps. Agents produce compatible-but-divergent code.
- Score 3–4: Major gaps. Agents will make conflicting architectural decisions.
- Score 1–2: Insufficient. Cannot be implemented without substantial clarification.
The most commonly overscored dimension is Verifiability — specs often describe
behavior clearly but without stating what a passing test would assert. If you can't
write a failing test directly from the spec text, score it lower.
The most commonly underweighted gap is prompt templates in LLM-powered systems.
If the system calls an LLM but the spec doesn't specify prompt structure, flag this
as the highest-impact gap regardless of which dimension it falls under.
Reference Files
rubric.md — Detailed scoring criteria with examples for each score level
