Session Pickup

Session Pick-up

Read context from previous session to prepare for new work.

Tasks to complete:

1. Verify the checkout is current (do this BEFORE reading any tracking file):

• If this is a git repo, run git fetch, then compare local HEAD to upstream:

git rev-list --left-right --count @{upstream}...HEAD (left = behind, right = ahead)

• Behind (left > 0): the tracking files may describe commits this checkout

does not have. Warn the user, recommend reconciling, and offer to git pull --rebase. Do NOT trust CONTEXT.md's contents until reconciled.

• Diverged (both > 0): local and remote have both moved. Warn the user,

recommend reconciling (rebase is usually right), and offer to do it. Do not plan new work on top of a diverged tip.

• Let the user decide; do not auto-reconcile without confirmation.
• Rationale: CONTEXT.md's updated/last_entry are self-reported and can

look fresh while the checkout is behind. Tracking files sometimes land via out-of-band pushes (including other projects' sessions), so a recent frontmatter date is NOT proof the local checkout is current.

1. Confirm a tracking system is present (before doing pickup work):

• Check whether docs/CONTEXT.md or docs/IMPLEMENTATION.md exists.
• If NEITHER exists, this project is not set up for project-tracking. Do not

improvise context or fabricate a plan. Report that no tracking system is present and suggest running the project-tracking skill to initialize one (or project-repo for a meta-repo coordinating several projects). Then stop.

1. Check for CONTEXT.md (token-efficient system):

• Try to read docs/CONTEXT.md
• If it exists:
• Check the updated date in frontmatter
• If older than 7 days, warn user it may be stale (in addition to the git

check in step 0)

• Read the entire file (~30-50 lines)
• Summarize current focus, active tasks, and blockers
• Report ready to work based on "Next Session" section
• DONE - no need to read other files unless context is unclear

1. Fall back to IMPLEMENTATION.md (if CONTEXT.md missing):

• Use Grep to search for "🔵" to find the current phase line number
• Use Read with offset/limit to read ~200-300 lines starting from that marker
• Understand from that section:
• What phase/sub-phase is active
• Task checkboxes and their status
• Any notes about what to work on next
• DO NOT read the entire IMPLEMENTATION.md file

1. Make a plan for what to do next based on the context

Note: CHRONICLES.md and DECISIONS.md are historical context. Only read them if you need deeper background on a specific decision or past work.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: pborenstein
• Source: pborenstein/handoff
• License: MIT

Install and usage instructions live in the source repository linked above.