checkpoint-resume

Files (1)

• SKILL.md

SKILL.md (first lines)

# Checkpoint Resume

Resume work from a CHECKPOINT.md file. Rebuild full context and continue exactly
where we left off.

## Process

### Step 1 — Resolve the Archive Directory

Run:

```bash
COMMON_DIR=$(git rev-parse --path-format=absolute --git-common-dir)
```

If this command exits non-zero, abort: **"Not a git repository.
checkpoint-resume requires a git repo at CWD."**

Then:

```bash
ARCHIVE=$(dirname "$COMMON_DIR")/.checkpoints
```

This resolves to the shared `.checkpoints/` directory at the main checkout root,
consistent across all worktrees.

### Step 2 — Slug Derivation

Derive `<current-slug>` from the current branch name:

1. Get branch: `git branch --show-current`
2. Lowercase the result.
3. Replace `/` with `-`.
4. Strip characters outside `[a-z0-9-]`.
5. Collapse consecutive `-`.
6. Detached HEAD fallback: use the basename of CWD, slugified the same way.

### Step 3 — Enumerate Available Checkpoints

Collect candidates:

- **Active checkpoint:** Check whether `CHECKPOINT.md` exists at CWD. If it
  does, parse its `**Branch:**` line.
- **Archive:** List `$ARCHIVE/*.md`, excluding any file matching `*.prev.md`
  (rolling same-branch backups, not paused efforts) and any file matching
  `*.mirror.md` (linked-worktree mirrors — these are auto-found by Case C′
  below, not listed as independent entries for Case D).

### Step 4 — Decide Which Checkpoint to Resume

Apply the first matching case:

**Case A — CHECKPOINT.md present, branch matches current**

`CHECKPOINT.md` exists at CWD and its `**Branch:**` line matches the current git
branch. → Resume it. This is the normal case. Proceed to Step 5.

**Case B — CHECKPOINT.md present, branch differs from current**

`CHECKPOINT.md` exists at CWD but its `**Branch:**` line is for a different
branch than the one you are currently on. → Flag the drift and prompt the user:

> `CHECKPOINT.md` is for branch `<X>`, but you are currently on `<Y>`. How would
> you like to proceed?
>
> - **(a)** Resume it as-is (stay on current branch, use the checkpoint from
>   `<X>`)
> - **(b)** Archive it to `.checkpoints/<X-slug>.md` first, then pick a
>   checkpoint from the archive
> - **(c)** Resume a specific archived checkpoint — list the archive contents so
>   I can pick

Wait for the user's response before continuing.

**Case C — No CHECKPOINT.md at CWD, archive has `<current-slug>.md`**

`CHECKPOINT.md` does not exist at CWD, but `$ARCHIVE/<current-slug>.md` does
exist. → Offer to restore it:

> Found an archived checkpoint for the current branch (`<current-slug>`).
> Restore it to continue work?

On user confirmation: **move** (not copy) `$ARCHIVE/<current-slug>.md` to
`CHECKPOINT.md` at CWD, then proceed to Step 5. On user decline: stop and report
no active checkpoint to resume.

**Case C′ — No CHECKPOINT.md at CWD, no plain slug, but archive has
`<current-slug>.mirror.md`**

`CHECKPOINT.md` does not exist at CWD, `$ARCHIVE/<current-slug>.md` does not
exist, but `$ARCHIVE/<current-slug>.mirror.md` does exist (a linked-worktree
mirror written by `/checkpoint-save` Step 5b). → Offer to restore it:

> Found a linked-worktree mirror checkpoint for the current branch
> (`<current-slug>`). This was saved from a worktree that may have been removed.
> Restore it to continue work?

On user confirmation: **copy** (not move) `$ARCHIVE/<current-slug>.mirror.md` to
`CHECKPOINT.md` at CWD, then proceed to Step 5. (Copy, not move — keep the
mirror in place in case the restore is tentative.) On user decline: stop and
report no active checkpoint to resume.

**Case D — No CHECKPOINT.md at CWD, no slug match, archive non-empty**

`CHECKPOINT.md` does not exist at CWD, neither `$ARCHIVE/<current-slug>.md` nor
`$ARCHIVE/<current-slug>.mirror.md` exist, but the archive contains other `.md`
files (excluding `*.prev.md` and `*.mirror.md`). → List the archive contents and
ask the user to pick:

> No checkpoint found for the current branch. The following archived checkpoints
> are available:
>
> 1. `.checkpoints/<slug-1>.md`
> 2. `.checkpoints/<slug-2>.md` ...
>
> Enter the number of the checkpoint to restore, or press Enter to cancel.

On pick: **move** (not copy) the chosen file to `CHECKPOINT.md` at CWD, then

From laurac8r/claude-damn, MIT.

More from laurac8r/claude-damn