skills/write-engineering-specifications/assets/specification-template.md

# Engineering Specification

## 0. Document control

| Field | Value |
|---|---|
| Project | |
| Feature/change | |
| Specification ID | |
| Version | |
| Date | |
| Status | Draft / In review / Approved / Superseded |
| Owner | |
| Reviewers | |
| Implementation target | Human developer / Coding agent / Team |

## 1. Executive overview

- Goal
- Problem
- User impact
- Technical impact
- Success measure
- Scope summary

## 2. Evidence and current-state audit

- Inspected sources
- Existing architecture and behavior
- Dependencies and constraints
- Strengths and invariants to preserve
- Known defects and risks
- Not verified

## 3. Scope control

### In scope

### Out of scope

### Create

### Modify

### Preserve unchanged

### Prohibited without approval

### Delete or deprecate

## 4. Decisions, assumptions, and blockers

| ID | Type | Statement | Evidence/rationale | Impact | Owner/status |
|---|---|---|---|---|---|

## 5. Functional requirements

| ID | Requirement | Trigger/input | Behavior/output | Priority | Dependencies | Verification |
|---|---|---|---|---|---|---|

## 6. Non-functional requirements

| ID | Quality attribute | Metric/standard | Conditions/workload | Verification |
|---|---|---|---|---|

## 7. Architecture and system design

- System context and boundaries
- Components and responsibilities
- Data and control flow
- Interfaces and dependencies
- State and persistence
- Security and privacy
- Failure handling and recovery
- Observability and operations
- Deployment and configuration

## 8. File and code impact

| Path/module | Current purpose | Required change | Constraints/invariants | Requirement IDs |
|---|---|---|---|---|

## 9. UI and interaction specification

- Surfaces and components
- Layout and tokens
- Copy and content rules
- States and validation
- Responsive behavior
- Accessibility
- Motion and interaction

## 10. Behavioral flows

For each flow: precondition → trigger → validation → processing → state/side effect → response → feedback → observability.

## 11. Edge and failure cases

| ID | Condition | Expected behavior | Recovery | Evidence/test |
|---|---|---|---|---|

## 12. Data, API, event, and integration contracts

## 13. Migration, rollout, rollback, and compatibility

## 14. Test and regression plan

| Test ID | Requirement IDs | Level | Preconditions/action | Expected result | Evidence | Owner |
|---|---|---|---|---|---|---|

## 15. Acceptance criteria

| AC ID | Requirement IDs | Criterion | Verification evidence | Status |
|---|---|---|---|---|

## 16. Risks and open points

| ID | Risk/open point | Likelihood | Impact | Mitigation | Owner/status |
|---|---|---|---|---|---|

## 17. Requirement traceability

| Problem/goal | Requirement | Design element | Implementation area | Test | Acceptance criterion |
|---|---|---|---|---|---|

## 18. Developer or coding-agent directive

- Implement only approved scope.
- Preserve listed invariants and protected areas.
- Do not add features, redesign interfaces, change architecture, or refactor unrelated code without approval.
- Surface repository/specification conflicts and blocking unknowns before proceeding.
- Run specified checks and report actual results.
- Return a change manifest, deviations, evidence, untested areas, and residual risks.

## 19. Source and evidence index