· Engineering practice
From bug ticket to reviewed PR: an evidence checklist
A useful fix is more than a plausible diff. It gives the next engineer enough evidence to understand the failure, evaluate the change and decide whether to merge.
AI can help explore a repository and propose changes. It does not remove the need to define the problem or check the result. Here is the sequence I use to make an investigation reviewable.
1. Define the failure before choosing the fix
Write down the trigger, expected behavior, actual behavior and affected environment. Include the smallest useful example. “The portfolio is broken” is vague. “When the repository API returns an error, the static featured-project links disappear” identifies an observable contract.
Also define what is outside the ticket. A failure in repository loading does not automatically call for replacing the framework or redesigning the project cards.
2. Reproduce at the boundary that fails
Control the failing dependency. For a network issue, exercise a rejected request, a slow response and an empty response separately. They are different states. First observe the behavior on the old code; a test that only passes after the fix is weaker evidence if it never demonstrated the original problem.
For the portfolio example, intercepting GitHub with a failed response gives a repeatable reproduction without relying on a real outage or consuming API limits. The static content should remain usable in that state.
3. Trace the cause, then make a bounded change
Read the rendering and data flow before editing. In this example, the page returned an error screen before it reached the static cards. Moving network status into the repository section addresses that boundary directly.
When handing this to an agent, give it the reproduction and acceptance criteria. Ask for evidence about the cause and the affected paths. Avoid treating a confident explanation as a substitute for reading the actual change.
4. Verify behavior, including recovery
- Does the original failure now behave correctly?
- Does normal loading still produce the intended result?
- Can the visitor retry without losing unrelated content?
- Does an empty result have an honest explanation?
- Can a keyboard user reach and activate the controls?
Run type, lint and build checks too. They catch a different class of problem from a browser regression test. A green build alone would not have detected the missing featured cards.
5. Make the handoff easy to judge
The pull request should explain the trigger, resulting behavior, verification and remaining limits. Link the issue and include a screenshot when the result is visual. Separate measured observations from expectations.
For example: “A failed GitHub request now affects only the repository list. Featured project links remain visible, and visitors can retry. Browser checks cover failure, empty results and recovery.” That is useful review evidence without claiming every production condition has been tested.
Where this method stops
A reproducible UI fix does not establish business impact, eliminate unrelated defects or justify a throughput claim. Changes to payments, authentication or customer data need checks appropriate to those risks. The reviewer still owns the merge decision.
Read the internal portfolio walkthrough for the concrete boundary, or inspect the focused browser regression test. For the general testing approach, Playwright documents network mocking and testing user-visible behavior.