# Spec Conventions > This skill should be used when the user asks about "spec file format", "spec conventions", "spec vs docs", "current status section", "specification structure", "how to write a spec", "spec deliverables", or "self-contained spec". Provides conventions for writing implementation-ready specification documents. Use when this capability is needed. - Skill: `tomevault-io/spec-conventions` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/spec-conventions` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/spec-conventions/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/spec-conventions --- # Spec File Conventions Conventions for writing implementation-ready specification documents that serve as the single source of truth for feature design and implementation. ## Spec Files vs Documentation Files Projects often maintain two distinct documentation layers. Understand the distinction to keep each layer focused. ### Spec Files - **Purpose**: Single source of truth for design and implementation decisions - **Audience**: Implementors and reviewers - **Content**: Full design details — schemas, field definitions, decision rationale, implementation notes - **Lifecycle**: Created before implementation, updated progressively during implementation - **Self-contained**: A reader should understand the full design without opening other files ### Documentation Files - **Purpose**: Quick-reference guides after implementation - **Audience**: Developers using the feature - **Content**: Usage-focused ("how to use"), not "how it was designed" - **Brevity**: Avoid duplicating definitions — point to source files (.sql, .proto, .rb, config files) - **No historical context**: Omit decision rationale and alternatives considered When a spec lists documentation files as deliverables, verify their scope is clear. The spec itself must contain enough inline detail to be self-contained — never defer design details to documentation files. ## Spec File Structure A well-structured spec includes: 1. **Title and overview** — what the feature does and why it's needed 2. **Data model** — include full DDL or schema definitions, not just prose descriptions 3. **Architecture** — name concrete classes/modules; specify where each piece of logic lives 4. **Behavior** — cover the happy path end-to-end, then every error condition and edge case 5. **Integration** — specify which existing modules are touched and how 6. **Security considerations** — credential handling, rate limiting, audit logging, sensitive data 7. **Operations** — setup steps, cleanup/purge strategies, key rotation procedures 8. **Scope** — explicitly state what's in and out; note dependencies on future work 9. **Deliverables** — enumerate every file to create or modify 10. **Current Status** — interview or implementation progress (see below) ## Self-Containment Principle Inline all design details directly in the spec: - Full schema definitions (SQL DDL, protobuf, JSON schemas, etc.) - Field-level tables with types, constraints, and descriptions - Decision rationale for non-obvious choices - Error handling behavior for each failure mode A reader should never need to open another file to understand the complete design. ## Resolving TODOs Before a spec is considered interview-complete: - Every TODO must be resolved - TODOs representing open design questions must be resolved through discussion; inline the decision and rationale directly - TODOs representing implementation tasks should be reworded as clear action items in the deliverables or checklist - Grep the spec for ambiguous language: "TBD", "maybe", "possibly", "to be decided" ## Current Status Section Every spec must end with a "Current Status" section. Its format differs by phase. See `references/current-status-format.md` for detailed examples across interview and implementation phases. ### During Interview Keep concise — list covered areas with key decisions and remaining areas with rough question count: ``` ## Current Status Interview in progress. Covered: - Data Model: field types finalized, indexes decided - Architecture: service object pattern chosen Remaining (~8 questions): - Behavior & Logic: error handling details - Security: rate limiting defaults - Operations: cleanup strategy ``` ### After Interview / During Implementation Expand into a checklist and updates format: ``` ## Current Status Implementation in progress. Implementors MUST keep this section updated as they work. ### Checklist - [ ] Create database migration - [ ] Implement service object - [ ] Add request specs - [ ] Write documentation ### Updates - YYYY-MM-DD: Migration created, model specs passing - YYYY-MM-DD: Service object implemented with error handling ``` ## Additional Resources ### Reference Files - **`references/current-status-format.md`** — Detailed examples of Current Status sections across interview and implementation phases --- > Source: [sorah/config](https://github.com/sorah/config) — distributed by [TomeVault](https://tomevault.io).