git-drill

git-drill

Run a git dojo: the user wants to practice a situation, not fix real work. Build a realistic mess in a disposable sandbox, coach them through it, and let them retry until it's muscle memory. This is the one skill that creates git states on purpose, so isolation is the absolute rule.

SAFETY — read first

• Never build a drill in the user's real repo or working directory. The sandbox is created for you by scenarios/build.mjs under the OS temp directory — use it and nothing else.
• Every git command you run for a drill must run inside the sandbox (use git -C "<sandbox>" …). Never run drill commands against the current directory.
• Cleanup is node scenarios/build.mjs clean "<sandbox>" — it refuses any path that isn't a git-drill- sandbox, so it can't touch a real repo.
• If you can't create an isolated sandbox, stop and say so — do not improvise in a real repo.

The scenario engine is cross-platform (Node + git): it works on Windows, macOS, and Linux. Drive everything through scenarios/build.mjs, not shell-specific commands like mktemp or rm.

All scenarios/build.mjs paths below are relative to this skill's directory, not the user's working directory (which is their own repo). Invoke the engine with its full path from the skill directory, e.g. node "<skill-dir>/scenarios/build.mjs" build <name>.

Transparency contract (every action)

$ <literal command>
✓ <one line: what it did, plain language>
↩ undo: <reversing command, or "— (not reversible)">

The learner sees and types the real commands — that's the whole point.

The drill loop

Reminder: the node scenarios/build.mjs … commands below are shorthand. The engine lives in this skill's directory, not the user's repo (their cwd), so invoke it with the full path — node "<skill-dir>/scenarios/build.mjs" … — or cd into the skill directory first. The git -C "<sandbox>" commands work from anywhere.

1. Pick a scenario. From the catalog in reference/scenarios.md (first-commit, unstage-file, discard-local-edit, amend-last-commit, revert-commit, stash-before-switch, merge-conflict, detached-head, wrong-branch, bad-reset, pr-update, pr-conflict), or the one the user named. node scenarios/build.mjs list prints the authoritative set. If they're vague and clearly new to git, start with first-commit; otherwise offer the list.
2. Build the sandbox. Run the engine — it creates an isolated temp dir and prints its path on the last line. Capture that path as the sandbox.

   node scenarios/build.mjs build <name>
   

   Show the command and that it created a throwaway practice repo. Exit: you hold the sandbox path and the repo is in the scenario's starting (messy) state.
3. Present the situation + goal from the catalog. State plainly where they are and what "done" looks like. Tell them they can type a git command, or hint, solution, reset, new, or quit.
4. Coach the attempt. For each command they try: show it with the transparency block, run it inside the sandbox (git -C "<sandbox>" …), and react. Let them drive — don't solve it for them. The sandbox only isolates the engine's writes, not arbitrary typed commands: if a learner's command targets a path outside the sandbox or is destructive to the host (e.g. rm -rf, a git -C <other-path>), decline and explain rather than run it — run learner commands only against the sandbox.
   • hint → give the next escalating hint only (not all of them).
   • solution → show the full solution commands, explain why each step works (ground concepts in reference/sources.md / git help if they ask "why"). For recovery drills (bad-reset, detached-head, wrong-branch), pull the exact recipe from reference/recovery.md.
   • reset → clean the sandbox and rebuild the same scenario to try again.
   • new → pick another scenario.
5. Verify. Run the engine's check — exit 0 / PASS means solved, non-zero / FAIL: <reason> says what's still off:

   node scenarios/build.mjs verify <name> "<sandbox>"
   

   On success, give a short recap: what they practiced, and the escape hatch they didn't need (merge --abort, etc.). On a wrong turn, point at the FAIL reason and let them try again — mistakes in the sandbox are free. A FAIL: could not check the sandbox … reason means the repo is in an unexpected state (e.g. a tracked file was deleted), not that their git answer was wrong — offer reset, don't tell them they failed. Exit: verify returns PASS, or the user chooses reset / new / quit.
6. Finish. Offer reset / new, or quit. To step up the difficulty, use new to pick a harder scenario (the ●●● ones: bad-reset, pr-conflict). Clean up on any exit from the loop — quit, abandonment, or an error mid-drill — so sandboxes never pile up:

   node scenarios/build.mjs clean "<sandbox>"
   

   (It refuses any path that isn't a git-drill- sandbox.) Confirm it's removed.

Creating new scenarios

Use this mode only when the user asks to add, create, design, or author a reusable git-drill scenario. If they only ask to "set up a scenario to practice," use the drill loop above.

1. Pick a lowercase slug, e.g. first-commit or undo-staged-file.
2. Scaffold a declarative spec:

   node scenarios/build.mjs create <slug>
   

3. Edit scenarios/specs/<slug>.json. Keep it declarative: use only init, write, and sandboxed git build steps. Do not add shell scripts.
4. Add or update the matching catalog entry in reference/scenarios.md: situation, goal, hints, solution, escape hatch, and verify line.
5. Validate the spec:

   node scenarios/build.mjs validate-spec <slug>
   

6. Smoke-test it: build the scenario, run the documented solution commands inside the sandbox with git -C "<sandbox>" ..., verify it passes, then clean up.

If the requested scenario cannot be expressed in the JSON spec format, update scenarios/build.mjs directly using the existing hard-coded scenario pattern, then keep the catalog and tests in sync.

When to use

• The user wants to practice / drill / rehearse a git situation: "give me a first commit drill", "give me a merge conflict to practice on", "let me practice detached HEAD", "quiz me on a bad reset".
• They want a safe place to fail and retry, separate from real work.
• They want to create a new reusable git-drill scenario for the catalog.

When NOT to use

• Real problem right now? "I'm actually stuck", a live conflict in their real repo → git-next (diagnose and recommend). Don't manufacture a drill.
• Wants to do a real operation? "Actually merge this branch" → git-guide-me.
• Just wants the concept? "What is a rebase?" → git-explain.

Worked example (merge-conflict drill)

User: give me a merge conflict to practice on

> node scenarios/build.mjs build merge-conflict
$ (creates an isolated sandbox)   →  /tmp/git-drill-a1b2c3
✓ throwaway practice repo created
↩ undo: node scenarios/build.mjs clean /tmp/git-drill-a1b2c3

DRILL: Merge conflict   ●●○
You're on main; `git merge spicy` conflicted in recipe.txt. Resolve it
keeping both ideas, then complete the merge. (type a command, or
hint / solution / reset / new / quit)

User: git status
$ git -C /tmp/git-drill-a1b2c3 status
✓ shows "both modified: recipe.txt"  → edit the file, remove the <<< === >>> markers

User: (edits file) then: git add recipe.txt && git commit --no-edit
✓ merge committed

> node scenarios/build.mjs verify merge-conflict /tmp/git-drill-a1b2c3
PASS  → ✅ Drill passed. You read status, removed the markers, added, committed.
        Escape hatch you didn't need: git merge --abort.
quit → node scenarios/build.mjs clean /tmp/git-drill-a1b2c3

References

Bundled in this skill so it installs self-contained:

• reference/scenarios.md — the scenario catalog: situation, goal, hints, solution, and verify check per drill, plus how to add new ones.
• scenarios/build.mjs — the cross-platform engine (Node + git) that builds, verifies, and cleans each drill. Works on Windows, macOS, and Linux.
• reference/recovery.md — undo/recovery recipes (the bad-reset, detached-head, and wrong-branch drills lean on these).
• reference/sources.md — authoritative sources for "why did that work?" follow-ups.