Plan a staged multi-system change

2154. Lesson identity

Module

5.6 — Large codebase strategy

Lesson

Plan a staged multi-system change

Academic type

Workflow

Schema type

mixed

Order

2 of the module

Estimated time

35–45 minutes, including practice

2155. Learning objective

After this lesson, you can break a broad multi-system request into sequenced stages, define the compatibility evidence for each stage, and identify when uncertainty requires escalation before implementation.

2156. Why this matters

A broad request can sound like one feature while crossing several ownership boundaries. In a game codebase, changing the visible behavior may also affect state, persistence, UI, configuration, tests, and tools. Asking an AI agent to complete the entire request at once hides those boundaries and makes review difficult. A staged plan gives each change a limited purpose, a clear dependency, and an observable checkpoint.

2157. Prior knowledge

You should already be able to map ownership in an unfamiliar repository using the S-E-D-B approach from the previous lesson: identify systems, entry points, data ownership, and boundaries. You should also be able to distinguish evidence found in the repository from assumptions made from a request. This lesson does not require you to implement the change.

2158. Core concept

The core concept is sequencing for controlled change.

A multi-system request should be divided according to dependency and risk, not merely according to file names. Each stage should answer four questions:

1. What single outcome does this stage establish?
2. What existing behavior or interface must remain compatible?
3. What evidence will show that the stage is safe enough to continue?
4. What uncertainty or failure condition requires stopping and escalating?

A good sequence moves from an explicit contract toward behavior and integration. It avoids combining an unverified data change, a behavior change, and a presentation change in one opaque edit. Where possible, plan isolated work around one responsibility and stop at a reviewable checkpoint before crossing the next system boundary.

2159. Mental model

Use the Contract → Core → Integration → Cleanup sequence:

The sequence is not a mandatory four-commit recipe. It is a decision aid. A small request may combine stages; a high-risk request may split one stage into several smaller checkpoints. The plan must preserve the reasoning, even when the number of implementation steps changes.

2160. Concrete example

Consider the broad request: “Add a new salvage item that can be collected in the world, stored in the player inventory, displayed in the HUD, and used by a trade screen.”

An uncontrolled plan would ask an agent to edit the item definitions, collection logic, inventory model, HUD, trade screen, and tests in one pass.

A staged plan could be:

1. Contract: Trace the existing item identity, inventory representation, and trade input. Define the new item’s identifier, stack rules, default quantity, and behavior when an old save does not contain it. Evidence: the relevant callers and persistence boundary are listed.
2. Core: Add the item data and inventory behavior without changing the HUD or trade screen. Evidence: focused checks cover adding, removing, stacking, and insufficient quantity behavior.
3. Integration: Connect collection to inventory, then connect inventory reads to the HUD and trade screen. Keep collection, display, and trade verification as separately observable checks. Evidence: each boundary is exercised with the new item and an existing item.
4. Cleanup: Remove any temporary adapter or duplicated identifier only after searches show no remaining callers and compatibility checks pass. Evidence: no stale path remains, and the fallback behavior is still accounted for.

The important decision is not the exact file order. It is the separation of contracts, core behavior, and cross-system connections so that a failure can be localized.

2161. AI-native workflow

Use AI to expand and challenge the plan, not to replace repository evidence.

1. State the broad request and the known constraints to the AI assistant.
2. Ask it to propose system boundaries, dependencies, compatibility risks, and a staged sequence. Require it to label every claim as either repository evidence, an inference, or an open question.
3. Compare the proposal with the S-E-D-B map from the previous lesson. Check each named system, entry point, and data owner against the repository.
4. Ask the assistant to identify the smallest useful checkpoint for each stage and the evidence required before the next stage.
5. Reject or revise any stage that combines unrelated ownership boundaries, lacks a compatibility condition, or assumes an interface that has not been verified.
6. Record escalation triggers explicitly. Examples include an unknown persistence format, conflicting owners, unclear event ordering, missing tests for a critical boundary, or a proposed change that would break an existing caller.

The learner remains responsible for selecting the sequence. The AI may reveal omissions, but a plausible plan is not evidence that the repository supports it.

2162. Common mistake

The common mistake is treating “staged” as “edit one file at a time.” File count is not the control mechanism. A stage can still be uncontrolled if it crosses several ownership boundaries without a contract or checkpoint. Conversely, one coherent stage may touch multiple files when those files implement one verified responsibility. Stage boundaries should follow dependency, compatibility, and evidence—not arbitrary file count.

2163. Guided practice

Work with this request:

“Add a temporary shield ability. The player can activate it, the ability consumes a resource, enemies should not damage the player while it is active, the HUD should show the remaining duration, and the state should survive a scene transition.”

Create a staged plan without editing the project.

1. List the systems and boundaries that must be verified using S-E-D-B.
2. Write a one-sentence outcome for each proposed stage.
3. For every stage, name the compatibility question and the evidence required to continue.
4. Mark at least two escalation triggers. Include one trigger related to state or persistence and one related to conflicting ownership or event timing.
5. Ask an AI assistant to critique your plan. Require it to identify missing dependencies without inventing repository facts.
6. Revise the plan only when you can explain the evidence supporting the revision.

Your key decision is where to place the boundary between the shield’s core rule and its integration with damage, resource consumption, HUD presentation, and scene-transition state.

2164. Validation / evidence

Your work is sufficient when you can point to a written plan that contains:

• A bounded outcome for every stage.
• A dependency order justified by repository evidence or clearly labeled as an open question.
• A compatibility condition for each stage.
• A reviewable checkpoint or testable observation for each stage, preferably after isolated work before the next boundary is crossed.
• Explicit escalation triggers for unresolved ownership, persistence, event ordering, or interface risk.
• No stage described only as “ask the AI to implement the feature.”

As a self-check, remove one proposed stage from your plan. If you cannot explain which dependency, compatibility check, or evidence checkpoint disappears, the original stages may not be meaningfully separated.

2165. Key takeaways

• Sequence multi-system work by dependency, compatibility, and evidence rather than by file count.
• Separate contracts, core behavior, integration, and cleanup when those concerns carry different risks.
• A stage is reviewable only when its outcome and continuation evidence are explicit.
• Isolated work and reviewable checkpoints make failures easier to locate before the next system boundary is changed.
• AI can propose dependencies and challenge omissions, but repository evidence determines the plan.
• Escalate when ownership, persistence, event ordering, or compatibility remains uncertain.

2166. Next lesson

Continue to 5.7 — Refactoring.

2167. Knowledge check