History is part of the production record

1338. Lesson identity

Module

3.14 — Professional Git

Lesson

History is part of the production record

Academic type

Workflow

Schema type

mixed

Order

1

Estimated time

30–45 minutes

This lesson treats Git history as production evidence: a record that helps another developer review a change, isolate a regression, or recover a known-good state.

1339. Learning objective

After this lesson, you can select a branch and commit structure that makes a multi-part game change reviewable, recoverable, and diagnosable.

1340. Why this matters

A multi-part change can contain gameplay rules, presentation, configuration data, and tests. If all of that is recorded as one opaque commit, a reviewer must reconstruct the reasoning from the final files, and recovery becomes unnecessarily broad. Focused commits and purposeful branches preserve why the change was structured as it was.

This matters especially when AI helps produce several edits quickly. Speed is useful only when the resulting history still explains what changed, what each part depends on, how it was checked, and what can be recovered independently.

1341. Prior knowledge

You should already be able to:

• create, inspect, and switch Git branches;
• make commits with meaningful messages;
• compare changes with git diff and inspect history with git log;
• use a compatibility matrix to record supported combinations and diagnostic questions, as practiced in 3.13 L2 — Design a compatibility matrix.

You do not need to memorize one universal branching strategy. The goal is to select a structure that fits the change and its risks.

1342. Core concept

Git structure should reflect the structure of the change.

A branch gives a change a review boundary. A focused commit gives one coherent unit of reasoning a recoverable boundary. Select both according to the parts of the change, their dependencies, and the order in which a reviewer or future investigator needs to inspect them.

A focused commit is not merely a small commit. It has one primary purpose and a clear validation claim. A rule change and the regression check that directly validates that rule can form one focused commit. By contrast, a commit that changes the rule, redesigns unrelated menus, reformats the project, and updates deployment files combines unrelated purposes even if its message is concise.

1343. Mental model

The production-record test

For each proposed change, ask:

A useful planning sequence is:

Change map → branch boundary → dependency order → focused commits → validation record

This is a decision model, not a command ritual.

1344. Concrete example

Suppose a change adds a new interaction to a game prototype. It has four parts:

1. a gameplay rule that determines when the interaction is valid;
2. a visual response that communicates the result;
3. configuration data that supplies the interaction text;
4. a regression check for the rule.

A weak history might contain one commit named add interaction. That history does not reveal whether the rule, presentation, data, or check caused a later failure.

A stronger plan might be:

• Preparatory commit: define the shared configuration format and add the data required by the interaction. Use this boundary when the format is independently reviewable and will support other interactions.
• Rule commit: implement the gameplay rule together with the regression check that directly validates that rule. They share one validation claim and should not be separated if the check would be meaningless without the rule.
• Presentation commit: add the player-facing response after the rule provides a stable result to present.

If the presentation is required for the interaction to reach a valid or testable state, keep it with the rule instead. If data and a check genuinely support the same independently reviewable validation claim, they may move together, but the plan must state that shared claim. Do not combine them merely because both remain unfinished.

The correct structure depends on coupling, valid intermediate states, and validation—not on reaching a fixed commit count.

1345. Choosing a branch structure

Before editing, write a short change map and choose among these structures:

• One focused branch with multiple commits: use when the parts form one reviewable functionality but have useful internal boundaries.
• Separate branches: use when parts have different owners, release timing, risk, or review criteria.
• A preparatory branch or commit followed by a feature branch: use when a shared foundation should be reviewed before dependent behavior.

Separate or stacked branches are appropriate only when their dependency, review base, and integration order are explicit. Otherwise, one branch with focused commits may preserve a clearer review boundary and avoid unnecessary integration ambiguity.

For every proposed commit, record:

• its primary purpose;
• the files or subsystem affected;
• prerequisite commits, if any;
• the validation performed or planned;
• the failure it would help isolate;
• any known limitation or follow-up.

1346. AI-native workflow

