Inspect, validate, and recover

2127. Lesson identity

Module

5.5 — Change safety

Lesson

Inspect, validate, and recover

Academic type

Debugging Lab

Schema type

Practical

Order

2

Estimated time

35–45 minutes, including practice

This lab uses the change boundary from 5.5 L1 — Establish a safe change boundary. You will inspect a proposed change, compare its diff with the authorized scope, run the planned checks, and choose a recovery action based on evidence.

2128. Learning objective

After this lesson, you can use a baseline, diff, and validation results to accept a bounded change, request a bounded correction, or revert the change and document the decision.

2129. Why this matters

Code that runs is not automatically a safe change. An AI-generated edit may compile while altering an excluded file, changing adjacent behavior, or failing an acceptance check. Review becomes reliable when the decision is tied to the authorized boundary and observable evidence. The goal is not to preserve every generated line; it is to preserve the intended game behavior while controlling change.

2130. Prior knowledge

You should have completed 5.5 L1 — Establish a safe change boundary. Bring its baseline evidence, named Git checkpoint or commit, in-scope request, non-goals, validation checks, and rollback condition. You should also be able to inspect a Git diff and run the project’s established validation commands or manual checks.

2131. Core concept

A change decision has three possible outcomes:

• Accept: The diff stays within scope, the intended behavior passes validation, and no relevant regression is found.
• Correct: The change is close to acceptable, but a specific, bounded defect can be corrected without expanding scope. The correction must be reviewed and validated again.
• Revert: Restore the named baseline when unintended effects remain unexplained, cannot be isolated confidently, or a clean restoration is safer than a bounded correction. A failed check or scope violation makes the current diff unacceptable, but it does not automatically forbid a bounded correction if every unintended edit is identified.

The decision must follow evidence, not confidence in the AI or attachment to the generated code. A small diff can still be wrong, and a larger diff is not automatically wrong; scope and behavior determine the decision.

2132. Mental model

Use the TRACE review sequence:

Do not skip directly from Review to Accept. A diff explains the implementation change; validation explains whether the game still meets the contract.

2133. Concrete example

Use the previous lesson’s bounded task: clarify the message shown when the player lacks enough currency to use an item. The currency calculation, item cost, purchase result, and other messages are excluded.

Imagine the review produces this evidence:

• The diff changes the intended message and also changes the item-cost comparison from currency >= cost to currency > cost.
• The new message appears during the insufficient-currency case.
• A check confirms that the message is clearer.
• A second check shows that an item can no longer be used when the player has exactly enough currency to pay its cost. With currency > cost, equality is rejected even though currency >= cost would allow the purchase; this is a behavioral regression in an excluded area.

The current diff is not acceptable as-is because it crosses an explicit non-goal and fails a behavioral check. That finding does not, by itself, determine the recovery mechanism. Choose a bounded correction if inspection establishes that every unintended edit is identified, its effects are understood, and removing it stays within the original boundary. In this case, that could mean restoring currency >= cost while retaining only the authorized message edit, then inspecting the resulting diff and rerunning every relevant check.

Choose revert instead when the unintended effects are not fully understood, cannot be isolated confidently, or restoring the clean baseline is safer than editing the mixed change. After reverting, verify both the repository state and the equality case against the named baseline. Either decision is defensible only when the raw diff, surrounding code, validation results, and recovery evidence support it; the scope violation rules out acceptance, not automatically correction.

2134. AI-native workflow

Use AI as an inspection assistant, not as the authority that decides whether its own work is safe:

1. Provide the AI with the authorized scope, non-goals, baseline reference, diff, and validation results.
2. Ask it to summarize each changed file or value, identify possible scope violations, and map each change to the request.
3. Compare that summary with the actual diff. Treat the diff as the source of truth if the summary omits or misstates a change.
4. Ask for hypotheses about failed checks, but label them as hypotheses until verified by inspection or testing.
5. If a correction is appropriate, state exactly what may be corrected and what must remain untouched. Do not authorize a broad cleanup.
6. After any correction, inspect the new diff against the original baseline and rerun the complete relevant validation set.
7. Record your own decision—accept, correct, or revert—and the evidence supporting it.

An AI explanation can help locate a defect, but it cannot replace the diff, runtime result, or recovery verification.

2135. Common mistake

