Headings and paragraphs define the structure readers and tools rely on.

Headings

Use ordered levels and avoid skipping levels.

Source syntax

# Spec Title

## Context

### Non-goals

## Requirements

### Functional requirements

Rendered output

Spec Title

Context

Non-goals

Requirements

Functional requirements

Paragraphs

Separate paragraphs with a blank line.

Source syntax

This is the first paragraph with core context.

This is a second paragraph that adds detail.

Rendered output

This is the first paragraph with core context.

This is a second paragraph that adds detail.

Guidance

• Keep headings descriptive and concise.
• Use sentence-style heading text for consistency.
• Break long paragraphs into 2-4 sentence chunks.