---
name: spec-design-format
keywords: [spec, design, proposal, architecture]
description: Required format for change design specifications
---

## Spec design format

# File name format
.spec/YYYY-MM-DD-<kebab-slug>.md

# Sections (in order):
1. # <Title> — short, descriptive title of the change
2. **File:** <path/impacted> — <date> — header line with the files touched and the date
3. ## Problem — current situation and pain to solve (concise)
4. ## Solution — high-level approach in 1–2 lines
5. ## Changes — operational detail, with ### subsections for each file/component (e.g. Config, Consumer, New method). Each subsection describes what changes and why, not line-by-line pseudocode
6. ## Caveats — operational warnings / side effects (optional but recommended)
7. ## Acceptance — numbered, verifiable acceptance criteria

# Style rules
- Content in English, references to code/path/identifiers in English
- References to config/methods in backticks
- Length proportional to the change (no padding)

# Brief summary
At the end of the implementation, inform the user, with a brief non-technical description, what was changed and what the developed spec now satisfies; also complete this section with the changes actually made, in table format:

| modified file | brief change | what it resolves |