The common mistake is evaluating the change from the prompt or the AI’s summary instead of from the actual diff and observed behavior. Another mistake is making a partial manual undo after a failed check, leaving the project in an uncertain state. When unintended effects remain unexplained, cannot be isolated confidently, or restoring the named Git recovery point is safer than a bounded correction, restore that checkpoint through the established project workflow and verify the baseline again.

2136. Guided practice

Run this drill in a small prepared repository or on a disposable branch of your learner project. Use a real bounded text or UI-message request whose expected runtime behavior you can observe. Do not work directly on a branch you cannot safely restore.

1. Record the baseline. Before applying the proposed change, save the commit or checkpoint reference, capture git status --short, and run one relevant behavioral check. Record its result and the expected behavior.
2. Create a mixed change. Apply or request the bounded message change. On the disposable branch, ensure the resulting change also contains one clearly unrelated edit and one adjacent logic edit that can affect observable behavior. Record who introduced each edit; do not rely on a summary in place of repository evidence.
3. Inspect the repository. Capture the changed-file list with git diff --name-only, inspect the raw git diff, and read enough surrounding code to understand each hunk. Classify every hunk as in scope, questionable, or out of scope and map it to the request or a non-goal.
4. Validate behavior. Run the original behavioral check and at least one check aimed at the adjacent logic edit. Preserve commands or manual steps, expected results, actual results, and any relevant runtime output.
5. Choose from evidence. Accept only if the complete diff is in scope and all checks pass. Choose bounded correction only if every unintended edit and effect is identified and can be removed within the original boundary. Choose revert if effects remain unexplained, isolation is uncertain, or clean restoration is safer.
6. Execute the decision. If correcting, remove only the identified unintended edits. If reverting, use the named checkpoint and the repository’s established recovery workflow. Do not stop at describing what you would do.
7. Verify the final state. Capture git status --short and the final diff or commit reference. Rerun the affected runtime checks and compare them with the recorded baseline. If correcting, confirm that only the authorized change remains; if reverting, confirm that both repository state and behavior match the baseline.
8. Submit a decision record. Include the baseline reference, raw-diff findings, changed-file list, scope classification for every hunk, validation evidence, selected action, recovery command or correction performed, final repository evidence, post-recovery runtime evidence, and a concise justification.

A scope violation makes the mixed diff unacceptable as-is, but it does not automatically require a revert. Your record must explain why correction or reversion was safer under the evidence you observed. AI confidence is not evidence.

2137. Validation / evidence

Your work is complete when it contains:

• A comparison between the authorized scope and the actual diff.
• A finding for every changed file or behavior, including unexplained changes.
• Validation results linked to specific acceptance checks.
• A justified accept, correct, or revert decision.
• A bounded next action for correction, or a named recovery action for reversion.
• Evidence that the baseline behavior was restored if you reverted.
• A concise decision record another developer could audit without repeating your assumptions.

For a correction, the evidence is not complete until the corrected diff and all relevant checks have been reviewed again. For a revert, confirm both the repository state and the affected runtime behavior against the original baseline.

Practical decision-record rubric

Score the submitted record out of 10 points:

• Scope-to-diff mapping — 2 points: Every hunk is classified and traced to the authorized request or a non-goal.
• Validation evidence — 2 points: Behavioral checks include reproducible steps, expected results, actual results, and relevant output.
• Recovery execution — 2 points: The learner performs the selected bounded correction or revert rather than merely describing it.
• Post-recovery verification — 2 points: Final repository state and affected runtime behavior are checked against the baseline and preserved as evidence.
• Decision justification — 2 points: The record explains why accept, correct, or revert is safest under the observed evidence, including any remaining uncertainty.

A submission must earn at least 1 point in every category. A well-written justification cannot compensate for missing execution or verification evidence.

2138. Key takeaways

• Review the actual diff before judging an AI-generated change.
• Acceptance requires both scope compliance and passing behavioral checks.
• Correction is appropriate only when every unintended edit is identified, its effects are understood, and removal remains within the original boundary.
• A failed check or scope violation makes the current diff unacceptable, but it does not automatically rule out a bounded correction. Revert when unintended effects remain unexplained, cannot be isolated confidently, or restoring the clean baseline is safer.
• The final decision belongs to the developer and must be supported by preserved evidence.

2139. Next lesson

Next: 5.6 — Large codebase strategy. Carry forward your baseline reference, diff findings, validation evidence, and decision record. You will use them to identify ownership boundaries, affected dependencies, safe change locations, and likely risks in an unfamiliar repository.

2140. Knowledge check