Decompose one change into supervised passes

2041. Lesson identity

Module

5.3 — AI orchestration

Lesson

Decompose one change into supervised passes

Academic type

Systems

Schema type

text

Order

1

Estimated time

35–45 minutes, including practice

This lesson establishes a repeatable orchestration pattern for a bounded multi-file change: plan it, create a recoverable checkpoint, implement it, validate it, and review the result without allowing one pass to silently make decisions for the next.

2042. Learning objective

After this lesson, you can produce an orchestration plan for a bounded multi-file change that defines task boundaries, pass-specific outputs, a recoverable checkpoint, a change association, acceptance criteria, and handoff artifacts.

2043. Why this matters

A request that sounds small to a human can cross several files, systems, and assumptions. If an AI agent plans, edits, tests, and approves the same change in one uninterrupted pass, errors become difficult to locate and easy to rationalize. Explicit passes preserve human control over scope and create evidence for each decision. A recoverable checkpoint limits the cost of an incorrect implementation, while a change association lets you trace the intended change from its approved plan through its files and validation evidence.

2044. Prior knowledge

You should already be able to diagnose ambiguity and unsafe assumptions in an AI prompt, as practiced in 5.2 L2 — Diagnose a prompt that invites unsafe code. En español, la dependencia es 5.2 L2 — Diagnosticar un prompt que invita a código inseguro. You should also be familiar with acceptance criteria, constrained requests, and asking an AI system to expose assumptions before it proposes an implementation.

2045. Core concept

The core concept is task boundaries with recoverable, traceable handoffs.

A supervised orchestration plan does not treat “make the change” as one task. It divides the work into passes, and each pass has:

1. A narrow responsibility.
2. An explicit input.
3. A defined output artifact.
4. A stopping condition.
5. A human review point before the next pass begins.
6. A recoverable checkpoint before implementation changes the project.
7. A change association that links the approved request, checkpoint, changed files, and validation evidence.

The four passes in this lesson are:

• Planning: map the change, dependencies, risks, and acceptance criteria without editing files.
• Implementation: apply only the approved change within the defined file and behavior boundary.
• Validation: gather evidence that the intended behavior works and that relevant regressions were not introduced.
• Review: compare the result with the plan, inspect scope and quality, and decide whether to accept, revise, or stop.

Before implementation, create a named recoverable checkpoint of the project state. The checkpoint may be the repository or project snapshot mechanism available in your environment; the important properties are that it can be identified, restored, and associated with this change. Do not treat a checkpoint as approval. It is a recovery boundary, not a quality judgment.

Planning is not a weaker implementation pass. Validation is not the same as review. Each pass answers a different question.

2046. Mental model

Use the four-pass handoff chain with checkpoint and change association:

The change association is a small traceability record:

Change request → approved plan → recoverable checkpoint → changed files → validation evidence → review decision

Every stage must refer to the same change identifier or clearly named change description. If a file, test result, or decision cannot be associated with the intended change, stop and resolve the association before continuing.

The handoff rule is simple: a pass may consume the previous artifact, but it may not silently replace the previous decision. If implementation reveals a new dependency, return to planning or record the explicit scope decision before continuing. If the implementation cannot be safely associated with the checkpoint or approved plan, stop rather than proceeding with an ambiguous state.

A useful control sentence for every pass is:

“Do only this pass. Do not perform the next pass. Stop when the handoff artifact is complete.”

2047. Concrete example

Suppose the bounded change is: add a cooldown indicator to an existing ability without changing the ability’s timing rules.

A weak request is: “Add a cooldown UI and make sure it works.” It leaves the AI to decide which files to change, whether timing logic should be rewritten, and what counts as working.

A supervised plan separates the decisions:

Planning pass

• Assign a change identifier, such as ability-cooldown-indicator.
• Identify the existing ability state that exposes cooldown information.
• Identify the UI component responsible for displaying ability status.
• Confirm that the timing rule remains unchanged.
• Define observable acceptance criteria: the indicator shows the unavailable state during cooldown, updates when the ability becomes available, and does not alter activation timing.
• Record uncertain dependencies instead of guessing.

