Software assurance guide

Write a software problem report that preserves the lesson

A useful problem report connects a failure to its cause, corrective work and evidence. It should let the next engineer distinguish a repaired instance from a broader recurrence-prevention claim.

Start with the decision

Start with expected and observed behavior, affected versions and conditions, the requirement involved and a reproducible observation. Preserve the original evidence even after the fix. Then explain the root cause and why the previous verification missed it. Missing intent, a missing input partition and an implementation mistake require different follow-up work; a generic “add more tests” action does not explain which protection was missing.

An illustrative case

Illustrative case: a parser accepts a trailing separator that its contract forbids. The patch adds one rejection and the original reproducer now passes. That establishes an instance result under the tested conditions. To make a broader claim, inspect other separator paths, add relevant boundary partitions and link the strengthened requirement and regression checks. If another parser path remains unexamined, keep that limitation visible instead of claiming that the whole syntax class is closed.

Build the record

Retain the original KnownIssue, its requirement link and the reproducer’s before-and-after observations.
Record the root cause and the specific requirement, test partition or implementation boundary that must change.
Link the corrective Change and permanent evidence. Inspect related sites and give each a supported disposition.
Choose a report disposition whose scope matches the evidence, obtain the required review and validate the record. Leave unresolved class work explicit.

KnownIssue and DEFECT serve different stages

In Proof, a KnownIssue tracks a live failure. A DEFECT ProblemReport retains corrective and recurrence-prevention work after a product fix has landed or while that hardening is being assembled. An open DEFECT should not become a second ticket for an untouched live bug.

Claim	Evidence to retain
The observed instance is fixed	Original reproducer, tested revision, conditions and actual result.
The regression is guarded	Permanent check tied to the requirement, with current execution evidence.
The declared class is addressed	Bounded class definition, inspected siblings, strengthened obligations and evidence covering that scope.

A covered_by_requirement disposition needs the applicable requirement and evidence links. Gap-rooted reports also need resolving hardening; an added obligation must really be attached to the linked requirement. If the available evidence supports a narrower outcome, record that outcome instead of weakening the validation rule.

proof problem-report list
proof problem-report validate

Keep the conclusion bounded

Proof validates record shape and resolves required references. Those checks do not themselves execute every linked test or prove universal class closure. A review signature is an accountable assessment of stated evidence, not a substitute for that evidence. Keep failed, stale and missing results visible to the acceptance decision.

Continue with one real issue

Problem reports reviewed · Known issue sibling disposition

Bring one finding, its requirement and the current evidence to scope a walkthrough of what your reviewer can establish and what still needs work.