Skip to main content

3. Guiding Phase (~ 1–6 hours)

Guided Coding workflow diagram highlighting the Guiding Phase. The three phases are Planning, Implementing, and Guiding, with arrows showing iteration back to Planning for large issues or back to Implementing for small issues.1. Planning Phase2. Implementing Phase3. Guiding Phase✓ PR

The most important part of Guided Coding​

This is the most important and time-consuming phase. You review all the generated code:

  • Read the code yourself. You are responsible for the code the LLM produces. You need to understand it.
  • Also let another agent review. I usually open a new conversation and use review features of coding agents for an additional code review.
  • Learn what you don't know. If the agent wrote something you don't understand, learn that concept before judging it. Ask the model to explain it.
  • Decide on the appropriate response:
    • If everything looks good → success, close the record and create the PR.
    • If there's a small issue → iterate back to the Implementing Phase with a targeted prompt.
    • If there's a large issue (wrong data structures, framework mechanisms misused, design flaws) → go back to the Planning Phase and write a follow-up plan.
  • Make manual changes if needed. Your coding agent doesn't need to do all the work — use it as a tool to write the code you would write yourself, just faster.
  • Close the record. Follow-up plans always require a Plan Deviations document; with a single plan, write one only for material departures.

There is no skill for the review itself, and there never will be. An agent can give you a second opinion, and a useful one. It cannot take responsibility for the code. That transfer is the thing Guided Coding exists to prevent.

How to Review​

  • Read every changed file. Don't skim — read the code line by line. Pay attention to naming, structure, error handling, and edge cases. If something feels off, it probably is.
  • Evaluate the design. Step back and look at the bigger picture. Are the abstractions appropriate? Is the code well-structured and easy to extend? Watch out for over-engineering, unnecessary indirection, or patterns the agent introduced that don't fit the existing architecture.
  • Check the acceptance criteria. Go through the plan's criteria and verify each ticked box yourself. An agent that ticks a criterion it did not actually satisfy is the single most expensive mistake in this workflow, because it looks like progress. Unchecked criteria are equally informative — they tell you what is left.
  • Run the automated tests. Even though the agent likely ran them during implementation, run them again yourself. Check that coverage is adequate and that the tests actually assert meaningful behavior. Pay special attention to the assertion phase — agents tend to write weak or incomplete assertions. A test that only checks for "no exception thrown" or verifies a single property when it should verify the full expected state gives you a false sense of safety.
  • Do a manual smoke test. Start the application and exercise the feature end to end. Automated tests can't catch everything — visual glitches, subtle UX issues, or integration problems with external systems often only surface when you use the app.
  • Check for regressions. Look beyond the feature itself. Did the agent accidentally change something unrelated? A quick scan of the full diff helps catch unintended side effects.
  • Verify non-functional aspects. Depending on the feature, check performance characteristics, logging, error messages, and security boundaries. These are easy for agents to overlook or handle superficially.

It takes experience to review the code produced by a Coding Agent. Educate yourself to become a better reviewer over time, don't be afraid to ask your (non-AI) colleagues if something is unclear and you think the coding agent is hallucinating.

The Opinionated Path

I review the changes myself first, then optionally open a fresh conversation and have another agent review the outcome of the Implementing Phase. Two independent passes catch different things: I catch design and intent problems, the agent catches the mechanical ones I skimmed past at file number thirty.

When we find something, I decide between two responses. Either I simply prompt to fix it — iterating back to the Implementing Phase — or the flaw is large enough that it deserves a new plan, in which case I go back to the Planning Phase and run the whole loop again with a follow-up plan.

Iterating​

Large issues in the guiding phase usually mean your plan was too big to begin with. This happened to me with a cloud events serialization feature — I tried to implement reading and writing in one plan. The result had too little code reuse and suboptimal performance, so I went back and created three smaller, focused plans to address each aspect separately.

When you go back to Planning, you write a follow-up plan rather than editing the original one. The original plan stays frozen: it records what you decided before you knew better, and the follow-up records what you learned and which of those decisions it supersedes. Both together are more useful than one tidied-up document — the reason a design changed is often more valuable than the design itself. See The Plan Record.

Don't be afraid to go back to the planning phase! In software development, it's long been established that iterative approaches benefit overall quality. Iterate until you're satisfied with the result.

Closing the Cycle​

Once you are satisfied with the implementation, ask one question: does the finished code still match what the plans decided?

If follow-up plans exist, always write a Plan Deviations document. It summarizes which decisions changed across those plans and what the finished code does, giving the reviewer one closing record instead of a scavenger hunt through several files.

With a single plan, write one only when the implementation materially changed an explicit decision — an acceptance outcome, a public contract, an architectural boundary, a security or performance constraint. Don't write one for routine implementation choices the plan deliberately left open; entries that don't matter bury the ones that do.

The aim is a specific promise to whoever reviews the PR: reading the issue's first plan and, when one exists, the Plan Deviations document is enough to understand the whole change. The Plan Record covers what belongs in such a document.

The Opinionated Path

I run /guided-coding-write-deviations. It reads every plan for the issue and inspects the complete implementation delta. Follow-up plans always produce a document. With a single plan and no material deviations, the skill says so and writes nothing.

The skill writes the document and stops. I review it and request corrections with ordinary prompts until I accept it. Then I commit it, create the pull request, and use its contents as the PR description — either manually or with a normal prompt to the agent.