Plan-Gated AI Implementation

Last updated: 2026-03-19

When to use this lesson

Use this lesson whenever the task is larger than a tiny local edit: multi-file implementations, refactors, architecture changes, new pipelines, importer/adapter work, dashboard redesigns, documentation sweeps, workflow skills, or any situation where the AI could silently make meaningful design decisions on the user's behalf.

The repeated failure pattern across these sessions was not inability to implement. It was premature execution. The agent often understood the goal and then immediately chose an architecture, decomposed the work, touched many files, and only later discovered that key assumptions were wrong, under-specified, or contrary to the user's mental model.

The core rule is simple:

When the task has meaningful design surface area, do not jump straight from request to edits. Insert a planning gate.

The agent's job is not just to move quickly. It is to prevent avoidable wrong-branch work by turning high-level intent into a visible implementation plan before substantial execution begins.

Core workflow

For non-trivial work, default to this sequence unless the user clearly asks to skip it:

Restate the goal and scope.

Surface the key design decisions or unknowns.

Propose a plan with phases, files, interfaces, and invariants.

Wait for confirmation, or explicitly say you are proceeding on assumptions.

Implement in bounded phases.

Pause at checkpoints with summaries before expanding scope.

Review what changed and what remains unverified.

If the task is small, compress this workflow rather than omitting it entirely. A three-line plan is often enough:

approach
affected files/components
validation path

Why this matters

Across many sessions, the AI became the de facto architect because the prompt only named a goal:

“Implement Phase 1” turned into a full system design before architecture was reviewed.
“Move on to step 2” caused the AI to invent fallback behavior and path rules that later had to be corrected.
“Redesign this dashboard” was treated as permission to choose interaction semantics, layout model, and implementation layering without confirmation.
Repo-wide updates expanded from a narrow request into scripts, docs, config, tests, and structural cleanup without explicit buy-in.

The better sessions had some visible structure first:

a repository audit or design pass before implementation
a lightweight architecture summary before code generation
a user checkpoint that challenged a proposed workaround and forced a cleaner system design
phased execution where one vertical slice was implemented before scaling out

The lesson is not “ask more questions” in the abstract. It is: make major design choices visible before they become code.

How to detect when a planning gate is needed

Insert a planning gate when any of these are true:

the task touches multiple files or subsystems
the request implies architecture, not just a local edit
there are multiple plausible approaches
the task changes schemas, workflow semantics, storage, or interfaces
the work will be expensive to redo
the user gives a high-level product goal but not the implementation envelope
the task could invisibly expand into docs, tests, scripts, config, and UI together
the request references a phase, step, or integration without restating requirements

Execute immediately only when the change is isolated, constraints are clear, architecture is already established, and the cost of a wrong guess is low.

What the plan should contain

The plan should reduce ambiguity, not create bureaucracy. Include the minimum structure needed to protect against wrong-branch execution.

A good plan usually includes:

objective and out-of-scope boundaries
affected files or subsystems
proposed architecture or workflow shape
key interfaces, artifacts, or outputs
constraints that must remain true
risky assumptions or open questions
what will be validated after each phase

For code or refactor tasks

Include:

target architecture
module/file boundaries
compatibility constraints
whether the work is one-shot or a phase in a larger refactor
what will be tested or inspected afterward

For UI or product changes

Include:

layout or interaction model
state and data-flow assumptions
implementation layers, such as layout -> data wiring -> interactions -> polish
visual acceptance criteria if known

For pipeline or automation work

Include:

stage order
prerequisites and environment assumptions
expected artifacts per stage
recovery or resume points

For docs or repo-wide content changes

Include:

documents to update
claims to verify against code or source artifacts
whether the task is descriptive only or also restructures information architecture

How to scaffold without offloading the job to the user

This is an agent-facing lesson. Do not tell the user they should have planned more. The agent should proactively create the structure.

Useful patterns:

“Before I edit, here’s the implementation plan and the files I expect to touch.”
“There are two viable designs here; I recommend X because Y. If you agree, I’ll implement that.”
“Because this changes workflow semantics, I want to lock the plan first, then I can implement in one pass.”
“The main open question is whether you want A behavior or B behavior. I’ll pause there.”
“I see this as four stages: contract, plumbing, one vertical slice, then rollout.”

If the user is moving quickly and does not want a design discussion, compress the planning gate. Do not silently remove it.

Bounded execution: avoid hidden scope growth

Once implementation starts, keep the work contained.

Good pattern:

implement one phase
summarize what changed
note newly discovered implications
ask whether to continue if scope broadens

Bad pattern:

start with a narrow request
discover adjacent cleanup opportunities
silently expand into new modules, docs, scripts, and architecture changes
present the whole thing as a completed bundle

Several sessions showed the AI growing a task from feature work into architecture work without explicit buy-in. That is only helpful when clearly announced and justified.

Decision criteria for ambiguous situations

If the user says “just do it”

Still insert a lightweight plan:

one sentence on approach
one sentence on files/components affected
one sentence on validation
then proceed

If the user already provided a strong spec

Do not force an extra design loop. Convert their spec into an execution checklist and proceed.

If the task is exploratory

Use proposal-first mode. Offer options, tradeoffs, and a recommendation before code.

If implementation has already started and an architectural flaw appears

Pause and explicitly pivot. Do not keep layering patches onto a bad plan. When a deeper contract issue appears, rethink the approach rather than hiding the pivot inside more code.

If exploration of the repo is needed

Do not let exploration substitute for planning. Summarize what is missing and what decision depends on it.

Anti-patterns to avoid

1. AI as silent architect

The user gives a broad goal; the AI chooses the architecture, sequencing, abstractions, and semantics without surfacing them. This feels fast but weakens alignment and makes later correction expensive.

2. One-pass big-bang execution

Large repo restructures, dashboard rewrites, importer builds, or workflow overhauls done end-to-end in one pass are hard to review and easy to misalign.

3. Planning after coding

If interaction model, schema, CLI semantics, or data flow is still unsettled, do not implement yet. Planning after code generation usually means rework.

4. Implicit constraints

Do not assume backward compatibility, file boundaries, environment behavior, rerun semantics, or docs coverage unless you say them explicitly.

5. Treating references as a complete spec

Reference repos, plans, and adjacent implementations are helpful, but they do not replace an explicit statement of how this codebase should behave.

6. Implementing and reviewing your own design with no pause

When the same AI invents the architecture and immediately implements it, error detection drops. Create a pause point by summarizing design choices before coding.

Recommended operating pattern

For substantial tasks, use this template internally and often explicitly in chat:

Step 1: Frame

What is being built or changed?
What existing pattern should it follow?
What outputs or artifacts should exist after completion?

Step 2: Bound

What files or modules are in scope?
What constraints are implied?
What assumptions remain unknown?

Step 3: Sequence

What are the 2–5 implementation stages?
What should be verified after each stage?

Step 4: Execute

Implement one approved stage or batch.

Step 5: Review

Summarize changes, unverified areas, and next checkpoint.

What success looks like

A strong collaboration on substantial work should feel like this:

the user sees the shape of the solution before edits begin
the AI makes design choices explicit rather than hiding them
execution proceeds in phases rather than as an opaque blob
any scope increase is announced and justified
architectural pivots happen early, not after large batches of code
the user remains the decider on meaningful design questions while the AI does the implementation work

The goal is not to slow the session down. The goal is to preserve the speed of delegation without letting the AI become an unreviewed architect by accident.