mobile-checkpoint

Mobile Checkpoint Skill

Git-based checkpoint workflow for Android/KMP development: save a known-good state before a risky operation, restore cleanly if it goes wrong. Checkpoints are ordinary git commits plus a checkpoint/* tag — no extra tooling.

When to Use

Before risky operations:

• Large refactors (MVI migration, architecture changes)
• Gradle/AGP/Kotlin upgrades, dependency bumps in gradle/libs.versions.toml, ./gradlew wrapper --gradle-version <x>
• Manifest changes (permissions, components)
• Navigation restructuring
• Experimental features

After milestones:

• Feature completion, all tests passing, successful release build

Checkpoint Workflow

1. Save (before the operation)

# Verify the state is worth saving
git status
./gradlew check

# Commit everything, including untracked files
git add -A
git commit -m "checkpoint: before-<operation>"
git tag checkpoint/before-<operation>

For a quick save of uncommitted work without touching branch history:

git stash push -u -m "before-<operation>"   # -u includes untracked files
git stash apply                              # keep working with the same tree

2. Perform the operation

Make the changes, then verify: ./gradlew build (or check for the fast lane).

3. After

Success — checkpoint the new state:

git add -A && git commit -m "checkpoint: after-<operation>"

Failure — restore:

# Optionally keep the failed attempt for later inspection.
# `git branch` alone captures only commits, so commit the WIP first:
git switch -c failed-<operation>
git add -A && git commit -m "failed: <operation>"
git switch -

# Back to the checkpoint (destructive to uncommitted changes)
git reset --hard checkpoint/before-<operation>

# reset --hard rewinds tracked files and deletes files added to the
# index since the checkpoint, but leaves UNTRACKED files in place.
# Preview leftovers, then remove them:
git clean -nd
git clean -fd

Avoid git clean -x in Android projects — it also deletes local.properties and build caches.