Feature Specifications¶

Feature specifications are the first step in developing any non-trivial feature. They capture requirements, design decisions, data models, public API surfaces, and implementation plans in a single reviewable document before any code is written.

Specs live in this directory and follow the naming convention:

YYYY-MM-DD-<feature-name>.md

Governing document¶

The requirements document defines the R-* identifiers that every subsequent feature spec must cite. A spec that implements no stated requirement is a spec for work nobody agreed to do.

Process¶

1. Check for an existing spec covering the feature. Do not draft a duplicate.
2. Draft to YYYY-MM-DD-<feature-name>.md with status: DRAFT, including: Problem, Goals & Non-Goals, Public API, Data Models, Error Cases, Testing Strategy, Documentation Requirements, Implementation Phases, and Open Questions.
3. Cite requirements — list the R-* identifiers the spec satisfies.
4. Pause for review. Implementation starts only once status is APPROVED.
5. Track status — IN PROGRESS when work starts, IMPLEMENTED when done.

Required frontmatter¶

---
title: "<Feature name>"
description: "<One-paragraph summary>"
date: YYYY-MM-DD
status: DRAFT
tags:
  - specification
author:
  - name: Matt Cockayne
    email: [email protected]
---

Follow the frontmatter with a document header using Material definition-list syntax (Authors, Date, Status), as in the requirements document.

Testing and documentation are spec sections, not afterthoughts¶

Every spec must explicitly state:

• Whether the feature warrants E2E BDD scenarios (Godog). CLI commands, multi-step user workflows, and service lifecycle coordination generally do.
• Which documentation sections need adding or updating. Docs follow Diátaxis, with the phpboyscout deviation that tutorials are blog posts on phpboyscout.uk, linked from the tutorials index rather than duplicated in-repo.