Specification

Expertise for working with software specifications.

What Makes a Good Specification

A specification describes the target state—what the system looks like when complete.

Specification IS	Specification is NOT
Target state description	Implementation plan
Design decisions (what)	Decision rationale (why)
Declarative statements	Narrative explanations

Core principle: Constrain design, open implementation.

Specify all user-visible decisions
Leave internal implementation choices to implementers
If an implementer must guess a design decision, the specification is incomplete

Anti-patterns:

Note: — If clarification needed, specification is unclear. Rewrite directly.
(Future), (v2) — Describes target state, not phases. Remove or split into separate spec.
(Optional) — Either required for target state or belongs in Non-goals.

Three Layers

Complete specifications address three layers:

Layer	Purpose	Key Question
Intent	Why this exists	What problem for whom?
Design	What to build	What boundaries, interfaces, behaviors?
Consistency	How to stay unified	What patterns for similar problems?

Intent Layer

Provides context for judgment calls:

Element	Role	Core
Purpose	What problem the system solves	✓
Users	Who uses it, what they accomplish	✓
Impacts	What behavior changes indicate success (drives priority)
Success criteria	What defines "done" and "working"
Non-goals	What is explicitly out of scope

Without intent, implementers make technically correct but misaligned decisions.

Design Layer

Defines observable behaviors and boundaries:

Element	Role	Format	Core
System boundary	What's inside vs outside	See Boundary types
User journeys	Task flows achieving impacts	Context → Action → Outcome
Interfaces	Contracts between internal modules	-
Presenter	How system presents to users	UI: colors, layout / CLI: output format / API: response structure
Behaviors	Outcomes for each state × operation	State + Operation → Result	✓
Error scenarios	How failures are handled	-	✓

Boundary types:

Type	Defines	Example
Responsibility	What system does / does not do	"Validates input; does not store history"
Interaction	Input assumptions / Output guarantees	"Assumes authenticated user; Returns JSON only"
Control	What system controls / depends on	"Controls order state; Depends on payment service"

Consistency Layer

Establishes patterns for uniform implementation (all items enhance quality, none required for minimal spec):

Concept	Role	Example
Context	Shared understanding	"This is event-driven"
Terminology	Same concept uses same name throughout	"Order" not "Purchase/Transaction/Request"
Pattern	Recurring situation → approach	"State changes via events"
Form	Expected structure	"Events have type, payload", "Primary: #FF0000", "Errors to stderr"
Contract	Interaction agreement	"Handlers must be idempotent"

Weave these into relevant sections rather than listing separately.

Implementation Standards (Optional)

For projects requiring code-level consistency across multiple contributors or extended development periods.

Category	Purpose	Examples
Architecture	Module boundaries and dependencies	Clean Architecture, Hexagonal, Layered
Design Patterns	Reusable solutions	Repository, Factory, Strategy
Testing Style	Test structure and conventions	Given-When-Then, Arrange-Act-Assert
Code Organization	Directory structure and naming	Feature-based, layer-based, naming conventions

When to include:

Multiple contributors work on the codebase
Development spans extended periods
Codebase requires shared conventions

When to skip:

Simple scripts or single-file utilities
Prototypes or proof-of-concept
Short-lived projects

Quality Criteria

Specification Rubric

Rate each item Y (yes) or N (no).

Intent Layer

#	Criterion	Required
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
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:

All Required Y → Specification is usable. Stop unless improving quality.
All items Y → Specification is complete. Stop.
Any Required N → Must address before implementation.
Non-required N → Address only if relevant to project scope.

Balance Check

Question	Design Decision (specify)	Implementation Detail (open)
User-visible?	Error messages, CLI output	Log format, variable names
Affects modules?	Interface signatures	Internal functions
Needs consistency?	Error handling pattern	Algorithm choice
Could misalign?	Business rules	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)

Warning signs of under-specification: vague terms ("appropriate", "reasonable"), undefined behavior for reachable states

Common Problems

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

Applying This Knowledge

Progressive Approach

Apply to both writing new specifications and improving existing ones. When improving, identify current phase and proceed from there.

Phase	Focus	Output	Confirm
1. Intent	Why and for whom	Purpose, Users, Impacts	Rubric #1-2 Y
2. Scope	What's included	Feature list, User journeys (Context → Action → Outcome)	List complete
3. Behavior	How it works	Feature behaviors, Error scenarios	Rubric #5-6, #8 Y
4. Refinement	Quality	Patterns, Contracts, Terminology	Rubric #7, #9-11 as needed

Rules:

Do not write Phase 3 details until Phase 2 is confirmed
Phase 2 defines user-facing flows; Phase 3 defines internal behaviors
Return to earlier phases when new understanding emerges
Specification is usable after Phase 3 (all Required Y)

When Reviewing

Assess against three layers:

Intent: Can I explain why this system exists and for whom?
Design: Can I predict behavior for any user action?
Consistency: Will similar situations be handled similarly?

Key questions:

Is this complete enough to implement without guessing?
Are all design decisions explicit?
Will two implementers produce compatible results?

Flag: missing layers, vague language, implementation details that should be open, design decisions that should be specified.

Splitting Content

Default: Keep everything in SPEC.md.

Use this decision table to determine when to extract content:

Decides	Expands	External	→ Action
Y	-	-	Keep in SPEC.md
N	N	-	Keep in SPEC.md
N	Y	N	May extract (summary + link)
N	Y	Y	Extract (link only)

Conditions:

Decides: Cannot understand what to build without reading this
Expands: Complete definition of a decision (all fields, all cases)
External: Maintained by different role/tool

Examples:

Content	Decides	Expands	External	→ Action
Feature behavior	Y	-	-	Keep
Decision table	Y	-	-	Keep
Error handling rules	Y	-	-	Keep
API endpoints (3-5)	N	N	-	Keep
Full DB schema (50+ fields)	N	Y	N	May extract
Complete test cases	N	Y	N	May extract
Figma design	N	Y	Y	Extract

When extracting:

SPEC.md keeps the decision/summary
Link: See [Schema](docs/schema.md) for field definitions
Detail documents follow same principles

Type	Location
Data structures	`docs/schema.md`
Visual design	`docs/design.md` or external
Test cases	`docs/tests.md`

When updating specifications:

First determine: decision or detail?
Decisions go in SPEC.md, details may go in referenced documents
If adding to external document, verify SPEC.md has the governing decision

Writing tip: Use tables (like this decision table) to define boundaries and rules. Tables make conditions explicit and reduce ambiguity.

Handling Uncertainty

Undecided design choices

Do not leave gaps. Instead:

Present options with tradeoffs
Request a decision
Document the choice

Incomplete information

Mark explicitly what is decided vs pending:

## Technical Stack

Decided:
- Runtime: Node.js >= 20

To be decided:
- Database: PostgreSQL or SQLite
  (depends on deployment target)

Conflicting requirements

Surface the conflict explicitly and request resolution rather than making assumptions.

spec-knowledge