Direct a tiny implementation

522. Lesson identity

Module

1.micro-loop — The Playable Micro-Loop

Lesson

Direct a tiny implementation

Academic type

Guided build

Schema type

Practical

Order

2

Estimated time

40–60 minutes

This lesson uses the same artifact from The four parts on one artifact. You will make one bounded change, inspect what changed, and decide whether to keep or revert it.

523. Learning objective

After this lesson, you can write a bounded implementation brief, direct an AI-assisted change to one component of a micro-loop, inspect the result, and keep or revert it using a recorded Git checkpoint.

524. Why this matters

A playable loop becomes manageable when you can change it without losing track of its contract. AI can produce a plausible edit quickly, but plausibility is not evidence that the edit is correct. A bounded brief and a Git checkpoint give you control over scope, behavior, comparison, and recovery.

Use the implementation map input → rule → presentation → feedback while preserving the Stage 1 loop ACT → RESPOND → CHANGE → AGAIN. The map identifies what you are changing; the loop describes how you repeatedly exercise and evaluate the artifact.

525. Prior knowledge

You should have completed The four parts on one artifact in this module. You should be able to identify the input, rule, presentation, and feedback of the existing interaction. You also need a working project repository with Git available and an AI coding partner that can inspect the relevant files.

526. Core concept

One change, one component

A bounded implementation changes one component of the interaction cycle at a time:

• Input: what the player does and what the game detects.
• Rule: the condition and state change that follow.
• Presentation: what the player can see or otherwise perceive as the state.
• Feedback: the immediate confirmation that the interaction was processed.

The implementation brief must name exactly one target component. Do not request a general polish pass, a broad refactor, or a change to the whole loop. A small change is easier to inspect, test, and restore.

Work through ACT → RESPOND → CHANGE → AGAIN: perform the existing interaction, observe its response, change one bounded component, and repeat the interaction to compare the result.

527. Mental model

The bounded-change ritual

The AI may propose or explain an edit, but you own the scope and the keep-or-revert decision.

528. Concrete example

Suppose the artifact detects a button press, changes a Boolean state, presents that state with a lamp, and provides immediate feedback. You choose the presentation component only.

A bounded brief could be:

Change only the presentation of the active state. When active, make the lamp blue and display the text label “Active.” When inactive, make the lamp gray and display the text label “Inactive.” Ensure the labels remain legible and do not rely on color alone to communicate the state. Do not change input detection, the state rule, feedback, file structure, or unrelated styling. Acceptance test: use the existing control and verify that both the lamp color and the text label change correctly in each state while the existing feedback still works.

Color is paired with a non-color cue rather than acting as the only state signal. This remains one bounded presentation change; it does not introduce a new gameplay system.

529. AI-native workflow

1. Write the brief: name the target component, current behavior, requested behavior, constraints, and acceptance test.
2. Request a bounded plan first: ask the AI to identify the likely file or function and restate what it will not change.
3. Authorize the smallest edit: allow only the change described in the brief.
4. Inspect before trusting: compare every changed file and diff hunk with the brief. Look for unrelated files, altered rules, renamed inputs, or changed feedback.
5. Run the artifact: test the original interaction path and the requested presentation change.
6. Keep or revert: make the decision from the diff and observed behavior, not from the AI's confidence.

If the AI cannot identify a narrow scope, stop and rewrite the brief. More generated code is not a substitute for a clearer boundary.

530. Git workflow

1. Record the starting state

Before requesting an edit, inspect the repository:

git status
git log -1 --oneline

If the working tree contains unrelated work, stop and separate or preserve that work according to your established repository practice. Do not mix it into this exercise.

Record the current commit before the edit. One way to store it for the current shell session is:

STARTING_COMMIT=$(git rev-parse HEAD)
printf '%s\n' "$STARTING_COMMIT"

Keep the printed identifier with your evidence. A shell variable may be lost when the terminal session ends, so retain the identifier separately.

2. Inspect the AI-assisted edit

Before staging anything, run:

git diff
git status

List every changed path and classify it as intended or unrelated. Do not continue if unrelated work would be overwritten or committed.

3. Keep a conforming change

If the diff and live test satisfy the brief, stage every inspected intended file explicitly:

git add <intended-file-1> <intended-file-2>
git diff --staged
git commit -m "Change one micro-loop component"

