DEV-125.md

id	DEV-125
title	Write a Spec in the Standard Format
status	active
enforcement	manual
severity	error
depends_on	DEV-180 DEV-350

Problem

A Spec written without a shared structure is hard to read and review: readers cannot tell where the goal, the overview, or the behavior sections are, and specs drift into describing internals instead of user behavior.

Solution

Give every Spec the same skeleton so any reader knows where to look, and keep it about what users can do, not how the system works.

1. Store the Spec as a markdown file under docs/specs/, linked from its Goal under # Spec; its sections graduate to docs/product/ per DEV-180.
2. Start with goal: frontmatter linking the Goal, then an H1 feature name and a ## Overview of what the Goal enables for users.
3. Add author-defined ## sections that describe observable user behavior, not internal mechanics.
4. Include a ## Design section using the markup in DEV-350 when the Goal has a design component.

---
goal: <link to Goal issue>
---

# Feature Name (max 45 chars)

## Objective
(describes business objective, max 250 chars)

## Key results
(three items; max 160 chars each)

## User Types
(list of end-users' types and their short definition; each item max 150 chars)

## Key Concepts

(subsections describing key concepts end-user needs to know about;
the relevant methods (actions) specific users can use)

## [Section]

Describe what users can do, not how the system works internally.

Acceptance Criteria

• The Spec is a docs/specs/ file with goal: frontmatter, an H1 name, and a ## Overview
• Sections describe user-observable behavior, not internal mechanics
• A Goal with a design component includes a ## Design section per DEV-350