spec-conventions

name	spec-conventions
description	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.
version	0.1.0

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