Refuse the neighbor rewrite

1089. Lesson identity

Module

3.5 — Coupling

Lesson

Refuse the neighbor rewrite

Academic type

Workflow

Schema type

Mixed

Order

Lesson 2 in the module

Estimated time

45–60 minutes, including practice

This lesson trains a review decision: accept, narrow, or reject an AI-generated diff when the requested change has a defined boundary.

1090. Learning objective

After this lesson, you can accept, narrow, or reject an AI-generated diff by comparing its changed surface, dependencies, and evidence with the requested boundary.

1091. Why this matters

AI often treats a local change as permission to reorganize neighboring systems. That expansion can increase coupling even when the original request is small. An unnecessary rewrite may alter ownership, timing, or data flow that another system already relies on. Review the change as a boundary decision, not merely as a code-quality decision.

1092. Prior knowledge

You should be able to identify coupling risks, distinguish one system’s responsibility from a neighboring system’s responsibility, and explain the cost of a change. This lesson depends directly on 3.5 — Coupling: Coupling has a change cost.

You also need basic experience reading an AI-generated diff and comparing a requested behavior with observable evidence.

1093. Core concept

Scope control means preserving the requested boundary unless evidence requires expansion.

A useful change is not automatically a justified change. Review every modified file, function, data path, public interface, and ownership decision against the request. If a modification belongs to a neighboring system but is not necessary to satisfy the request, ask the AI to remove it or reject the diff.

Use three decisions:

1. Accept — the diff stays within the requested boundary and has sufficient evidence.
2. Narrow — part of the diff is useful, but unrelated or boundary-moving changes must be removed.
3. Reject — the problematic changes cannot be safely isolated or justified, so the diff should not be accepted as a whole.

Touching a neighboring system is not automatically wrong. A justified adjacent change may use an existing contract without moving responsibility. For example, a UI system may display a result produced by a gameplay system while the gameplay system remains the authority for that result.

1094. Boundary-review model

Use this sequence:

Requested boundary → Changed-surface inventory → Classification and justification → Evidence → Accept, narrow, or reject

Do not use “the code is cleaner” as evidence that expansion is necessary. Cleanup may be a valid later task, but it does not automatically belong in the current diff.

1095. Concrete example

Suppose the request is:

Add a cooldown to the interaction command. Keep cooldown ownership in the interaction system. Do not change progression rules.

An AI-generated diff does four things:

• Adds a cooldown field to the interaction system.
• Blocks the interaction command while the cooldown is active.
• Renames progression fields for consistency.
• Moves the progression threshold check into the interaction system.

The first two changes are inside the request. The rename is unrelated expansion. Moving the threshold check changes responsibility and creates knowledge coupling: the interaction system now knows a progression rule that belongs elsewhere.

Do not accept the whole diff merely because the cooldown works. Narrow it to the cooldown behavior, remove the rename and threshold move, and then verify that the progression system still owns and evaluates its threshold.

1096. AI-native workflow

Use the AI as a scoped implementation partner, not as the authority that defines scope.

1. State the boundary. Provide the requested behavior, the owning system, permitted contracts, and explicit non-goals.
2. Record the focused branch or checkpoint. Identify the branch or checkpoint containing the scoped attempt so unrelated work is not included in the review.
3. Request a plan before editing. Ask the AI to list the files, responsibilities, contracts, and checks it expects to touch.
4. Inventory the entire changed surface. Record every changed item before deciding whether it belongs.
5. Classify each item. Mark it as required, justified adjacent, evidence-producing, unrelated, or boundary-moving.
6. Constrain the follow-up. Tell the AI exactly what to retain, remove, and preserve.
7. Run focused checks. Verify the requested behavior and at least one neighboring behavior that must remain unchanged.
8. Record the decision. State accept, narrow, or reject and cite the inventory, rationale, checks, and focused checkpoint.

Useful instructions include:

• “Restate the requested boundary, owning system, permitted contract, and non-goals before editing.”
• “For every proposed change, identify the requirement or evidence need it satisfies.”
• “Review this diff for responsibility movement, new knowledge coupling, and unrelated expansion.”
• “Retain only the listed changes and preserve the named neighboring behavior.”

An AI explanation is a claim to inspect, not evidence by itself.

1097. Common mistakes

A common mistake is accepting a broad diff because it appears more complete or architecturally elegant. A larger diff can hide a transfer of responsibility while still making the requested behavior pass. “The AI already touched that file” is not a reason to expand the task.

The opposite mistake is rejecting every neighboring change. A boundary-preserving implementation may legitimately touch an adjacent system through an existing contract. Review whether responsibility and authority remain stable, whether the adjacent touch is necessary, and whether focused evidence supports it.

1098. Guided practice

Review this hypothetical diff. The request is:

Add a maximum carry weight of 12 kilograms to the inventory system. The inventory system owns the limit. Keep the economy reward calculation unchanged.

In the compact diff below, each + marks an added line. In prose, the diff adds a weight limit and rejection rule to the inventory, changes reward representation and naming, moves the carry check into the economy, and adds a new reward-completion event.

inventory.ts
+ add maxCarryWeightKg = 12
+ reject additions when currentWeightKg + itemWeightKg > maxCarryWeightKg

reward.ts
+ convert reward values from integers to floating-point numbers
+ rename rewardAmount to payout

economy.ts
+ move the carry-weight check into the reward calculation
+ add a new event so inventory listens to reward completion

Complete the review before reading the reference decision:

1. State the requested boundary in one sentence.
2. Inventory every changed line or logical group.
3. Classify each item as required, evidence-producing, unrelated, justified adjacent, or boundary-moving.
4. Choose accept, narrow, or reject for the complete diff.
5. Write a constrained follow-up instruction.
6. Specify one check for the carry-weight rule and one check proving that reward calculation remains unchanged.

Reference decision

A strong decision is narrow. Retain maxCarryWeightKg and the inventory-owned rejection rule. Remove the reward representation change, the rename, the moved carry check, and the new event unless a separate requirement justifies them. Check a boundary case at exactly 12 kilograms, an over-limit attempt, and an unchanged representative reward calculation.

1099. Scored practical assessment

Complete Practical diff review: preserve the owning boundary. It uses a fresh diff containing:

• a required change in the owning system,
• a justified adjacent-system change through an existing result contract,
• a focused test that produces evidence, and
• a harmful move of decision authority into a neighboring controller.

Submit a complete changed-surface inventory, classification and rationale for every item, an accept/narrow/reject decision, a constrained AI instruction, and checks for both requested and preserved behavior. The assessment is scored with the module’s diff-review rubric. Do not compare your work with the post-submission reference until you have frozen your own decision.

1100. Validation and evidence

A defensible review record contains:

• The requested boundary in one sentence.
• The focused branch or checkpoint for the attempt.
• A complete inventory of the changed surface.
• A classification and reason for every item.
• A final accept, narrow, or reject decision.
• A constrained follow-up instruction or rejection rationale.
• A focused check for the requested behavior.
• A focused check for preserved neighboring behavior.

You have met the objective when another developer can reproduce the decision from the review record without relying on the AI’s explanation.

1101. Key takeaways

• Review an AI diff against the request, not against its apparent completeness.
• Inventory every changed item before deciding.
• Extra changed surface requires justification, but an adjacent touch through an existing contract can be valid.
• Accept only when the scope and evidence are sufficient.
• Narrow useful work when it is mixed with unrelated or boundary-moving changes.
• Reject when harmful changes cannot be safely isolated or justified.

1102. Next lesson

Continue to 3.6 — 3D rendering. The same responsibility and boundary analysis will next be applied to simulation state, render data, and rendered objects along a 3D render path.

1103. Knowledge check