Task-level coding agents have advanced rapidly and can now execute surprisingly complex engineering tasks. Tools like Devin, Cursor, and Claude Code can navigate large repositories, chain tool calls across dozens of steps, and hand you a diff that looks thorough at first review.

However, every non-trivial task arrives with ambiguity baked in. There are decisions that the codebase cannot answer and that the task description does not imply. Someone still has to make those decisions. The current approach is typically binary: either ask questions before reading anything - often generating questions the codebase itself can answer or skip asking entirely. Both paths land in the same place. The agent resolves ambiguity on its own, without surfacing it - silently, inside the diff.

Wrong-direction code is harder to catch than broken code precisely because it doesn't fail. All tests pass. The PR looks reasonable. The problem surfaces later, when someone notices a constraint was violated.

The pipeline we built at Potpie exists to make those decisions visible before code is generated or a PR is opened.

Stage 1: Questions That Actually Belong to the User

Before Potpie asks any clarifying questions to the user, it first reads and indexes the repository. It greps for existing patterns, traces how similar features are wired, checks which primitives are already in use, and maps where new code needs to land. Anything the codebase can answer confidently, the agent resolves itself, not as a guess, but as a verified convention.

After the repository scan, the remaining questions are the ones the codebase genuinely cannot answer. For example, the agent does not need to ask where the configuration pattern lives; it can read the existing files, identify the established structure, and follow the same convention. By contrast, deciding whether a timed-out request should return a 408 or a 504 is a product decision because it affects a public API contract. Both are defensible. Neither is implied by the codebase. The team has to choose.

This distinction matters because it changes who owns the decision. Repository conventions belong to the agent. Product behavior, failure semantics, rollout scope belong to the user.

Potpie agent asks the 2-3 highest impact blockers first. Then it goes back to the codebase and re-examines through the lens of those answers before deciding whether a second batch of questions is needed. On the timeout task, if the user says 504 and per-route only, the follow up question becomes more focused: should the timeout error be retried by the client, or should it be treated as a terminal failure that must be surfaced immediately? This second question only exists because of the previous response. You can't front-load it.

Stage 2: The Spec Is a Contract, Not a Prompt

Simply appending Q&A responses to a code-generation prompt does not close the gap between intent and implementation. It merely creates a longer prompt and increases the number of assumptions that a downstream agent must interpret correctly.

Before any specification is written, a dedicated research agent performs a structured investigation of the codebase - the same kind of work as Stage 1's scan, but exhaustive. Its job isn't to summarize but to answer the questions a software architect would need to answer before committing to a direction. Every pattern it finds has to resolve to a file and a line, not a confident guess. Independent queries run in parallel: authentication patterns, persistence semantics, and test conventions get checked at the same time because they don't depend on each other.

Every claim needs a file reference. "Use this file as a template" requires a line range. "Wire the feature here" requires pointing at the exact registration pattern. The research output is a verified map of what actually exists.

Then the author agent runs. No filesystem access. It can only work from the verified research output and the answers collected from the user. This is deliberate: the spec should be grounded in evidence the author has explicitly given, not in assumptions the model might invent based on incomplete context or patterns learned during pretraining. Every claim in the spec traces back to something that was actually read.

The spec is where the user pushes back before anything is implemented. If the proposed scope is incorrect, the behavior does not match expectations or key assumptions are flawed, those issues become visible, before a single line of code is written. By the time the planning stage begins, there is a stable artifact to build from. Not a prompt that another agent must reinterpret, but a contract whose requirements are explicit and enforceable.

Stage 3: The Plan Turns the Contract into Build Instructions

The spec tells you what you're building. The plan tells the agent how to build it, in which order, and what done looks like at every step. That distinction matters because code generation at scale fails the same way most complex projects fail - not because the final vision was wrong, but because the work was under-sequenced and intermediate states were never validated.

Potpie's plan is organized into phases not as a simple task list, but as a collection of self-contained implementation modules. Each phase has a specific goal, touches a defined set of files, and has a verifiable done condition before the next one starts. The agent doesn't need to hold the entire implementation in working memory. It builds Phase 1, verifies it, and hands a stable foundation to Phase 2.

At this point, the user sees the full build graph. They can look at Phase 3 and decide to defer remediation tasks to the next release. They can see that Phase 4 can't start until both Phase 2 and 3 are solid. The build order isn't something that surfaces mid-diff; it's visible upfront and negotiable before implementation begins.

Each phase knows exactly where to land and specifies which files it modifies or creates, what the existing shape of those files looks like, and which integration points it connects to. That specificity comes from a focused read of the actual repository, the registration patterns, the template files, the exact line ranges where new behavior plugs in. The agent isn't figuring out where the webhook handler goes. It already knows, and the instruction is grounded in the codebase that was already  mapped.

By the time the user approves the plan, they know what's being built, in what order, and which files are involved. The agent has a bounded execution path - implement the approved plan, validate each phase, and avoid introducing scope that was never agreed on.

Before the First Commit

The agent that ships the wrong code isn't failing because of model quality. It's failing because it never earned the right to start. The pipeline described here exists to change that not by adding process, but by making the agent's assumptions visible before they become diffs.

When it works, the developer's experience shifts in a specific way. Code review stops being where you discover what the agent misunderstood. That happens earlier in the spec, when it's still a paragraph to edit rather than a PR to review. What remains for review is the implementation itself, which is the part that should have always required human judgment.

That's the version of AI coding we're building towards. Not an agent that moves fast and apologizes later. Instead, we are building toward an agent that does its homework first, makes its assumptions explicit, and earns the right to write code.

If that sounds like what's been missing from your workflow, try Potpie.