---
name: handoff
description: Use at the end of a session in the sdg-skill repo to close out work cleanly so the next session can resume without reading the chat history. Updates TASKS.md / STATE.md, appends to docs/decisions.md if needed, and commits with the right T<id>: prefix.
disable-model-invocation: true
---

# Handoff protocol for sdg-skill

Run this when work is complete (or when stopping for the day) so the next
session can pick up cleanly via `/resume`. The goal: every session ends with
the repo in a state where `git`, `STATE.md`, and `TASKS.md` all agree.

## Steps

1. **Tick `TASKS.md`.** For each task completed in this session, change
   `[ ]` → `[x]` and append `(done <ISO date YYYY-MM-DD>, <commit-sha>)`
   to the same line. Use today's date.

2. **Update `STATE.md`.** Set:
   - `Active task` — the task you just finished, or `None` if at a
     boundary.
   - `Last commit` — the SHA you're about to create (or just created).
   - `Last action` — one-line summary of what was done.
   - `Next action` — the next concrete thing a future session should do
     (typically the next unblocked task in `TASKS.md`).
   - `Blockers` — list any new blockers; clear any that were resolved.

3. **Append to `docs/decisions.md`** ONLY if the work involved an
   architectural or non-obvious choice that a future contributor would need
   the rationale for. If it was a routine implementation, skip this step —
   `docs/decisions.md` is for ADRs, not changelogs.

4. **Commit.**
   ```bash
   git add -A
   git commit -m "T<id>: <one-line summary>"
   ```
   - Use the task ID being closed (or the most relevant one).
   - One-line subject; keep it under ~70 chars.
   - Include a body only if the change is non-obvious from the diff.

## Branch note

- Small fixes: commit directly to `main` with the `T<id>:` prefix.
- Risky / large changes: you should already be on a `feat/T<id>-<slug>`
  branch — push and open a PR for squash-merge instead of committing direct.

## Don't

- Don't tick a task as `[x]` if its acceptance criteria (`Acceptance:` line
  in `TASKS.md`) was not actually met. Leave it `[~]` and note the gap in
  `STATE.md`.
- Don't bypass the redact / provenance rules in any handoff commit (those
  are hard rules in `CLAUDE.md`).
- Don't commit `key.json`, `.env*`, `runs/`, or `htmlcov/` (already
  gitignored, but double-check `git status`).
- Don't run `git push --force` or amend commits that are already on
  `main`.