Spec-Driven Development — Modular Specification Template
SKILL: Spec-Driven Development — Modular Specification Template
Purpose
This skill guides an agent in producing software specification documents that are:
- Grounded in IEEE standards (29148-2018, 1016-2009, 42010-2011)
- Modular and progressive — sections are added based on complexity tier
- Optimized for downstream consumption by coding agents or human engineers
Use this skill when asked to: write a spec, create a plan, define requirements, design a component, or document a feature.
Step 0 — Assess Complexity Tier
Before writing anything, determine the complexity tier by asking (or inferring from context):
| Signal | Tier |
|---|---|
| Single function, isolated component, no external deps | T1 — Simple |
| Multiple components, one integration point, team-scoped | T2 — Moderate |
| Cross-system, multiple teams, architectural decisions, non-trivial data model | T3 — Complex |
| Platform-level, org-wide, compliance/security requirements, multi-phase delivery | T4 — System |
Rule: When in doubt, start at T1. Add sections only when the user confirms they are needed or when the context clearly demands them.
Core Sections (All Tiers)
These sections are ALWAYS present regardless of complexity.
[CORE-1] Overview
Answers: What is this? Why does it exist? Standard: IEEE 29148 §6.2 — Purpose and Scope
## Overview
**Name**: [Component / Feature / System name]
**Status**: [Draft | Review | Approved]
**Owner**: [Team or person responsible]
**Last updated**: [Date]
### Purpose
[1–3 sentences. What problem does this solve? Who benefits?]
### Scope
[What is IN scope. Be explicit.]
### Out of scope
[What is explicitly NOT covered. Prevents scope creep.][CORE-2] Definitions
Answers: What do the words mean? Standard: IEEE 29148 §6.3 — Terms and Definitions
## Definitions
| Term | Definition |
|---|---|
| [Term] | [Precise definition as used in THIS document] |Agent instruction: Only include terms that are ambiguous or domain-specific. Skip obvious ones.
[CORE-3] Functional Requirements
Answers: What must the system do? Standard: IEEE 29148 §6.8 — Software Requirements
## Functional Requirements
Each requirement follows: [ID] [Priority] [Statement] [Acceptance Criterion]
| ID | Priority | Requirement | Acceptance Criterion |
|---|---|---|---|
| FR-01 | Must | [System shall...] | [Observable, testable condition] |
| FR-02 | Should | [System should...] | [Observable, testable condition] |
| FR-03 | Could | [System could...] | [Observable, testable condition] |Priority scale:
- Must: Non-negotiable. Failure = system failure.
- Should: Important but has a workaround.
- Could: Nice to have. Dropped first under pressure.
[CORE-4] Interfaces
Answers: What are the contracts at the boundaries? Standard: IEEE 29148 §6.8.4 — External Interface Requirements
## Interfaces
### Function / API Signature
[Language-agnostic or code-specific contract]
### Inputs
| Parameter | Type | Required | Description | Constraints |
|---|---|---|---|---|
| [name] | [type] | Yes/No | [what it is] | [valid range, format, etc.] |
### Outputs
| Field | Type | Description |
|---|---|---|
| [name] | [type] | [what it represents] |
### Errors / Failure modes
| Condition | Error | Behavior |
|---|---|---|
| [what went wrong] | [error code/type] | [what the system does] |T1 — Simple
Use when: Single component, function, or isolated UI element. One engineer. No external service dependencies.
Sections: CORE-1 · CORE-2 · CORE-3 · CORE-4
Example targets: A utility function, a UI component, a data transformation, a single API endpoint.
T2 — Moderate
Use when: Multiple components interact. Integration with one external service or team dependency. QA involvement expected.
Adds: CORE-1 · CORE-2 · CORE-3 · CORE-4 · [T2-1] Use Cases · [T2-2] Non-Functional Requirements · [T2-3] Data Model
[T2-1] Use Cases
Answers: How does an actor interact with the system? Standard: UML 2.x (OMG) — aligned with IEEE 29148 stakeholder requirements
## Use Cases
### UC-[N]: [Name]
**Actor**: [Who initiates]
**Precondition**: [What must be true before this starts]
**Trigger**: [What causes this flow to begin]
**Main Flow**:
1. [Actor does X]
2. [System responds with Y]
3. [Actor does Z]
4. [System confirms / returns result]
**Alternate Flows**:
- [Condition]: [What happens instead]
**Postcondition (success)**: [Observable state after happy path]
**Postcondition (failure)**: [Observable state after failure][T2-2] Non-Functional Requirements
Answers: How well must the system perform? Standard: IEEE 29148 §6.8.5 — Quality Requirements
## Non-Functional Requirements
| ID | Category | Requirement | Measurement |
|---|---|---|---|
| NFR-01 | Performance | [e.g., p95 latency < 200ms] | [how it's measured] |
| NFR-02 | Availability | [e.g., 99.9% uptime] | [monitoring metric] |
| NFR-03 | Security | [e.g., all tokens signed with RS256] | [audit / test] |
| NFR-04 | Scalability | [e.g., handles 10k concurrent users] | [load test threshold] |
| NFR-05 | Observability | [e.g., all errors emit structured logs] | [log format spec] |[T2-3] Data Model
Answers: What data does the system own or transform? Standard: IEEE 1016-2009 — Information Viewpoint
## Data Model
### Entities
**[EntityName]**
| Field | Type | Required | Description | Constraints |
|---|---|---|---|---|
| id | UUID | Yes | Primary identifier | Immutable |
| [field] | [type] | Yes/No | [description] | [constraint] |
### Relationships
[EntityA] 1──* [EntityB]: [description of relationship]
### State Machine (if applicable)
[State] ──[event]──> [State]T3 — Complex
Use when: Multiple teams involved. Architectural decisions with long-term consequences. Non-trivial data flows across service boundaries.
Adds: All T2 sections · [T3-1] Architecture · [T3-2] Component Design · [T3-3] Decision Log (ADR) · [T3-4] Risks
[T3-1] Architecture
Answers: How do the parts fit together? Standard: IEEE 42010-2011 — Architecture Description Viewpoints
## Architecture
### Context (System Boundary)
[Diagram or description of the system and everything it interacts with]
External actors:
- [Actor / System] → [interaction]
### Decomposition (Components)
[List or diagram of internal components and their responsibilities]
| Component | Responsibility | Owner team |
|---|---|---|
| [Name] | [What it does] | [Team] |
### Key Flows
[Sequence of interactions for the most critical paths]
Step 1: [A] calls [B] with [payload]
Step 2: [B] validates and stores in [C]
Step 3: [B] returns [result] to [A][T3-2] Component Design
Answers: How is each component structured internally? Standard: IEEE 1016-2009 — Composition + Logical Viewpoints
## Component Design
### [Component Name]
**Pattern**: [e.g., Repository, CQRS, Event-driven]
**Language / Runtime**: [e.g., TypeScript, Node 20]
**Dependencies**: [internal and external]
#### Internal Structure
[Modules, classes, or layers within the component]
#### Key Algorithms or Logic
[Describe non-obvious logic. Pseudocode if helpful.][T3-3] Decision Log (ADR)
Answers: Why was this designed this way? Standard: IEEE 42010-2011 — Rationale
## Decision Log
### ADR-[N]: [Decision title]
**Date**: [YYYY-MM-DD]
**Status**: [Proposed | Accepted | Deprecated | Superseded by ADR-X]
**Context**: [What situation forced a decision?]
**Options considered**:
1. [Option A] — [tradeoff]
2. [Option B] — [tradeoff]
3. [Option C] — [tradeoff]
**Decision**: [What was chosen and why]
**Consequences**: [What becomes easier? What becomes harder?][T3-4] Risks
Answers: What could go wrong? Standard: IEEE 29148 §6.5 — Constraints and Risks
## Risks
| ID | Risk | Likelihood | Impact | Mitigation |
|---|---|---|---|---|
| R-01 | [Description] | High/Med/Low | High/Med/Low | [What reduces it] |T4 — System
Use when: Platform or org-level change. Compliance requirements. Multi-phase delivery. Multiple product teams affected.
Adds: All T3 sections · [T4-1] Stakeholder Requirements · [T4-2] Compliance & Security · [T4-3] Delivery Phases · [T4-4] Dependencies & Assumptions
[T4-1] Stakeholder Requirements
Answers: What does each stakeholder need from the system? Standard: IEEE 29148 §6.6 — Stakeholder Requirements
## Stakeholder Requirements
| Stakeholder | Need | Priority | Linked FR/NFR |
|---|---|---|---|
| [Role] | [What they need, in their language] | Must/Should/Could | FR-0X |[T4-2] Compliance & Security
Answers: What external constraints apply? Standard: IEEE 29148 §6.8.6 — Constraints
## Compliance & Security
### Regulatory / Policy
- [Regulation]: [How the system satisfies it]
### Threat Model
| Threat | Attack Vector | Control |
|---|---|---|
| [e.g., Token theft] | [e.g., Intercepted JWT] | [e.g., Short TTL + refresh rotation] |
### Data Classification
| Data type | Classification | Handling requirement |
|---|---|---|
| [e.g., User email] | PII | Encrypted at rest, masked in logs |[T4-3] Delivery Phases
Answers: What ships when?
## Delivery Phases
### Phase 1 — [Name] (Target: [date/quarter])
**Goal**: [What capability is unlocked]
**Included**: [FR-01, FR-02, UC-01]
**Excluded**: [Deferred items]
**Definition of Done**: [Measurable condition]
### Phase 2 — [Name]
[Repeat structure][T4-4] Dependencies & Assumptions
Answers: What must be true for this to work? Standard: IEEE 29148 §6.5
## Dependencies & Assumptions
### Dependencies
| Dependency | Type | Owner | Risk if unavailable |
|---|---|---|---|
| [Service/API/Team] | Hard/Soft | [Owner] | [Impact] |
### Assumptions
- [Assumption 1]: If false, [consequence]
- [Assumption 2]: If false, [consequence]Agent Instructions
When using this skill, follow these rules:
- Always start with Step 0. Determine the tier before writing any section.
- Never include empty sections. If a section has nothing to say at this stage, omit it.
- Prefer tables over prose for requirements, risks, and data models.
- Requirements must be testable. Every FR must have an acceptance criterion that can be verified without talking to a human.
- ADRs are mandatory at T3+. Every non-obvious design choice needs a rationale.
- IDs are stable. FR-01 never becomes FR-02. Deprecated requirements are marked [REMOVED], not deleted.
- A spec is not done until the interfaces section has no ambiguous types. “object” or “any” are not types.
- When in doubt, make it T2. T1 underestimates complexity almost always.
Quick Reference — Section Map
| Section | T1 | T2 | T3 | T4 | Standard |
|---|---|---|---|---|---|
| CORE-1 Overview | ✓ | ✓ | ✓ | ✓ | IEEE 29148 §6.2 |
| CORE-2 Definitions | ✓ | ✓ | ✓ | ✓ | IEEE 29148 §6.3 |
| CORE-3 Functional Req | ✓ | ✓ | ✓ | ✓ | IEEE 29148 §6.8 |
| CORE-4 Interfaces | ✓ | ✓ | ✓ | ✓ | IEEE 29148 §6.8.4 |
| T2-1 Use Cases | ✓ | ✓ | ✓ | UML 2.x (OMG) | |
| T2-2 Non-Functional Req | ✓ | ✓ | ✓ | IEEE 29148 §6.8.5 | |
| T2-3 Data Model | ✓ | ✓ | ✓ | IEEE 1016 Info VP | |
| T3-1 Architecture | ✓ | ✓ | IEEE 42010-2011 | ||
| T3-2 Component Design | ✓ | ✓ | IEEE 1016 Comp VP | ||
| T3-3 Decision Log (ADR) | ✓ | ✓ | IEEE 42010 Rationale | ||
| T3-4 Risks | ✓ | ✓ | IEEE 29148 §6.5 | ||
| T4-1 Stakeholder Req | ✓ | IEEE 29148 §6.6 | |||
| T4-2 Compliance & Security | ✓ | IEEE 29148 §6.8.6 | |||
| T4-3 Delivery Phases | ✓ | — | |||
| T4-4 Dependencies | ✓ | IEEE 29148 §6.5 |