Specification Quality
Criteria and tools for evaluating specification quality.
Applicability Rubric
| Condition | Pass | Fail |
|---|---|---|
| Spec review requested | Need to assess spec quality | No review needed |
| Pre-implementation check | Spec about to be implemented | Already implemented |
| Quality gate | Spec must meet minimum bar before proceeding | Quality already verified |
| Improvement cycle | Iterating on spec after feedback | No prior version to compare against |
Apply when: Any condition passes
Core Principles
Specification Rubric
Rate each item Y (yes) or N (no).
Intent Layer
| # | Criterion | Required | Y/N |
|---|---|---|---|
| 1 | Purpose stated in one sentence? | ✓ | |
| 2 | Target users identified? | ✓ | |
| 3 | Impacts (behavior changes) identified? | ||
| 4 | Success criteria measurable or verifiable? |
Design Layer
| # | Criterion | Required | Y/N |
|---|---|---|---|
| 5 | Each documented feature has defined behavior? | ✓ | |
| 6 | Error scenarios cover all documented features? | ✓ | |
| 7 | Interaction points (internal and external) have explicit contracts? | ||
| 8 | Implementer can build without clarifying questions? | ✓ |
Consistency Layer
| # | Criterion | Required | Y/N |
|---|---|---|---|
| 9 | Key terms defined and used consistently throughout? | ||
| 10 | Recurring situations have named patterns? | ||
| 11 | Two implementers would produce compatible results? |
Passing Criteria:
- •Any Required N → Must address before implementation.
- •All Required Y → Specification meets Minimal level. Usable for small teams.
- •All Required Y + #3,4 Y → Specification meets Usable level. Stop unless improving quality.
- •All items Y → Specification meets Complete level. Stop.
- •Non-required N → Address only if relevant to project scope.
Quality Level Classification
| Level | Criteria | Suitable For |
|---|---|---|
| Minimal | All Required items Y (#1,2,5,6,8) | Small team, rapid iteration |
| Usable | All Required Y + #3,4 Y | Standard development |
| Complete | All 11 items Y | Multi-team, external consumers |
| Over-specified | All Y but Balance Check fails | Needs trimming of implementation details |
Balance Check (for review verification; see spec-principles Specify vs Leave Open for writing decisions)
| Question | Design Decision (specify) | Implementation Detail (open) |
|---|---|---|
| User-visible? | Error messages, CLI output | Log format, variable names |
| Affects module contracts? | Interface signatures | Internal functions |
| Could cause inconsistent interpretation? | Error handling pattern, Business rules | Algorithm choice, Performance optimization |
Test: "If implemented differently, would users notice or would modules conflict?"
Warning signs of over-specification: internal implementation details, algorithm choices (unless user-visible or cross-implementer consistency required)
Warning signs of under-specification: vague terms ("appropriate", "reasonable"), undefined behavior for reachable states
Common Problems (diagnosis; see spec-principles Anti-Patterns for prevention)
| Problem | Symptom | Cause | Fix |
|---|---|---|---|
| Missing intent | Technical tasks instead of user value | No purpose/users defined | Add intent layer |
| Undefined scenarios | Inconsistent edge case behavior | Incomplete state coverage | Enumerate all combinations |
| Over-specification | Implementer constrained unnecessarily | Implementation details included | Keep only observable behaviors |
| Inconsistent patterns | Similar problems solved differently | No shared conventions | Extract and reference patterns |
| Inconsistent terminology | Same concept has multiple names | No shared vocabulary | Define key terms, use consistently |
| Vague language | Ambiguous interpretation | "Handle appropriately" | Use specific values or criteria |
| Hidden assumptions | Works only in specific context | Unstated prerequisites | Make all assumptions explicit |
| Explanatory notes | "Note: because..." appears | Mixing rationale with spec | Rewrite as direct statement |
| Phase markers | "(Future)", "(v2)" in spec | Mixing planning with spec | Remove; spec describes target state |
Completion Rubric
Before Quality Assessment
| Criterion | Pass | Fail |
|---|---|---|
| Full spec read | Entire specification read and understood | Partial or skimmed reading |
| Project context known | Understand team size, project stage, consumers | No context about project |
| Target quality level selected | Chose Minimal/Usable/Complete based on context | No target level determined |
During Quality Assessment
| Criterion | Pass | Fail |
|---|---|---|
| All 11 items evaluated | Every rubric item scored Y or N | Items skipped or unclear |
| Evidence for each N | Each N has specific evidence from spec | N without justification |
| Balance Check completed | Over/under-specification assessed | Balance not checked |
| Common Problems scanned | All 9 problem types checked | Problems check incomplete |
After Quality Assessment
| Criterion | Pass | Fail |
|---|---|---|
| Prioritized findings | Required N items listed before non-required | Unprioritized list |
| Actionable recommendations | Each finding has a specific fix suggestion | Vague improvement advice |
| Clear verdict | Quality level determined (Minimal/Usable/Complete/Over-specified) | No clear assessment |