Engineering guide

Derive requirements that add useful detail

A derived requirement makes a higher-level promise concrete enough to allocate or verify. Copying the parent's sentence into a lower-level file adds a link without adding engineering knowledge.

Begin with an acceptance question

A stakeholder needs to resume an interrupted import without losing accepted records. That need does not yet settle checkpoint storage, duplicate handling, or what happens when the source changes during recovery. Derivation identifies the responsibilities and decisions needed to make the promise achievable.

Illustrative refinement. Parent: an interrupted import can resume without duplicating accepted records. Candidate system responsibilities: persist a checkpoint only after accepted records are durable; recognize already accepted record IDs on replay; reject or explicitly handle a source revision mismatch.

Each child should explain which part of the parent it realizes. Some details are design choices and constraints, not new stakeholder desires. Keep their rationale and assumptions visible.

Use generation as a starting point

proof req derive STK-REQ-042 --component importer

This command writes system requirement YAML from testable stakeholder acceptance criteria, adds satisfies links, and updates the criteria's derived-requirement backlinks. It is an authoring operation, not a read-only preview or a proof of refinement.

The current command uses automatic derivation logic even without the auto flag; do not assume it provides an interactive approval step. Review every generated description, suggested formalization, variable binding, and skipped criterion before promoting the records.

Check what the child adds and what it misses

State the trigger, domain, response, and boundary cases at the child's level.
Check that the child does not weaken the parent or add an unauthorized constraint on callers.
Allocate each relevant obligation, including error and recovery behavior, to an actual owner.
Choose evidence appropriate to that level: a unit test for checkpoint ordering does not by itself accept the end-to-end recovery promise.

A structural satisfies link shows the claimed relationship. Formal consistency or implication analysis can strengthen a modeled relationship under declared assumptions, but it cannot repair a wrong or incomplete parent statement automatically.

Keep the derivation current

When the parent changes, review the children and their evidence rather than relying on the old link. When a defect reveals a missing case, decide whether the parent was incomplete, the child refinement was weak, or the implementation violated an adequate requirement. Those are different repairs.

proof audit --check obligation_completeness --verbose
proof audit --check obligation_decomposition_complete --verbose

These checks inspect declared class allocation. Their clean results do not establish that the derived behavior is correct or fully verified.

Continue from here

Choose useful requirement layers. Define the governing need.

Bring a stakeholder criterion whose system-level responsibilities are still unclear. Bring a change to Proof.