checkpoint-save

Files (1)

• SKILL.md

SKILL.md (first lines)

# Checkpoint Save

Pause here and create a checkpoint CHECKPOINT.md file to allow us to quickly
resume work on this later. Use / reference memories as needed.

## What to Capture

Create `CHECKPOINT.md` in the project root (or working directory) with:

```markdown
# Checkpoint: [Brief Title]

**Date:** [today's date] **Branch:** `[current git branch]` **Session context:**
[1-2 sentence summary of what we were doing]

## Current State

- What's been completed
- What's in progress (with file paths and line numbers)
- What's not yet started

## Next Steps

1. [Exact next action to take]
2. [Following actions in order]

## Key Decisions Made

-

[Decision]: [Why] (so we don't re-debate)

## Open Questions / Blockers

- [Anything unresolved]

## Files Modified

- [List of files changed in this session, with brief note on what changed]

## Relevant Memories

- [Reference any memory files that provide context for this work]

## Resume Command

[Exact prompt or slash command to resume, e.g. "Continue from CHECKPOINT.md"]
```

## Process

### Step 1 — Compute current-branch slug

Run `git branch --show-current` to get the current branch name. If the output is
empty (detached HEAD), fall back to the basename of CWD (`basename "$PWD"`).
Apply slug rules to produce `<slug>`:

1. Lowercase.
2. Replace `/` with `-`.
3. Strip characters outside `[a-z0-9-]`.
4. Collapse consecutive `-`.

### Step 2 — Resolve archive directory

Run:

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

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

Then:

```
ARCHIVE=$(dirname "$COMMON_DIR")/.checkpoints
mkdir -p "$ARCHIVE"
```

This resolves to the **main checkout root's** `.checkpoints/` directory,
ensuring all git worktrees share a single archive.

### Step 3 — Verify `.gitignore` coverage

Check whether `.checkpoints/` is listed in the main checkout's `.gitignore` (the
`.gitignore` at `$(dirname "$COMMON_DIR")/.gitignore`). If the line is absent,
append `.checkpoints/` to that `.gitignore` and report to the user:

> "Added `.checkpoints/` to `.gitignore` in the main checkout. Please review and
> commit that change when ready."

Do NOT auto-commit — the user handles all git commits.

### Step 4 — Handle existing CHECKPOINT.md

If `CHECKPOINT.md` exists at CWD, parse its `**Branch:**` line and apply one of
the four cases below. **Before auto-selecting Case A (same branch), also check
for the Case D escape hatch** — a same-branch CHECKPOINT.md may belong to an
unrelated live effort, not a stale version of current work.

**Case A — Same branch as current, same effort (stale version of current
work):** Copy the existing file to `.checkpoints/<slug>.prev.md` (overwrite any
prior `.prev.md`). This is a rolling single-slot backup before the same-branch
overwrite. Use this when the existing checkpoint's **Current State** section
describes the same work you're about to re-checkpoint — it's a natural
supersession.

**Case B — Different branch:** The existing checkpoint belongs to a different
effort. Derive `<old-slug>` from the `**Branch:**` value in the existing file
(apply the same slug rules). Move (not copy) the existing `CHECKPOINT.md` to
`.checkpoints/<old-slug>.md`. On collision (file already exists), append `-2`,
`-3`, etc. until the name is free.

**Before proceeding to Step 5, verify the `mv` succeeded.** If it fails
(permissions, disk full, cross-device), abort: **"Failed to archive existing
CHECKPOINT.md. The old checkpoint is still at CWD. Resolve the mv failure before
retrying."** Do not overwrite `CHECKPOINT.md` until the archive is confirmed.

From laurac8r/claude-damn, MIT.

More from laurac8r/claude-damn