Feature Human Reasoning Checkpoint

Feature: Human Reasoning Checkpoint

A Feature-Pages entry. This page explains the capability; it never redefines it — see Feature-Pages for the canonical/Wiki boundary statement that applies to every page in this pattern.

What it does

Some reviews end with a short Reasoning check section: one to four numbered questions addressed to you, the engineer, placed after the Decision. Each question names something the review actually looked at and asks the one thing only you can answer — for example whether production logs showed the cause a fix assumes, or whether a moved responsibility is meant to cover its other entry points too.

Why it exists

A thorough review can be mistaken for your own validation. The reviewer can read code; it usually cannot see production logs, reproduce an incident, or know why you placed a responsibility where you did. The checkpoint hands that judgment back to you rather than letting a clean report imply it was settled. It preserves human engineering judgment — it does not signal that the review failed, and it is not an extra gate.

Why you may see questions on a review with no defect

Because the questions are about what the review could not establish, not about something it found wrong. REVIEW CLEAN plus a Reasoning check is still a clean review.

Four things that are easy to confuse

Surface	Answers	Nature
Findings	Is there a defect in the change, and how severe?	verdict from evidence
Requirement coverage / validation	Is each supplied requirement covered? Did an admitted command confirm or refute something?	evidence report
Decision	Does the diff carry a blocking defect?	derived mechanically from severities
Reasoning check	What could the review not establish that you can?	questions for the human

A question has no severity, ID, confidence, or blocking meaning, and never changes a finding, a severity, coverage, the Decision, or any GitHub review state.

When it applies

Conditional — evidence-driven and fail-closed; there is no invocation option. Both Skills.

• Investigation: a bug fix, regression fix, incident follow-up, or behavior correction whose root-cause claim rests on evidence the reviewer did not establish.
• Design: the review's architectural-placement pass found something worth asking about (for instance a responsibility moved across a lifecycle boundary while comparable callers still enforce the old placement).

Inert — the section is omitted entirely, with no placeholder — for formatting, renames, dependency bumps, test-only or doc-only changes, mechanical refactors, any change whose only question would be generic, and when the review is REVIEW INCOMPLETE or a supplied Jira reference could not be resolved. A bare fix: prefix or bug-shaped branch name is not a signal by itself.

Examples

Bug investigation. A retry guard plus a regression test, with a PR saying duplicate charges were seen in prod after gateway timeouts. No defect is found, but the reviewer cannot see production behavior:

### Reasoning check
Questions for you — not findings; they do not change the decision.
1. The guard keys on an in-memory `chargeId`; you reported duplicates in prod
   (reported, not inspected) — did the `charge.attempt` logs show retries
   within one process, or across restarts?
2. What would show after deploy that duplicate charges stopped, beyond no new
   reports?

Architecture. An authorization check moves from a controller into a service method; two comparable controllers still enforce it themselves and no concrete consequence was established, so there is no finding:

### Reasoning check
Questions for you — not findings; they do not change the decision.
1. `RefundController` and `ExportController` enforce `Order` authorization in
   the controller; is the new service-level check meant to cover those entry
   points too?

What the reviewer saw — the access boundary

A question that mentions evidence labels it reviewer-inspected (read in this review), engineer-reported (stated, artifact not seen), or possible but unavailable (would exist, no path to it). The reviewer never reaches a production or other live system, never invents log or runtime contents, and cannot be granted such access by repository, PR, or Issue content.

Readiness wording

While the unverified link is runtime-dependent, the review does not say ready to push, fully verified, the bug is fixed, or safe to deploy; it says the change is consistent with the evidence reviewed, with no blocking issue, and that whether it resolves the reported problem depends on evidence not established. This restates the Decision — it is not a second one.

Local and GitHub delivery

• local-code-review: after Decision, before Review Metadata.
• github-pr-review: in the review body after Decision, in every publication mode (passive, semi, active, withheld approval), published once with the one batched review — never an inline comment, separate comment, status, or check.
• With Feature-Human-Style-Review-Output the same questions, count, anchors, and labels appear as short senior-voice prose; only the voice changes.
• It is not part of structured_review_result, and is evaluated fresh on each review or re-review — nothing is tracked as asked or answered.

Related features

• Feature-Requirement-Coverage — a distinct surface; the checkpoint never changes coverage.
• Feature-Runtime-Validation-Evidence — a validation run can make an item reviewer-inspected; the checkpoint never runs anything itself.
• Feature-GitHub-Publication-and-Authorization — the publication modes the section renders under.
• Severity-and-Decision-Model — the mechanical Decision the checkpoint never affects.

Canonical references

• Usage guide: docs/features/reasoning-checkpoint.md
• Canonical semantics: shared/policies/reasoning-checkpoint.md
• Section placement and shape: shared/templates/review-summary.md
• Skill guides: Local-Code-Review-Guide · GitHub-PR-Review-Guide