AI can propose a change map, draft commit boundaries, or summarize a diff. It should not decide the history without your review.

1. Describe the parts, risks, and dependencies before requesting a Git plan.
2. Ask AI to propose a branch boundary and commit sequence.
3. Compare the proposal with actual file coupling and available validation.
4. Reject boundaries that would leave an intermediate commit invalid, conceal unrelated edits, or combine changes with different recovery needs.
5. Revise the plan yourself and record why each boundary exists.
6. If commits already exist, verify any AI summary against git diff, git log, and the checks actually run.

A useful prompt is:

Here is a multi-part game change: [list the parts]. Dependencies are [list dependencies]. Validation available for each part is [list checks]. Propose a branch scope and focused commit sequence. For every commit, state its purpose, prerequisites, validation, and what failure it would help isolate. Do not assume unrelated formatting or refactoring belongs in this change.

The learner remains responsible for the final structure. An elegant AI-generated plan is still wrong if it does not match the repository's actual dependency graph.

1347. Inspecting the resulting record

Commands such as these can gather evidence:

git status
git diff --check
git log --oneline --decorate --graph --all
git show --stat <commit>
git diff <base>...<branch>

A clean status does not prove that the history is coherent. A successful command also does not prove that each change was validated at the correct boundary.

1348. Common mistakes

Mistaking a short message for a focused commit

update gameplay may describe one coherent rule change, or it may conceal changes to gameplay, UI, assets, data, and formatting. Focus comes from contents, dependencies, and the validation claim—not message length.

Splitting by file instead of reasoning

Two files may need to change together to produce a valid state. Conversely, several edits in one file may serve different purposes and recovery needs. File count alone does not determine a commit boundary.

Creating branches without an integration plan

Dependent branches can obscure which base a reviewer should use and which branch must integrate first. If those decisions are not explicit, one branch with focused commits may be easier to review and recover.

1349. Guided practice

Use this scenario, or substitute a comparable change from your own prototype:

A functionality adds a new interaction. The rule logic, player-facing response, configuration data, and regression check are mixed in one working change. The response cannot be tested meaningfully until the rule exists. The configuration format is also needed by an unrelated interaction planned for a later milestone.

Produce a Git structure decision:

1. Create a four-row change map. For each part, state its purpose, dependency, validation, and recovery need.
2. Choose one branch structure and explain its review boundary.
3. If you choose separate or stacked branches, state the dependency, review base, and integration order.
4. Propose an ordered commit sequence. Give every commit one primary purpose and a validation claim.
5. Identify one boundary that should not be split because its parts must move together.
6. Identify one boundary that should not be combined because its parts have different review or recovery needs.
7. Explain which commit or boundary you would inspect first if the presentation failed while the rule still passed.
8. Ask an AI assistant to critique the plan. Record one recommendation you accepted and one you rejected, with reasons.

Do not change project files yet. Submit the planning artifact through the practical assessment attached to this lesson.

1350. Validation and evidence

A defensible artifact includes:

• a named branch boundary and its rationale;
• a complete change map;
• an ordered commit plan with dependencies and valid intermediate states;
• a validation claim for every commit;
• one justified coupled boundary and one justified separated boundary;
• an explicit integration order if multiple dependent branches are used;
• a recovery rationale that identifies a first diagnostic or rollback target;
• an AI critique checked against the learner's own analysis.

A strong answer does not depend on a particular number of commits. It makes the review path, validation claims, and recovery choices explicit.

1351. Key takeaways

• A branch defines a review boundary; a commit defines a coherent reasoning and recovery boundary.
• Split work when purpose, validation, or recovery differs; keep directly coupled work together.
• The rule and its direct regression check often share one validation claim.
• Dependent branches require an explicit review base and integration order.
• AI can propose Git structure, but the developer must verify it against actual dependencies and checks.

1352. Next lesson

Continue to 3.14 L2 — Review an AI-assisted change set to identify boundary violations, integration risk, and recovery options in an AI-assisted change set.

1353. Knowledge check