AI-assisted coding needs ambiguity checkpoints

AI-assisted coding changes the shape of engineering work because it moves effort from typing to judgment. A model can produce a plausible implementation quickly, sometimes with useful tests and a clean explanation. That speed is real. The risk is also real: a change can compile, pass a narrow happy path, and still hide unresolved product assumptions, risky shortcuts, missing tests, or debugging uncertainty.

The thesis is simple: AI-assisted coding needs ambiguity checkpoints. Not more ceremony, not a second code review, and not a vague reminder to be careful. A checkpoint is a small, explicit handoff moment between the generated draft and the review packet. Its job is to capture what the AI made look finished but a human still has to own.

Addy Osmani describes the pattern as the “70% problem”: AI can get work most of the way toward a working solution, while the final portion requires human handoff, ambiguity navigation, debugging, and staying in the loop when machines do much of the typing. That framing matters because the last 30% is not just cleanup. It is where ownership becomes visible. See Osmani’s recap of AI-assisted engineering for the source framing behind this article: AI-Assisted Engineering: My 2025 Substack Recap.

The last 30% is a handoff problem

The failure mode is not always bad code. It is often good-looking code with unclear ownership.

A developer asks an AI coding tool to add a setting, refactor a component, generate a migration, or wire a new API response into an interface. The output looks coherent. The files are touched in plausible places. The naming is consistent enough. The model explains what it did with confidence. The team feels momentum.

Then review starts and the ambiguity leaks out. Why was this behavior chosen for the empty state? Was the migration designed for old records or only new ones? Did the agent follow the intended authorization boundary or copy the nearest pattern? Are these tests proving the business rule or only freezing the generated implementation? Who checked the edge case that was mentioned in the ticket but not present in the prompt?

If the first time these questions appear is code review, the review is doing two jobs at once. It is evaluating the change and reconstructing the intent. That is expensive. It also creates the wrong incentives. Reviewers may focus on style, naming, and obvious bugs because the deeper uncertainty is not packaged for them.

This is why acceptance criteria still matter. A related article, AI coding needs acceptance criteria first, argues that the prompt should not be the first place where the team defines done. An ambiguity checkpoint extends that idea downstream. Even with good criteria, generated work will reveal places where the criteria were incomplete, the codebase had hidden conventions, or the implementation path forced a tradeoff.

What belongs in an ambiguity checkpoint?

An ambiguity checkpoint should be small enough to use on real work. If it becomes a document nobody updates, it will be skipped. The point is to make the handoff inspectable before review, not to create a compliance archive.

Use five fields.

First, list unresolved product assumptions. These are not implementation notes. They are statements like: “I assumed the default state should show the legacy label until the user saves,” or “I assumed admins and owners share the same permission path.” If the assumption changes the user experience, data model, pricing rule, or operational behavior, it belongs here.

Second, list implementation shortcuts. AI-generated code often follows the most available local pattern. That can be fine, but the reviewer should not have to discover it by reading every diff. Write the shortcut plainly: “Reused the existing parser although it does not validate unknown fields,” or “Kept the synchronous call because the surrounding flow is synchronous.” A shortcut is not automatically wrong. Hidden shortcuts are the problem.

Third, list missing tests. Not just “needs more tests,” which is useless. Name the absent proof: “No test for deleted account state,” “No fixture with multiple currencies,” “No migration rollback test,” or “No browser-level test for keyboard navigation.” This gives the reviewer a map of risk instead of a generic request for diligence.

Fourth, list debugging notes. This is where the human records what looked suspicious while working with the model: failed attempts, confusing stack traces, flaky behavior, regenerated sections, or places where the model contradicted itself. These notes are especially valuable because AI-assisted work can hide exploration. The final diff may look linear even when the route to it was messy.

Fifth, name the owner for the final judgment. Not the author by default, and not “the team.” If a product assumption needs PM confirmation, name the PM. If a data migration needs staff engineering review, name that person or role. If security posture is unclear, name the approver. Ownership has to follow the ambiguity, not the commit.

Where does this differ from code review?

An ambiguity checkpoint happens before code review and has a different purpose.

Code review asks, “Should this change enter the codebase?” The checkpoint asks, “What still requires human judgment before that question can be answered?” That difference is subtle but important. Review is a decision surface. The checkpoint is a preparation surface.

Without the checkpoint, review packets become overloaded. The article AI coding agents need review packets covers the need to package AI-generated work so reviewers can see intent, scope, and evidence. The ambiguity checkpoint is one ingredient in that packet. It is the part that admits what is not settled.

This is also where teams should avoid the performance of certainty. An AI assistant may produce a beautiful summary: files changed, functions added, tests updated. That summary is useful, but it is not enough. A human should add the parts the model is least qualified to own: business meaning, risk tolerance, production context, and what was deliberately not solved.

A good checkpoint is not a confession that AI failed. It is proof that the team stayed in the loop. It says: here is where the machine accelerated us, here is where the codebase pushed back, and here is where a person must decide.

How should a team introduce the checkpoint?

Start with one class of work, not every change. Pick AI-assisted changes that touch product behavior, data persistence, permissions, billing, onboarding, or customer-visible workflows. Do not begin with harmless copy edits or mechanical refactors. The checkpoint is most valuable where plausible output can create real ambiguity.

Add a short template to the pull request description or review packet:

• Product assumptions:
• Shortcuts taken:
• Missing tests:
• Debugging notes:
• Owner for final judgment:

Keep the fields empty only when they are truly empty. “None noticed” is better than silence because it makes the author make a claim. If a reviewer later finds an unlisted assumption, the team has something to improve in the next checkpoint.

The checkpoint also helps PMs participate without pretending to review code line by line. A PM can read the product assumptions and decide whether behavior matches the intended outcome. An engineering lead can scan shortcuts and missing tests. A reviewer can focus on the diff with the right risk model in mind.

This does not replace rollback thinking. For production-sensitive AI work, AI coding agents need rollback plans is still the next layer. The ambiguity checkpoint answers what judgment is needed before merge. A rollback plan answers how the team recovers if its judgment was incomplete.

Make one checkpoint before the next merge

The practical test is simple. Take one AI-generated change this week and mark the first point where human judgment became necessary. Was it when the model chose a data shape? When it inferred a business rule? When it skipped a test? When debugging moved from syntax to system behavior? That point is the checkpoint.

Do not measure the practice by whether it slows the first pull request. It may. Measure it by whether review becomes clearer, whether assumptions stop hiding inside generated code, and whether ownership moves to the person best equipped to decide.

AI-assisted coding is not dangerous because it writes code. It is dangerous when teams confuse plausible progress with accountable delivery. Ambiguity checkpoints make the handoff visible. They preserve the speed of AI assistance while forcing the final 30% back into the open, where product judgment, engineering judgment, and ownership can do their work.