# Specful Requirement

> Use when writing or updating a Specful Requirement: a new normative obligation, or a change to what the software must do.

- Skill: `unkos-dev/specful-requirement` (Agent Skill)
- Install (CLI): `npx skillmds@latest add unkos-dev/specful-requirement`
- Raw SKILL.md: https://api.skillmd.com/api/skills/unkos-dev/specful-requirement/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: unkos-dev (https://skillmd.com/u/unkos-dev)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/unkos-dev/specful-requirement

---


# Writing a Specful Requirement

A Requirement records a current normative obligation: what the software must do now, written as though it has always
been so. It is not a Design (how the system works) and not an ADR (why a decision was made); if the change is about how
or why, load `specful-design` or `specful-adr` instead. History and transitions never appear in the prose: a transition
is a plan, and what used to be true is Git history.

## Workflow

1. Start at `docs/specs/index.md` and follow the scope indexes to the module the obligation belongs to. Read the
   neighbouring Requirements and the Designs that satisfy them before writing.
2. Scaffold with `specful new requirement --title <TITLE> --scope <SCOPE>`. Never hand-allocate an identifier; the
   command owns the counter.
3. Complete the placeholders. The Statement section carries at least one uppercase BCP 14 keyword (MUST, MUST NOT,
   SHOULD, SHOULD NOT, MAY); cite governing ADRs through `governed-by`, naming only the ADR whose rationale this
   obligation embodies, never a related or organising decision such as the decision to adopt a convention, and omit the
   field when that record does not exist in the profile. Write obligations testably: a Requirement that no observable
   behaviour could violate is decoration, not specification. More information is optional and is removed completely when
   it adds nothing; it never restates a `governed-by` edge as a link, since `specful show` already renders it.
4. Run `specful index`, then `specful validate`; commit the regenerated views with the change.
5. Mechanical validation does not judge substantive quality. Use `specful-review` when the adopting repository requires
   substantive review or the user asks for it.

For the full Requirement profile and field-by-field guidance, see <https://unkos-dev.github.io/specful/>.