The keywords
REQUIRED, SHALL and RECOMMENDED are RFC 2119 synonyms, but PolicyCodex extracts
the five levels above. Prefer them.
Uppercase is mandatory
The rule exists because the same words appear constantly in ordinary prose. “This approach should be familiar to most teams” is a sentence about tone, not a requirement. Reserving uppercase for rules means a reader — human or machine — can find every requirement in a document by scanning for capitals.Writing an extractable statement
Statement extraction reads your document and produces one row per requirement. Give it clean input:One rule per sentence
A sentence with two keywords becomes two statements that share a slug’s worth of
context but can’t be enforced or waived independently.
Name the subject
“Every public API schema MUST…” is testable. “It MUST be documented” is not — the
extractor has to guess what “it” is.
Be checkable
A requirement an AI reviewer can evaluate against a diff. “Code MUST be clean” is
unenforceable; “Every exported function MUST have a doc comment” is not.
Group under headings
The
## heading a requirement sits under is recorded as its section, which is how
findings cite context back to the reader.Examples
Choosing a level
Ask what happens when someone violates it:1
Would you block the merge?
If yes — and you are willing to defend that at 5pm on a Friday — it is a
MUST.2
Would you expect a reason in the PR?
That is a
SHOULD. It surfaces as a warning; the author explains and moves on.3
Are you just documenting an option?
MAY. It records that something is permitted, and produces no findings.