Validate the review packet before you review the patch

#testing

A green build can arrive with evidence for the wrong commit. A detailed delivery can leave the security reviewer unnamed. Neither problem requires reading every line of the patch to detect.

This tutorial builds a small evidence gate for a fictional search-filter change. The gate checks that a review packet is ready for human inspection. It deliberately does not decide whether the code is correct.

Separate implementation from acceptance

The task author prepares the outcome, fixture, scope, and acceptance criteria. The runner implements the change using their own authorized tools. A qualified reviewer judges the technical evidence, and the authorized task reviewer records the final decision.

If your requirement is “delegate AI task without sharing account,” place repository access and tool authorization in the runner’s setup checklist. The task should carry context and expected results, not somebody else’s login or provider token.

In this example, a search field should trim surrounding whitespace without changing authorization, query scope, or result ranking. If the implementation reaches those areas, the runner stops for technical review.

Create the evidence packet

Use actual revision identifiers and attach the full output of the checks you run. The values below are fictional placeholders illustrating the shape, not successful test results.

{
  "candidate": "REPLACE_WITH_COMMIT",
  "runner": "runner-name",
  "reviewer": "qualified-reviewer-name",
  "checks": [
    {
      "criterion": "search-trims-whitespace",
      "revision": "REPLACE_WITH_COMMIT",
      "result": "not-run",
      "evidence": ""
    },
    {
      "criterion": "empty-search-keeps-existing-behavior",
      "revision": "REPLACE_WITH_COMMIT",
      "result": "not-run",
      "evidence": ""
    }
  ],
  "escalations": []
}

Save that as review-packet.json. A task-specific required list matters: otherwise an empty or conveniently shortened checklist can pass a generic gate.

Check completeness with a small script

Save this as check-review-packet.mjs and run node check-review-packet.mjs review-packet.json with a current Node.js release.

import { readFileSync } from "node:fs";

const required = [
  "search-trims-whitespace",
  "empty-search-keeps-existing-behavior"
];
const problems = [];
const hasText = x => typeof x === "string" && x.trim().length > 0;
let p;
try {
  p = JSON.parse(readFileSync(process.argv[2], "utf8"));
} catch {
  console.error("Provide a readable JSON review packet.");
  process.exit(1);
}
if (!p || typeof p !== "object" || Array.isArray(p)) {
  console.error("The packet must be an object.");
  process.exit(1);
}
if (!/^[a-f0-9]{40}$/i.test(p.candidate ?? "")) {
  problems.push("Use the full candidate commit SHA.");
}
if (!hasText(p.runner) || !hasText(p.reviewer)) {
  problems.push("Name the runner and qualified reviewer.");
} else if (p.runner.trim() === p.reviewer.trim()) {
  problems.push("This task requires an independent reviewer.");
}
const checks = Array.isArray(p.checks) ? p.checks : [];
for (const criterion of required) {
  const matches = checks.filter(c => c?.criterion === criterion);
  if (matches.length !== 1) {
    problems.push(`${criterion}: expected exactly one record.`);
    continue;
  }
  const c = matches[0];
  if (c.revision !== p.candidate || c.result !== "pass" ||
      !hasText(c.evidence)) {
    problems.push(`${criterion}: missing current passing evidence.`);
  }
}
if (!Array.isArray(p.escalations) || p.escalations.length > 0) {
  problems.push("Resolve and document escalations before review.");
}
if (problems.length) {
  console.error(problems.join("\n"));
  process.exitCode = 1;
} else {
  console.log("Packet complete. Human review is still required.");
}

Work through a handoff

The author records the existing empty-search behavior before work starts. The runner changes the input normalization and gathers evidence for the two named criteria. They record the candidate commit once the implementation is stable.

Now imagine a follow-up edit changes that commit after the tests run. The packet gate rejects check records carrying the previous revision. The runner either reruns the relevant checks or obtains a documented review decision about which evidence remains applicable; they do not simply relabel old output as new evidence.

If the runner discovers that trimming is happening inside an authorization-sensitive query builder, they add an escalation describing the affected path. The qualified engineer decides whether the proposed scope is still appropriate. A founder can understand that blocked state without personally certifying the query implementation.

Understand what the gate cannot prove

The script accepts text supplied by people. It cannot verify that a named reviewer is qualified, that an evidence link is accessible, that a command really ran, or that the chosen tests are sufficient. It does not inspect Git or enforce identity. Use it as a completeness check before review, never as a replacement for review.

Wagglet’s human–AI pairing article discusses why a useful human role includes judgment and a clear route to expertise. The same principle applies here: automate the missing-field check, then leave the consequential decision with somebody who can assess the result.

The final review note should name the candidate revision, explain the verdict, and retain unresolved limits. “Packet complete” means the reviewer has something coherent to inspect. It does not mean the patch is accepted, merged, or ready to deploy.

DEV Community