handoff

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.

   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.