LearnGrokReview the pull request against the ticket, the evidence from tests and the repository’s stated conventions. This workflow gives senior engineers and technical leads a review record that another person can act on without rereading the whole diff.
Use it for changes that could reach production. It is not a replacement for an engineer reading the affected code, especially authentication, data migration, concurrency and rollback paths.
Key point
Review the contract, not just the diff
A merge decision is sound only when the ticket, implementation, tests and operational impact agree.
1. Assemble one review packet
Collect the material before asking the model to assess anything. Label each item clearly so the response can cite it.
- Copy the ticket title, problem statement and acceptance criteria.
- Add the pull request description, linked incidents and any stated rollout or rollback plan.
- Add the changed files or a focused diff. Include relevant surrounding code where a changed function depends on it.
- Add test evidence: new or changed tests, CI results, known failures and manual test notes.
- Add repository conventions that apply, such as contribution guidance, error-handling patterns, logging rules, API compatibility policy and migration rules.
- Add operational context: services affected, feature flags, schema changes, queues, background jobs, alerts and dashboards.
Keep unneeded material out. A full repository dump makes it harder to identify the actual change. If the review packet is too large, split it by concern, for example API behaviour, database migration and worker processing. The material you can provide and the limits that apply are version-dependent. Check the xAI documentation overview before designing a repeatable attachment process.
Stop
Remove secrets and customer data
Do not include credentials, access tokens, private keys, production payloads or unredacted customer records in the review packet.
2. Set the review standard
State what the model must assess and what it must not assume. Paste this instruction above the review packet:
You are assisting with a production pull request review.
Compare the implementation against the ticket acceptance criteria, test evidence and repository conventions supplied below. Do not infer facts that are not present.
For every finding, provide:
- severity: blocker, risk, or note
- location: file and symbol, or “review packet” if no code location exists
- evidence: the relevant ticket criterion, code behaviour, test result, or convention
- consequence if merged
- specific requested change or verification step
Separate confirmed findings from questions. End with one recommendation only: merge, merge after changes, or do not merge. State the conditions required for that recommendation.
Define blocker as a known condition that should prevent merging. Examples include failure to meet an acceptance criterion, an unsafe migration with no recovery path, a security-sensitive change with no required verification, or a failing relevant test.
Define risk as a plausible production concern not proven by the supplied material. A missing load test for a changed hot path may be a risk. Do not present it as proof that the change fails under load.
Use note for maintainability or consistency issues that do not alter the merge decision. This keeps style comments from obscuring operational issues.
3. Run the comparison in passes
Ask for one pass at a time when the change is substantial. This makes gaps visible and stops a polished summary hiding weak reasoning.
- Ticket pass. Ask which acceptance criteria have direct implementation evidence, which have test evidence and which have neither.
- Behaviour pass. Ask for changed execution paths, including failure handling, retries, idempotency, permissions and backward compatibility where relevant.
- Test pass. Ask whether each changed behaviour has an appropriate test. Distinguish unit, integration and end-to-end evidence rather than treating any test as sufficient.
- Convention pass. Ask for deviations from the supplied repository rules. Require a cited rule for every claimed deviation.
- Operations pass. Ask what could affect deployment, observability, rollback, data integrity and on-call response.
For each pass, require the model to quote a short identifying excerpt or name the exact file and symbol. A finding with no source is a question, not a review comment.
Check
Each acceptance criterion has a status
Your working review should show implemented and tested, implemented but untested, not evidenced, or not applicable for every criterion.
4. Check the output against the pull request
Do not paste the first response into the review. Read every blocker and risk against the source material.
The output is likely wrong when it does any of the following:
- Calls a method or file that is not in the supplied diff or context.
- Treats absent evidence as evidence of absence, such as claiming a rollback does not exist when no rollout document was supplied.
- Labels a preference as a blocker without a ticket criterion, test failure or repository rule.
- Repeats the pull request description instead of tracing behaviour through the code.
- Says a test covers a case but cannot identify the test name and assertion.
- Makes a confident claim about runtime behaviour where the relevant configuration, dependency or deployment path was not provided.
For each disputed finding, ask a narrow follow-up. For example: Show the exact changed path that permits duplicate processing. If the evidence is insufficient, downgrade this to a question. This is better than asking for a general rewrite.
Watch out
Do not equate passing CI with readiness
CI can show that selected checks passed. It does not by itself prove the ticket is met, the rollout is safe or the changed failure path is observable.
5. Publish the structured review
Post a review that separates action required before merge from work that can follow later. Use this format:
Merge recommendation: merge after changes
Blockers
- [file:symbol] <finding>. Evidence: <ticket, test, or convention>. Required change: <specific action>.
Risks
- [file:symbol or operational area] <risk>. Why it matters: <consequence>. Before merge: <verification or owner decision>.
Notes
- [file:symbol] <non-blocking observation>.
Acceptance criteria status
- <criterion>: implemented and tested | implemented but untested | not evidenced | not applicable
Evidence reviewed
- Ticket: <identifier>
- Tests: <named results or gaps>
- Conventions: <document or section>
- Operational plan: <present, absent, or not applicable>
Use merge only when no blocker remains and the residual risks are understood and accepted by the person responsible for the change. Use merge after changes when the required work is specific and verifiable. Use do not merge when the change cannot safely meet its stated purpose with the evidence available.
6. Hand over the decision
Tag the pull request author on blockers. Assign each risk a named owner or explicitly record that it was accepted. Link the ticket criterion beside the relevant review comment so the author does not need to reconstruct the reasoning.
If the change affects on-call work, add the operational finding to the release or handover record: what signal should change, what failure looks like and who owns the first response. Keep this separate from code-style notes.
When the workflow does not work
Stop and request more evidence when the ticket is vague, the diff is incomplete, tests cannot be identified or repository conventions are missing. Do not compensate by making stronger assumptions.
If the response is broad or repetitive, reduce the packet to one concern and rerun the relevant pass. If it produces unsupported findings, require file-and-symbol evidence and ask it to downgrade unsupported claims to questions. If the merge decision remains unclear after that, record do not merge or merge after changes with the missing evidence named, then have the responsible engineer decide the next step.