Replace the placeholders with actual paths. If there is only one intended file, provide only that path. If there are more files, include each inspected intended path or repeat git add for each one. Do not use a broad staging command that could include unrelated work.

4. Restore a failed change

If the result fails the brief, first record the useful observation. Then restore only the tracked files intentionally involved in this exercise from the recorded starting commit:

git restore --source="$STARTING_COMMIT" -- <intended-file-1> <intended-file-2>
git status
git diff

Replace the placeholders with the exact intended paths and verify that STARTING_COMMIT still contains the identifier you recorded. This command restores the named tracked paths; it does not remove untracked files.

Review untracked paths with:

git status --short

Remove an untracked file individually only after confirming that it was created by this exercise and is not needed:

rm -- <exercise-created-file>
git status
git diff

Do not copy these placeholders literally. Do not remove an untracked path merely because it appears in git status. Avoid broad reset, clean, or deletion commands, especially when the working tree contains unrelated work.

531. Common mistakes

• Accepting a successful-looking result without comparing it with the brief.
• Allowing a presentation request to alter the rule, input handler, or feedback.
• Communicating state through color alone.
• Committing before running the acceptance test.
• Staging only one intended file when the inspected implementation requires several.
• Assuming git restore removes exercise-created untracked files.
• Using a broad recovery command that risks unrelated work.

A scoped diff, an observable test, and a verified repository state are separate requirements.

532. Guided practice

Use the same artifact from the previous lesson.

Part 1: Establish the checkpoint

1. Open the project repository.
2. Run git status and inspect the latest commit.
3. If unrelated changes are present, stop and protect them from this exercise.
4. Record the starting commit or create a focused checkpoint according to your established workflow.

Part 2: Choose one component

Select exactly one target: input, rule, presentation, or feedback. Complete these lines before prompting the AI:

• Target component:
• Current behavior:
• Requested behavior:
• Constraints:
• Acceptance test:

Include the constraint: “Do not change the other three components.” If the change presents a state visually, ensure the acceptance test does not depend on color alone.

Part 3: Direct and inspect

Ask the AI to restate the brief and identify the intended paths before editing. Request the smallest implementation that satisfies the brief. Inspect the resulting diff and classify every changed file as intended or unrelated.

Part 4: Test and decide

Run the artifact and follow ACT → RESPOND → CHANGE → AGAIN. Test the unchanged interaction path as well as the requested change.

• Keep: the intended component changed, the other components still work, no unrelated paths were included, and the acceptance test passes.
• Revert: the scope expanded, the behavior is incorrect, an accessibility cue is missing, or the acceptance test fails.

If you keep the change, stage all and only the inspected intended paths and create one focused commit. If you revert it, restore the intended tracked paths from the recorded commit, review any untracked paths individually, and verify the result with git status and git diff.

533. Validation and evidence

You have completed the lesson when you can provide:

• A brief naming one target component and an observable acceptance test.
• A pre-change checkpoint or recorded starting commit.
• A list of intended paths.
• An inspected diff containing only the bounded change, or evidence of a verified restoration.
• A live test showing the requested behavior and continued operation of the other three components.
• For a visual state change, evidence that state is distinguishable without color alone.
• A keep-or-revert decision supported by the evidence.

The pass condition is not “the AI generated code.” It is that you can control the scope, inspect the result, test the behavior, and recover from a failed edit. Complete the attached practical assessment to organize this evidence for the next lesson.

534. Key takeaways

• Change one component at a time: input, rule, presentation, or feedback.
• Use ACT → RESPOND → CHANGE → AGAIN to exercise and evaluate the artifact.
• Pair color with a non-color cue when presenting state.
• Inspect every changed path before staging or restoring it.
• Stage all and only the inspected intended files.
• Restore failed tracked changes from the recorded checkpoint using explicit paths.
• Review exercise-created untracked files individually.
• The keep-or-revert decision belongs to you.

535. Optional knowledge check

536. Next lesson

Continue with 1.micro-loop L3 — Milestone studio, the canonical Lesson 3. Organize the brief, checkpoint, inspected diff, live test, accessibility evidence where relevant, and keep-or-revert decision so the artifact can be evaluated as evidence of the Stage 1 capability.

537. Knowledge check