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