AI agents now help us produce more code and much larger pull requests. Reviewing those changes is getting harder, especially because many of our code-review habits were formed when humans wrote every line. Over the years, I’ve seen the same few approaches repeat themselves — including some unintentionally funny ones.
One is the rubber-stamp reviewer, who approves almost immediately — sometimes after leaving one ceremonial comment, just to prove that the review contained signs of life. That was never a great approach. It is even worse with agent-written code, because you can no longer assume that the PR author fully understands the change or has taken ownership of it.
My favorite is the senior engineer doing an impression of the most expensive linter in the company. “The explicit type is missing.” “The variable starts with the wrong letter.” “The naming does not follow our convention.” “This line needs a semicolon.” These rules matter, but please encode them in a formatter, a linter, or a CI check. A senior engineer enforcing them one comment at a time is not thorough code review. It is just a very expensive linter.
Then there is the more thoughtful local optimizer. The comments are perfectly reasonable: use LINQ instead of foreach, split this component, extract this logic into a helper, reuse the utility we already have, memoize this value, wrap that callback in useCallback. The code may genuinely improve. The only unanswered question is what the pull request is supposed to do — and whether it works.
These review styles are very different, but they share one limitation: none starts by understanding the change as a whole. I want review to begin there — with the problem, product intent, and design — and only then move toward implementation details.
If I could review only one layer of a change, that is the one I would choose. Does it solve the right problem? Does the behavior match the product intent? Is the responsibility in the right component? A beautifully named private function is not much consolation if the function should not exist, or if the entire feature has landed in the wrong service.
Agent review is good — and still noisy
This matters even more when coding agents write a large share of the implementation. Pull requests can become larger, changes arrive faster, and carefully rereading every line — especially while acting as a human linter — stops being a realistic quality strategy.
At the same time, I do not think it is acceptable for a developer to submit a pull request without understanding what their agent built. I can understand missing an implementation detail. I am much less comfortable with not understanding the intent, the main flow, or the architectural decisions. We still own those decisions, even when we did not type every line ourselves. Without that ownership, the codebase quickly becomes difficult for both humans and agents to extend safely.
The good news is that agents have also become genuinely good code reviewers. GitHub Copilot, Codex, Claude Code's review plugins and specialized agents, and many other options can all inspect a change. I often use cross-review: if Codex wrote the code, I ask Claude to review it; if Claude wrote it, I ask Codex. Different models notice different things, and together they find real bugs, design weaknesses, and missing edge cases.
In my experience, several reviews can provide excellent coverage. But then I have several reviews to read. Some findings are important; others are noise. An optimization may be valid but irrelevant at my scale. A reviewer may misunderstand the feature because it lacks product context. Good repository structure, local instructions, architecture documentation, and tests reduce this problem, but they do not eliminate it.
The developer often knows something the agent cannot infer from the diff. We may know that today's one-to-many relationship is likely to become many-to-many because of conversations with users and stakeholders. Or we may know the opposite: that a supposedly reusable abstraction will never have a second use case. Without that context, an agent can design the change too narrowly or add flexibility nobody needs.
Even a valid finding can become a distraction when it arrives before we have established what the change is supposed to do and which decisions matter most.
The missing piece is the order
What I was missing was not another reviewer. I was missing a review flow that matched how I want to think about a change.
First: what user or business problem are we solving? Is this the right feature, and was there a simpler way to solve the same problem?
Then: does the design put responsibilities, data, and contracts in the right places? If business logic has accidentally moved into a message processor, or a schema change makes the next likely product step unnecessarily painful, I want to discover that before discussing helper methods.
With the intent and design understood, we can review the rest in context: correctness, security, migrations, failure handling, reliability, tests, performance, and simplicity. These concerns are not less important; we can simply evaluate them better once the larger decisions are clear. After all, there is little value in polishing the implementation of a feature we should not be building.
That is the idea behind progressive-code-review. It is not a one-shot request that returns a more or less random collection of comments. It is a staged, developer-controlled review process. The skill first helps me understand the change and choose the questions that matter. It then works through those questions in an order where an early answer can challenge the assumptions behind later reviews.
This takes longer than a quick automated scan. The trade-off is a deeper review with less misplaced effort. A developer can use it to inspect their own agent-generated change before opening a pull request. A human reviewer can use it to understand a large pull request in advance and arrive at the conversation with more focused questions. In both cases, the developer remains responsible for the decisions; the agent helps make sure we examine them.
How the progressive review works
A review lens is simply a focused perspective on the same change. I use a similar approach in design-lens-workshop, a standalone adaptation of Specrew's Design Workshop for technical design. In progressive-code-review, the lenses are applied to implemented code and arranged so that earlier conclusions can change or invalidate later review work.
The goal is not to maximize the number of findings. It is to ask the questions that can still change the outcome, in the right order.
The skill has seven available review lenses:
- purpose and behavior;
- architecture, data, and contracts;
- security and privacy;
- experience and accessibility;
- correctness and tests;
- production readiness;
- simplicity and code health.
The skill first probes all seven lenses. Only lenses with a concrete warning or unresolved evidence gap are promoted to standard or deep review; the rest are covered by the initial analysis or skipped as irrelevant.
The review proceeds in five stages:
- Understand the task and the change: establish the boundary, identify unrelated change groups and ask which belong in this review when necessary, find the task or specification, reconstruct the before-and-after flow, and probe every lens.
- Explain the change and propose a focused agenda showing what is already checked, what needs detailed review, at what depth, and why. I can adjust the selection, depth, and order. For a large, ambiguous, or risky change, detailed review begins only after I confirm the agenda.
- Review the selected lenses one at a time. Before and after each lens, explain in plain language what is being checked, what evidence held up, and what happens next. Each detailed review ends with a plain-language result and waits for me to continue.
- Pause on any merge-blocking finding, any issue that can change the task, scope, or design, or a critical evidence gap. I decide whether to fix it, accept or defer the risk, or narrow the scope. After a fix, a separate reviewer with fresh context reruns the current lens; the reviewer that found the issue does not approve its own fix. If the fix expands the change, the initial analysis and agenda run again.
- Return a verdict and a compact, ready-to-paste PR handoff with the purpose, key decisions, important risks or non-goals, validation, and reviewer focus.
For example, a webhook deduplication change may need a quick check across all seven lenses, but only a few deserve deeper work. Purpose asks what counts as a duplicate. Architecture and contracts examine the idempotency key and where it is stored. Production readiness traces retries and crash windows. Accessibility may already be clear if no user interface changed. If the deduplication identity is wrong, the review pauses there before discussing helper methods or naming.
Detailed evidence and decisions are saved in a local checkpoint under .review/. It may appear in git status, but it is excluded from the reviewed diff and never staged automatically. The PR handoff is intentionally short — normally no more than 180 words — because a human reviewer needs the decisions that explain the change, not a transcript of every stage.
Review-only by default
The skill reviews code; it does not silently rewrite it.
Except for that checkpoint, the review does not edit product files, change the Git index or local history, switch the current branch, push, or publish a pull request. It may use non-destructive Git inspection, including fetching missing refs, without asking for permission. The skill records repository state before and after review work. If reviewed code or evidence changes in a way that could invalidate the review, it stops; unrelated changes are only noted.
If I explicitly ask to fix a finding in the same task, the skill does not refuse. It saves the paused review state, recommends a separate implementation task for cleaner context but does not require one, and suspends review while the authorized fix is made.
When to use it
The skill activates only when explicitly invoked or when I explicitly ask for a progressive or staged branch review. An ordinary request for code review should remain an ordinary review.
I would use it when:
- an agent has finished a non-trivial feature and I want to review it before the PR;
- a change crosses components, contracts, persistence, UI, or operational boundaries;
- the implementation is plausible, but I want to challenge its purpose and design before polishing details;
- findings may need to be fixed and re-reviewed without losing the decisions already made;
- I want the final PR description to explain the important choices and remaining risks.
I would not use it for every small patch. A mechanical rename, a narrow test update, or an obvious local bug fix may need only deterministic checks and a normal focused review.
The extra depth also costs time and model tokens. That is a deliberate trade-off. The skill is useful when the cost of reviewing in the wrong order is higher than the cost of running several focused review stages.
Current branch or another branch
The simplest invocation reviews changes introduced on the current branch relative to its inferred base, plus staged, unstaged, and untracked work:
/progressive-code-review
It can also review committed changes on another branch without switching the current checkout:
/progressive-code-review --branch feature/catalog-cache
/progressive-code-review --branch feature/catalog-cache --base main
You can add context directly to the invocation:
/progressive-code-review
Review my current branch before I open the pull request. Payment-provider
webhook events may be retried for up to 72 hours and arrive out of order.
A duplicate must never create a second payment, but valid delayed events
must still be processed.
You can also ask specific questions about the change:
/progressive-code-review
Review only the backend changes. Why were MasteryBefore, MasteryAfter, and
LessonId added? Also explain how the service and endpoint flow changed.
Install and try it
The skill is available in the public Zio-Net skills repository.
The commands below require GitHub CLI 2.90 or newer.
Preview it with GitHub CLI:
gh skill preview Zio-Net/skills progressive-code-review
Install it for Codex at project scope:
gh skill install Zio-Net/skills progressive-code-review --agent codex --scope project
For Claude Code, replace codex with claude-code. The repository follows the open Agent Skills structure, so the skill can also be copied manually into the appropriate skills directory.
In conclusion
AI-assisted development does not remove the need for code review. It changes where the review happens and how much code can arrive before a human has challenged the underlying decisions.
For me, progressive-code-review is a way to keep that responsibility visible. It asks the important questions in an order that respects their dependencies, preserves the evidence and decisions between stages, and leaves the developer in control of both the findings and the fixes.
The goal is not to run more review for its own sake. It is to spend review effort where it can still change the outcome.
If you try it, I would be glad to hear your feedback and ideas for improving it.
