Keeping a Review Audit Trail With Evidence
Quick answer: A confident review leaves a trail you can hand to someone else. For every suspicion, keep the priority and the code anchor, a reproducible command with its raw output, the decision to confirm or dismiss, and the reason behind it. This makes the merge defensible when a defect later surfaces and keeps the next review from re-litigating the same questions. A decision recorded without the evidence is hard to trust and impossible to rerun.
Why the trail matters
A review is a decision made under uncertainty, and the value of the record shows up after the merge. If a change later causes a problem, the trail answers what was checked, what was not, and why the team accepted it, rather than reducing the history to a single approval. It also protects the reviewer: a dismissed suspicion with a cited guard is a deliberate decision, not a missed defect.
The trail also compounds. A repeatable record of commands and outputs means the next reviewer can rerun the same checks and focus on the new diff instead of reconstructing old reasoning.
What each record should carry
| Field | Purpose |
|---|---|
| Code anchor and priority | Where the suspicion sits and its rank |
| Evidence type | Static, dynamic, contract, or AI hypothesis |
| Reproducible command | The exact check that can be rerun |
| Raw output | The process result the decision rests on |
| Decision | Confirmed, dismissed, or left open |
| Reason | The trigger or guard that decided it |
An AI-only claim is recorded as a hypothesis, and the field makes that status explicit rather than letting it look like verified evidence.
How to build the trail
- As each suspicion is read, attach the anchor and the priority to the record.
- Classify the evidence by type, keeping AI-only claims labeled.
- For every runnable check, store the command and the raw process output.
- When a suspicion is confirmed or dismissed, write the decision and the exact reason.
- Leave uncertain items open rather than recording a confident verdict.
- Re-run a recorded command later to confirm the trail still reproduces.
Take a review that flags a deletion filter. The record stores the anchor, the evidence type, the request that reproduces the archived-note deletion, and the raw response showing the removed row. The decision is confirmed, and the reason names the caller that passes the full visible list. A second suspicion is dismissed, and its record cites the earlier guard that blocks the trigger. Months later, either decision can be read and rerun from the same file.
Deterministic verdicts
The verdict itself is deterministic with no LLM involved, so the recorded outcome reflects the evidence rather than a model's mood: drift or failing evidence fails, partial verification stays partial, and an empty result is not a pass. Each evidence item carries a reproducible command and raw output, which is what makes the recorded verdict trustworthy.
The Agent task package also builds on this trail, exporting a Markdown handoff with context and revision anchors that another agent can assess independently.
Powerduck keeps the evidence and the decision attached to the change, so the review history travels with the code rather than living in scattered notes.
How long the trail should live
The trail has value long after the merge, and it should be kept where the code history can reach it rather than in a chat that scrolls away. Keep the record at least as long as the change it describes is live, because a defect can surface months later and the evidence that was checked then is the only way to tell a missed defect from a deliberate decision. When a finding is revisited, the stored command can be rerun against the current code to see whether the old guard still holds. A thin record forces the team to reconstruct that reasoning from memory, which is unreliable, while a full one turns a post-incident review into a reading exercise. Treat the trail as part of the change, not a temporary note.
Honest limits
The trail records what was actually checked, and it does not cover paths no command exercised, so a clean record is not proof of every edge case. Dynamic loading and external consumers can remain outside the static evidence, and the review can still miss defects.
Keep unverified items visible rather than hiding them, and confirm behavioral changes with a real request when the recorded checks cannot.
Frequently asked questions
Why store the raw output? It is the basis for the decision and lets a reviewer rerun the check rather than trust a summary.
Does a dismissed finding stay in the record? Yes, with the reason, so the same suspicion is not re-litigated or mistaken for a miss.
What makes a verdict defensible? Reproducible evidence and a written reason, with AI-only claims kept as hypotheses.
The bottom line
Record the full trail, not just the approval: the anchor, the evidence type, a reproducible command and raw output, and the decision with its reason. This makes a later defect traceable, keeps dismissed findings deliberate, and lets the next review rerun the same checks. A clean record still bounds itself to the paths that were run, and uncertain items stay open. The evidence is what makes the decision defensible. Read more in the AI code review guide.