handoff

name	handoff
description	Update a TPP with session progress and prepare it for the next session. Run when context is 80-90% full or when ending a session. Captures what was done, what was learned, and what comes next.
argument-hint	["path/to/_todo/YYYYMMDD-name.md"]
disable-model-invocation	true
allowed-tools	Read, Glob, Grep, Edit, Write, Bash

Handoff: Update TPP for Next Session

Purpose

You are ending (or pausing) a session. Update the active TPP so the next session can pick up exactly where this one left off — with no re-explanation needed.

Procedure

1. Locate the active TPP

If $ARGUMENTS is provided, use that path. Otherwise, find the most recently modified file in _todo/:

• Use Glob on _todo/*.md, pick the most recently modified

2. Read the current TPP in full

Note the existing structure so you preserve it. Do not rewrite sections that don't need updating.

3. Update the TPP with this session's work

Apply these edits, in order:

a. Current phase checkboxes

• Check off any phases that are now complete
• Leave the next phase unchecked

b. Tribal knowledge

• Add any new non-obvious facts discovered this session (API quirks, performance gotchas, incorrect assumptions, version constraints)
• Do NOT add facts already present

c. Completed tasks

• Move newly completed tasks to a "Session N (date)" subsection under "Completed tasks"
• Mark them [x]
• For each task, add a one-line note of any important discovery made while doing it

d. Failed approaches (if any)

• If you tried an approach that didn't work, add it to a "Dead ends" subsection with a one-line reason. This prevents the next session from repeating the mistake.

e. Remaining tasks

• Remove tasks that are now done
• Reorder remaining tasks by priority (must-do first)
• Add any new tasks discovered during this session

f. Next steps

• At the top of "Remaining tasks", add a ## Next session starts here comment with 1–3 bullet points naming the very first actions the next session should take

4. Trim for length

The TPP must stay under 400 lines. After updating:

• Delete fully-completed subsections that are no longer informative
• Remove obvious or redundant prose
• Compress verbose task descriptions to one line each

5. Confirm

Report to the user:

• Which TPP was updated
• The current phase
• How many tasks remain
• The "Next session starts here" bullets

Do not commit or push anything. The user will do that.