Engineering guide
Validate requirements before trusting their checks
Requirements validation asks whether the proposed promises are appropriate for the intended use. A command that validates record shape or model setup answers a narrower question.
Start with the intended use
A hospital scheduling service may have a perfectly formed requirement that cancels appointments after one missed confirmation. Whether that behavior is acceptable depends on the users, consequences, and operating policy. Valid YAML and passing tests cannot settle that decision.
Illustrative review. Ask what happens when a notification is delayed, the recipient cannot respond, or the appointment is urgent. The resulting decision may require escalation or a grace period. Treat those as candidate requirements to review, not behavior inferred from the existing cancellation code.
Use the right kind of validation
| Activity | Question |
|---|---|
| Record validation | Are fields, references, and declared shapes valid? |
| Model preflight | Are variables and modeled roles suitable for analysis? |
| Intent validation | Do these promises meet the accepted need in the operating context? |
| Implementation verification | Does the implementation satisfy the approved promises within the evidence scope? |
Each can find defects that the others miss. Keeping them separate avoids calling a structurally valid requirement “validated” without saying what was examined.
Run structural checks, then inspect the decisions
proof validate
proof validate --preflight specs/system scheduler
proof review req SYS-REQ-042The first checks configured requirement records. Preflight requires both a configured spec and component and catches setup issues before solver invocation. The review command gathers the requirement's authored state and available evidence. None independently certifies that the scheduling policy is appropriate.
Review representative normal, boundary, failure, and recovery scenarios with the responsible authority. Compare related requirements and assumptions so local clarity does not hide a system-level conflict.
Record the product decision before changing the tests
Illustrative decision: the scheduling owner decides that a missed confirmation must create a staff follow-up rather than automatically cancel the appointment. The grace period and urgent-case escalation remain unresolved. Those questions stay visible before implementation.
Download the plain-text template, or select and copy it here. This worksheet works with your existing tools.
Requirement and revision under review:
Intended user outcome:
Source of the need:
Normal scenario and expected result:
Boundary or failure scenario and expected result:
Conflicting requirements or assumptions:
Decision: accept / amend / reject / unresolved
Decision owner, authority and date:
Rationale and evidence considered:
Follow-up changes to code, tests and documentation:
Open questions and owners:A completed record should explain why the behavior is acceptable for its intended use. A successful syntax check belongs in the supporting evidence, not in the decision-owner field.
Record acceptance and uncertainty
Retain the source of the need, the decision, its scope, and unresolved questions. Agents can recover candidates and support or perform review within policy, but a generated statement does not approve itself.
After a decision changes the requirement, revisit its children, formalization, tests, and implementation evidence. If a model reports a counterexample, determine whether it is a real conflict, an abstraction error, or a scenario to reproduce in code. A passing model or test cannot rescue a requirement that specifies the wrong outcome.
Continue from here
Inspect intent and evidence together. Investigate conflicting promises.
Bring a requirement that is well formed but may specify the wrong behavior. Bring a change to Proof.