Handoff artifact: a file and dependency map, assumptions, acceptance criteria, proposed files, and the change identifier.

Checkpoint control

• Create a named, recoverable checkpoint immediately before implementation.
• Record its identifier beside ability-cooldown-indicator.
• Confirm that restoring or inspecting the checkpoint is possible before authorizing edits.

Handoff artifact: a checkpoint record associated with the approved plan.

Implementation pass

• Read the approved plan and checkpoint record.
• Modify only the approved presentation and integration points.
• Do not rewrite the timer, add unrelated cleanup, or change input behavior.
• Report every changed file and any deviation from the plan.
• Refuse or stop if the requested edit requires an unapproved file, changes timing rules, cannot be associated with the change identifier, or would make the checkpoint unusable.

Handoff artifact: the diff summary, changed-file list, implementation notes, deviations, and the association between the change identifier, checkpoint, and files.

Validation pass

• Exercise the ability before, during, and after cooldown.
• Check the acceptance criteria one by one.
• Inspect whether activation timing remains unchanged.
• Record observed failures rather than correcting them during validation.
• Stop validation without editing if the tested files do not match the associated implementation, the checkpoint or change identifier is missing, or the evidence cannot be attributed to this change.

Handoff artifact: a criterion-by-criterion result table with reproduction details for failures and references to the associated change.

Review pass

• Compare the changed files with the approved boundary.
• Confirm that the change is associated with the recorded checkpoint and validation evidence.
• Compare the evidence with the acceptance criteria.
• Decide whether the change is accepted, returned for a specific correction, or stopped because the scope or traceability is no longer bounded.

The implementation pass produces a change, but it does not declare the change correct. The validation pass produces evidence, but it does not silently fix the code. The review pass makes the acceptance decision. The checkpoint provides recovery, and the association provides traceability.

2048. AI-native workflow

Use the AI as a participant in each pass, not as the owner of the entire change.

1. Planning prompt: provide the change request, available project context, constraints, and a prohibition on editing. Ask for a file map, assumptions, risks, acceptance criteria, open questions, and a proposed change identifier.
2. Human planning gate: reject guesses, narrow the file boundary, and resolve or explicitly preserve open questions. Do not authorize implementation until the plan is specific enough to inspect.
3. Checkpoint gate: create and record a recoverable project checkpoint. Ask the AI to confirm the checkpoint identifier and intended association, but verify the checkpoint yourself before allowing edits.
4. Implementation prompt: provide only the approved plan and checkpoint association. Ask for the smallest implementation within scope. Require a changed-file list and deviation report.
5. Implementation refusal condition: instruct the AI to refuse and stop if it discovers an unapproved dependency, needs to edit outside the approved boundary, cannot preserve the specified behavior, cannot associate the edits with the change identifier, or cannot work from the recorded checkpoint.
6. Human implementation gate: inspect the diff or project changes. If the agent changed scope, decide whether to return to planning or reject the deviation.
7. Validation prompt: provide the acceptance criteria, changed-file list, checkpoint association, and change identifier. Ask the AI to execute or describe checks without modifying the implementation. Require observed results and reproduction details.
8. Human review gate: compare the plan, checkpoint, diff, association record, evidence, and final decision. Retain the acceptance decision yourself.

Do not combine these prompts into one instruction such as “plan, implement, test, and review this feature.” That removes the handoff points that make supervision possible.

2049. Common mistake

The common mistake is treating a longer prompt as equivalent to a decomposed workflow. Adding “be careful,” “test everything,” or “do not break anything” does not create task boundaries. A single uninterrupted agent run can still select its own scope, change the plan while implementing, mark its own output as validated, and overlook an assumption it introduced.

Another mistake is creating a checkpoint without associating it with the change. A snapshot with no name, identifier, or link to the approved plan cannot reliably support recovery or investigation. Record the association before implementation and update it with the actual changed files.

A further mistake is allowing validation to repair failures. When validation edits the implementation, its evidence no longer describes the change that was tested. Record the failure, return to the appropriate pass, and generate new evidence after the correction.

2050. Guided practice

Create an orchestration plan for this bounded change:

