Engineering guide

Review requirements completeness in layers

Requirements completeness has several meanings. A repository can have valid files, linked children, and tests for every declared item while still omitting an important product behavior.

Ask which population is being called complete

Question	What a clean result leaves open
Are records structurally complete?	The requirement may still be wrong or vague.
Does every parent have a child?	The child may cover only part of the promise.
Is every declared obligation allocated?	An important obligation may never have been declared.
Does every obligation have evidence?	The witness or its assertion may be inadequate.

A completeness percentage needs its denominator. “All declared requirements have tests” says nothing about requirements absent from the set.

Walk a real behavior through failure and recovery

Consider an import service whose requirements cover valid records and malformed input. Walk through process termination, disk-full conditions, duplicate replay, an input file changing during recovery, and a partially written checkpoint. Ask what the user should observe in each case and which requirement governs it.

Illustrative gap. Every existing import requirement has a child and a test, but none says whether accepted records may be duplicated after restart. The missing promise cannot be repaired by adding another trace link among the existing requirements.

Use interfaces, hazards, incidents, support reports, and domain constraints to challenge the set. Catalog suggestions can help, but neither tag matching nor semantic similarity defines the full product boundary.

Turn the omission into a decision

Continue the importer example with a specific interruption: the service saves a row, then stops before saving its checkpoint. On restart it reads that row again. This is an illustrative review scenario, not a recorded failure.

Review step	Record to retain
State the missing decision.	May replay create duplicate accepted records, or must importing the same item be idempotent?
Identify authority.	The owner of the import contract must choose the behavior. Existing implementation is evidence of what happens today.
Propose a requirement.	After restart, replaying an already accepted item must not create a second record. Define the item identity and persistence assumptions before approval.
Plan a discriminating check.	Interrupt between row persistence and checkpoint persistence, restart, replay, then count records using that identity.
Keep the rest open.	Concurrent importers, changing input files and storage failure still need separate decisions and checks.

Adding this requirement changes the inventory that any coverage percentage refers to. Until its authority is resolved and the check runs, the useful outcome is a named gap with an owner, rather than a larger “complete” count.

Use checks for the layers they actually cover

proof audit --check l1_system_complete --verbose
proof audit --check obligation_completeness --verbose
proof audit --check obligation_evidence_complete --verbose

These inspect record shape, declared stakeholder-class allocation, and required evidence cells respectively. Catalog completeness is another integrity check: it reconciles class definitions and references, not the completeness of stakeholder intent.

Resolve gaps without lowering the promise

Recover or author candidate requirements for newly identified behavior, then review them under the applicable authority policy. If a requirement already applies but implementation or evidence is missing, keep it as visible work. Deleting the checklist item changes the question rather than answering it.

Preserve the reasoning behind the completed review, the assumptions, and unresolved scope. A later architecture change or production failure can expose a new omission. Completeness is a reviewed claim about a stated boundary, not a permanent property conferred by one green audit.

Continue from here

Review catalog applicability. Validate the intended behavior.

Bring a feature whose requirements look complete but whose failure and recovery behavior remains uncertain. Bring a change to Proof.