Checkpoint

---
name: checkpoint
description: Save a lightweight session checkpoint.
allowed-tools: Write, Bash, Read
---

# /checkpoint - Save Progress

Save current work state as a thread to survive context loss.

**Task ID (optional):** $ARGUMENTS

## Process

0. **Capture session learnings**
   Reflect on this session. If any reusable learnings exist (mistakes, patterns, gotchas, workflow improvements), call `/learn` for each before proceeding. Skip if nothing novel was learned. See CLAUDE.md `## Session Learnings` for guidance.

0c. **Extract session insights (lightweight)**
    Same as /handoff step 0c but briefer — max 2 insights.
    Skip if session just started or no explanatory content generated.
    Call `/learn` with source: "session-insight" for each.

1. **Check for recent auto-checkpoint** (upgrade instead of duplicate)
   ```bash
   # Find auto-checkpoints from last 5 minutes
   find workspace/threads -name "T-*-auto-*.json" -mmin -5 2>/dev/null | sort -r | head -1
   ```
   If found: upgrade that file in-place (add full fields: `initial_commit`, `commits_made`, `remote_url`, `knowledge_repos`, `worker`, `next_steps`; change `type` to `"checkpoint"`; rename file to remove `-auto-`). Then continue from step 7 (INDEX updates).

2. **Generate thread ID** if not provided
   - Format: `T-{YYYYMMDD}-{HHMMSS}-{slug}`
   - Derive slug from recent work (e.g., `mrr-report`, `email-fix`)

3. **Capture git state**
   ```bash
   git rev-parse --abbrev-ref HEAD          # branch
   git remote get-url origin 2>/dev/null    # remote
   git rev-parse --short HEAD               # current commit
   git log --oneline -5                     # recent commits
   git diff --name-only HEAD~3              # recently touched files
   git status --porcelain                   # dirty check
   ```

4. **Capture knowledge repo git states**
   Knowledge folders may contain embedded git repos at their canonical real-directory paths. For any knowledge path in files_touched, capture its repo state. Continue detecting legacy symlinks only so they can be reported for migration:
   ```bash
   # For each knowledge repo with changes:
   bash -c '
   shopt -s nullglob
   for knowledge_path in core/knowledge/public/* core/knowledge/private/* personal/knowledge/* companies/*/knowledge; do
     if [ -L "$knowledge_path" ]; then
       target=$(cd "$knowledge_path" 2>/dev/null && pwd -P) || continue
       case "$target" in
         "$(pwd -P)"/core/packages/*) continue ;;  # package-managed mount — the only valid knowledge link
       esac
       repo_dir=$(cd "$knowledge_path" && git rev-parse --show-toplevel 2>/dev/null) || repo_dir=""
       hq_repo=$(git rev-parse --show-toplevel 2>/dev/null) || hq_repo=""
       if [ -n "$repo_dir" ] && [ "$repo_dir" != "$hq_repo" ]; then
         echo "$knowledge_path: INVALID legacy symlink to $repo_dir (migration required — run hq reindex)"
       else
         echo "$knowledge_path: NONSTANDARD symlink to $target (knowledge must be a real directory)"
       fi
       continue
     fi
     [ -d "$knowledge_path/.git" ] || continue
     repo_dir=$(cd "$knowledge_path" && git rev-parse --show-toplevel 2>/dev/null) || continue
     dirty=$(cd "$repo_dir" && git status --porcelain)
     [ -z "$dirty" ] && continue
     echo "$knowledge_path: $(cd "$repo_dir" && git rev-parse --short HEAD) (dirty)"
   done
   '
   ```
   Include dirty knowledge repos in the thread JSON under `git.knowledge_repos`.

5. **Gather session state**
   - Summarize what was accomplished
   - List files touched
   - Identify next steps

5.5. **Close active session journal** (if any)
   Spec: `core/knowledge/public/hq-core/journal-spec.md`. If a journal was opened earlier in this session by `/brainstorm`, `/deep-plan`, `/prd`, or `/plan`, close it now:
   ```bash
   .claude/skills/_shared/journal.sh close "{project_dir}" "{one-line synthesis, ≤120 chars}"
   ```
   Pass the resolved project directory that owns this session's journal. Fail-soft: no-op if no owned active journal pointer exists. Use the same one-line summary you used for `conversation_summary` below.

6. **Write thread** to `workspace/threads/{thread_id}.json` (include knowledge_repos from step 3):
   ```json
   {
     "thread_id": "T-20260123-143052-mrr-report",
     "version": 1,
     "created_at": "ISO8601",
     "updated_at": "ISO8601",

     "workspace_root": "~/",
     "cwd": "current/working/dir",

     "git": {
       "branch": "main",
       "remote_url": "git@github.com:...",
       "initial_commit": "abc1234",
       "current_commit": "def5678",
       "commits_made": ["hash: message"],
       "dirty": false,
       "knowledge_repos": {
         "knowledge-{company}": {"commit": "abc1234", "dirty": true},
         "knowledge-ralph": {"commit": "def5678", "dirty": false}
       }
     },

     "worker": {
       "id": "worker-id or null",
       "skill": "skill-name or null",
       "state": "completed"
     },

     "conversation_summary": "1-2 sentence summary",
     "files_touched": ["relative/paths"],
     "next_steps": ["remaining tasks"],

     "metadata": {
       "title": "Human-readable title",
       "tags": ["searchable", "tags"]
     }
   }
   ```

7. **Also write legacy checkpoint** to `workspace/checkpoints/{task-id}.json` for backward compat

8. **Update INDEX files and recent threads**
   - Update `workspace/threads/recent.md` with last 15 threads (table format)
   - Update `INDEX.md` timestamp only (do NOT regenerate full content — it's now slim)
   - Regenerate `workspace/threads/INDEX.md` (all threads, full table)
   - Check files_touched for any `companies/*/knowledge/` paths — if found, regenerate that company's `knowledge/INDEX.md`
   - See `core/knowledge/public/hq-core/index-md-spec.md` for INDEX format

8b. **Document release**
    Run `/document-release` — the skill resolves company + project context on its own.
    Best-effort — skip silently on failure.

9. **Report**
   Chat report follows the active output style (`core/policies/hq-audience-mode.md`). Files this skill writes stay full prose. The templates below are chat-only.

   **Default (`HQ`, and any style that is not `hq-operator`):** one or two short plain sentences. Do not print Scope, Dedup, Action, file paths, thread IDs, or PIDs. Do not paste the operator template.

   `Progress saved. Keep going here, or open a new chat later and I'll pick this up.`

   **Operator (`/output-style hq-operator`):**
   ```
   Thread saved: workspace/threads/{thread_id}.json

   Summary: {summary}
   Git: {branch} @ {commit} ({dirty ? "dirty" : "clean"})
   Files: {count} files touched
   Next: {next_steps or "Work complete"}

   To hand off to fresh session: /handoff
   ```

## Thread vs Checkpoint

| Feature | Thread (new) | Checkpoint (legacy) |
|---------|--------------|---------------------|
| Git context | Full (branch, commits, dirty) | Minimal |
| Worker state | Captured | Not captured |
| Location | workspace/threads/ | workspace/checkpoints/ |
| Format | Rich JSON | Simple JSON |

## Notes

- Threads ensure work survives context clears
- Run frequently during long sessions
- Threads are searchable via `/search`

## See also

- `/handoff` — a full continuation package
- `/journal` — durable working memory