Specification Format

Two Formats for Two Workflows

Choose the right specification format based on your workflow:

Format	Workflow	Use When
Full Spec	Spec Kit	Complex features, new systems, multi-day work
Quick Spec	My Kit	Simple fixes, minor features, < 1 day work

---

Quick Spec Format (My Kit)

For simple tasks, use a lightweight format in the issue description or PR body:

## What
[One sentence describing the change]

## Why
[One sentence explaining the reason]

## How
[Brief description of the approach]

## Test
[How to verify it works]

Quick Spec Example

## What
Fix navigation menu not closing on mobile after link click.

## Why
Users have to manually close the menu, causing poor UX.

## How
Add click handler to menu links that closes the menu state.

## Test
1. Open site on mobile
2. Open hamburger menu
3. Click any link
4. Verify menu closes automatically

---

Full Spec Format (Spec Kit)

For complex features, create a full specification in specs/{issue#}-{name}/spec.md.

Frontmatter

# Spec: [Descriptive Title]

**Issue**: #[number]
**Branch**: `[branch-name]`
**Status**: Draft | In Review | Approved | In Progress | Complete
**Priority**: Low | Normal | High | Critical
**Type**: Feature | Bug Fix | Documentation | Refactor | Enhancement

Required Sections

Problem Statement

## Problem Statement

[1-3 paragraphs explaining:]
- Current situation
- The problem
- Impact if not addressed

Goals and Non-Goals

## Goals

1. [Specific, measurable goal]
2. [Another goal]

## Non-Goals

- [Explicit exclusion]
- [Out of scope item]

User Stories

## User Stories

### US-1: [Title]
**As a** [role]
**I want** [capability]
**So that** [benefit]

**Acceptance Criteria**:
- [Testable criterion]
- [Another criterion]

Deliverables

## Deliverables

### 1. `path/to/file`
[Description]

| Aspect | Details |
|--------|---------|
| Feature | What it does |
| Behavior | How it works |

Acceptance Criteria

## Acceptance Criteria

### Functional
- [ ] Feature works as specified
- [ ] Edge cases handled

### Quality
- [ ] Tests pass
- [ ] No lint errors

### Integration
- [ ] Works with existing features
- [ ] No regressions

Implementation Checklist

## Implementation Checklist

- [ ] Create spec document
- [ ] Implement feature
- [ ] Add tests
- [ ] Update docs
- [ ] Create PR

---

Full Spec Template

Copy this template for new specs:

# Spec: [Title]

**Issue**: #
**Branch**: ``
**Status**: Draft
**Priority**: Normal
**Type**: Feature

---

## Problem Statement

[Description]

## Goals

1. [Goal]

## Non-Goals

- [Non-goal]

---

## User Stories

### US-1: [Title]
**As a** [role]
**I want** [capability]
**So that** [benefit]

**Acceptance Criteria**:
- [Criterion]

---

## Deliverables

### 1. `path/to/file`
[Description]

---

## Acceptance Criteria

### Functional
- [ ] [Criterion]

### Quality
- [ ] Tests pass
- [ ] Lint clean

---

## Implementation Checklist

- [ ] Create spec
- [ ] Implement
- [ ] Test
- [ ] Document
- [ ] PR

---

Status Values

Status	Meaning	Next Step
Draft	Being written	Complete all sections
In Review	Awaiting feedback	Address comments
Approved	Ready to implement	Start coding
In Progress	Being built	Complete checklist
Complete	Merged and released	Archive

---

Best Practices

For Quick Specs

• Keep it brief—4 sections, 1-2 sentences each
• Include in issue or PR description
• Focus on “what” and “why”

For Full Specs

• Be specific—vague specs lead to vague implementations
• Include examples where helpful
• Update as you implement
• Mark checklist items as you complete them