Add a visible “interacting” state to an existing interaction prompt. The interaction rule and input binding must remain unchanged. The change may require more than one file, but it must not introduce a new interaction system.

Complete the following steps:

1. Assign a concise change identifier. Write one sentence defining the behavior boundary and one sentence defining what is out of scope.
2. Create a planning-pass handoff containing likely files or system boundaries, assumptions to verify, three acceptance criteria, two risks, and questions that must be answered before editing.
3. Define a named, recoverable checkpoint to create before implementation. State what evidence would confirm that it can be restored or inspected.
4. Create a change-association record linking the change identifier to the approved plan, checkpoint, proposed files, eventual changed files, validation evidence, and review decision.
5. Write an implementation-pass instruction that names the approved boundary and requires a changed-file list.
6. Add this refusal condition: “If you need an unapproved file, discover a new interaction system, cannot preserve the existing rule or input binding, or cannot associate the edit with the recorded checkpoint and change identifier, refuse to edit and stop. Report the blocking condition.”
7. Write a validation-pass instruction that forbids code changes, requires criterion-by-criterion evidence, and stops if the implementation, checkpoint, or test evidence cannot be associated with the same change identifier.
8. Write a review decision rule with three possible outcomes: accept, return for a targeted correction, or stop and re-plan.
9. Identify one condition that would force a return to planning, such as discovering that the interaction prompt is generated by a system outside the original boundary.

The meaningful decision is your boundary choice: decide what the AI may inspect, what it may edit, what must be associated with the checkpoint, and what requires authorization before the next pass.

2051. Practical submission rubric

Score the completed orchestration plan on seven criteria. Award 2 points when the control is specific and executable, 1 point when it is present but vague or incomplete, and 0 points when it is absent or nonfunctional.

1. Boundary quality: authorized behavior, files or systems, and exclusions are explicit.
2. Pass-specific artifacts: every pass produces an artifact that the next pass can actually consume.
3. Checkpoint recoverability: the checkpoint is named, associated with the change, and supported by restoration or inspection evidence.
4. Traceability: the identifier connects the request, approved plan, checkpoint, actual files, validation evidence, and review decision.
5. Stop conditions: every pass states when it must stop rather than expanding or repairing scope silently.
6. Human decision gates: authorization and acceptance decisions have explicit human owners between passes.
7. New-scope handling: newly discovered dependencies trigger refusal, escalation, or a return to planning.

A plan is adequate at 11 of 14 points or higher, with no zero in boundary quality, checkpoint recoverability, or traceability. Revise any handoff that names an artifact but does not specify enough information for the next pass to proceed safely.

2052. Validation / evidence

Your work is sufficient when you can point to a single orchestration plan containing:

• a bounded change statement and change identifier;
• separate planning, implementation, validation, and review responsibilities;
• a named recoverable checkpoint created before implementation;
• an explicit association between the change, checkpoint, approved scope, actual changed files, validation evidence, and review decision;
• a stopping condition for each pass;
• at least one handoff artifact for each transition;
• observable acceptance criteria;
• an explicit human decision gate between passes;
• an AI refusal-and-stop condition for unapproved scope, unsafe assumptions, or broken traceability;
• a validation stop condition when evidence cannot be associated with the same change;
• a rule for handling new scope or dependencies.

A strong plan lets another developer determine which pass produced an error, recover the pre-change state, and trace the evidence to the intended change without rereading an entire conversation or guessing what the agent was authorized to do.

2053. Key takeaways

• A multi-file change should be divided by responsibility, not merely described in more words.
• Planning, implementation, validation, and review answer different questions and produce different evidence.
• A recoverable checkpoint provides a known pre-change state; it does not replace review or acceptance.
• Change associations connect the request, plan, checkpoint, files, evidence, and decision into one traceable record.
• AI refusal and stop conditions prevent silent scope expansion and ambiguous handoffs.
• Validation should observe and record; it should not silently repair the implementation.

2054. Next lesson

Next: 5.3 L2 — Build a human-in-the-loop change sequence. You will use the orchestration plan produced here to mark decision ownership, inspection stops, escalation routes, and the authorization required to begin each subsequent pass.

2055. Knowledge check