Specification Framework
Detailed structure for each layer of a specification.
Applicability Rubric
| Condition | Pass | Fail | |-----------|------|------| | Structuring new spec | Writing a spec from scratch | Spec structure already established | | Layer completeness check | Need to verify all layers are addressed | Layers are already complete | | Element selection | Deciding which elements to include | Elements already chosen | | Multi-layer coordination | Ensuring layers align with each other | Single-layer change only |
Apply when: Any condition passes
Core Principles
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
Layer Selection Guide
| Project Characteristic | Intent | Design | Consistency | Implementation Standards | |-----------------------|--------|--------|-------------|-------------------------| | Solo prototype | Core only | Core only | Skip | Skip | | Small team (2-5) | Full | Full | Terminology + Patterns | Optional | | Multi-team | Full | Full | Full | Recommended | | External API / Public contract | Full | Full | Full | Required |
Element Completeness Guide
| Design Element | When to Include | When to Skip | |----------------|-----------------|--------------| | System boundary | External dependencies exist | Self-contained utility | | User journeys | Multiple user-facing flows | Single-purpose tool | | Interfaces | Multiple internal modules | Monolithic implementation | | Presenter | User-facing output matters | Internal service | | Behaviors | Always (Core) | Never skip | | Error scenarios | Always (Core) | Never skip |
Completion Rubric
Before Applying Framework
| Criterion | Pass | Fail | |-----------|------|------| | Scope understanding | Know what the system does | Scope unclear | | Layer necessity evaluated | Determined which layers needed per project type | Blindly applying all layers | | Existing content assessed | Reviewed any existing spec content | Starting without context |
During Application
| Criterion | Pass | Fail | |-----------|------|------| | Intent before Design | Intent layer completed before Design details | Design written without Intent | | Core elements present | All Core-marked elements addressed | Core elements missing | | Boundaries explicit | System boundaries clearly defined | Boundaries implied or missing | | Layer selection justified | Layer depth matches project characteristic | Over/under-layered for context |
After Application
| Criterion | Pass | Fail | |-----------|------|------| | Intra-layer consistency | Elements within each layer do not contradict | Internal contradictions | | Cross-layer alignment | Design serves Intent; Consistency supports Design | Layers misaligned | | Element completeness | Included elements fully specified | Partial elements left incomplete |