requirements-management

Requirements Management

Purpose

A requirements document is the durable source of truth for what a project must do, what constrains it, and what decisions have been made. It exists so that any LLM session can re-ground itself on project intent without relying on chat history.

File Format

Requirements live in requirements.md (or requirements.yaml) in the project root, version-controlled alongside code. The file is plain text that humans can edit directly — the LLM is a convenience layer, not a gatekeeper.

Document Structure

Sections in order:

1. Project header — name and one-line summary
2. Problem Statement — what, who, why (2-3 paragraphs max)
3. Actors — table of actor IDs, descriptions, and goals
4. Glossary — canonical terms with aliases; domain quirks and exceptions
5. Functional Requirements — each with ID, status, priority, actor, intent, description, rationale, acceptance criteria, scenarios
6. Constraints — technical, business, or operational limits on the solution space
7. Non-functional Requirements — performance, security, reliability with measurable criteria
8. Future Scope — anticipated work explicitly not in current scope but worth recording
9. Non-Goals — behaviours explicitly rejected, especially from prior implementations
10. Decisions — append-only log of design/architecture choices
11. Open Questions — things we know we don't know

Key Principles

IDs Are Stable

Requirement IDs (FR-01, C-01, NF-01, D-01, Q-01) never change once assigned. Reference them in code comments, commit messages, and conversations. Increment to the next available number for new items.

Status Flow

Requirements move through: draft → in-flux → settled. Only settled requirements should be treated as ground truth during implementation. draft and in-flux items should be flagged for discussion.

Priority Levels

must = system is broken without this. should = significant value, strong expectation. could = nice to have, implement if cheap.