| id | DEV-020 | |
|---|---|---|
| title | Structure a Rule as Problem, Solution, Acceptance Criteria | |
| status | active | |
| enforcement | manual | |
| severity | error | |
| depends_on |
|
Rules written in free form are hard to scan and impossible to check consistently. Without a fixed shape, a reader cannot tell what breaks, what to do about it, or how to verify they complied.
Give every rule the same three parts, each with a distinct job so they do not repeat each other:
- Problem: what is broken, or what someone cannot do, not a restatement of the title. Keep it short (see DEV-050).
- Solution: the approach and the reasoning, the method a doer follows and why. Prefer a numbered list for steps or sequence, prose for reasoning that has no order, and add a good and bad example where it makes intent concrete. It may overlap the Acceptance Criteria, but it must add the how and why, not just reword the checks.
- Acceptance Criteria: the objective outcomes a reviewer checks on a finished subject, phrased as pass or fail. They verify the Solution; they do not restate its steps.
The frontmatter title is the rule's title, so the body does not repeat it as a
heading. The body opens at Problem and Solution (##) and nests Acceptance
Criteria (###):
## Problem
## Solution
### Acceptance Criteria- The body has Problem, Solution, and Acceptance Criteria, in that order
- The title is not repeated as a body heading
- The Solution reads as method and reasoning, not a restatement of the acceptance checks
- Each acceptance item is an objective outcome, checkable on a finished subject