Blockers and Observations

A review finding needs enough structure to be actionable: classification, location, violated contract, consequence, and proposed direction. “This feels brittle” may start a conversation but cannot block landing because nobody can tell what proof would resolve it.

Blockers are defects that must be repaired or explicitly stetted: wrong scope, false claims, broken behavior, missing acceptance evidence, safety failures, or contract violations. Observations are valuable improvements or risks that do not invalidate the current task. Mixing them makes either every suggestion a crisis or every defect optional.

Severity is not a model confidence score. A reviewer can be uncertain about a high-impact possibility and should state the uncertainty. The author verifies the premise. Classification describes consequence if true, while evidence strength describes how well the reviewer established truth.

Locations should be tight. For code, name file and line or symbol. For documents, name section and claim. For runtime behavior, name the route or workflow without dumping private infrastructure. Precision shortens repair and makes stet reviewable.

Make the Claim Falsifiable

Rewrite each blocker as: at location X, artifact says or does Y, contract requires Z, consequence is W. The author can then reproduce, repair, or demonstrate why one premise is false.

Keep observations on the record even when no immediate repair is required. They become inputs for future pipeline edits or dedicated product work without holding the current task hostage.

Severity follows consequence, not annoyance. A blocker makes the artifact false, unsafe, unrunnable, or outside approved scope; an observation records a worthwhile improvement that does not invalidate landing. Keeping that bar explicit protects both quality and the ability to finish.

Code

A structured review finding·json

{
  "kind": "blocker",
  "location": "verification summary",
  "claim": "reports success without destination evidence",
  "contract": "task completion requires destination proof",
  "consequence": "a documented failure can land",
  "suggested_direction": "record and check the named acceptance evidence"
}

Blockers and Observations