Ph

Prepare Handover Command

Announcement: Begin with: "I'm using the ph skill to prepare a session handoff."

PRIMARY OBJECTIVE

Capture the current implementation state into a cold-start brief (HANDOFF.md) so a fresh Claude session can resume work without re-exploring the codebase. This is invoked when context windows run long or when work spans multiple sessions.

Resolve the task with ../setup/references/task-context.md before writing. Use the selected task root, preserve an existing plan or compact TASK.md, and record the handoff link, current state, evidence, blockers, and one next action in that task record. A read-only request may return the proposed path without creating it.

Write-first discipline

Context may compact while this skill runs. Create HANDOFF.md with section headers immediately after STEP 1, then fill each section as you complete STEPS 2–5. A partially-written handoff on disk is more useful than a fully-planned one that never gets saved. Produce every section through to the end — do not stop early due to token concerns.

WHY THIS EXISTS

/si Continue mode works well when the task document is perfectly up to date. In practice, handoffs happen mid-step when docs are stale — checkmarks don't reflect actual code state, recent decisions aren't documented, and the next session wastes tokens re-discovering what this session already knew.

HANDOFF.md solves this by capturing a point-in-time snapshot that the next session can load directly.

WORKFLOW

STEP 1: Resolve Task

1. Resolve $ARGUMENTS, the linked active task, or the configured task convention with ../setup/references/task-context.md.
2. If several candidates remain plausible, ask which task; do not choose by recency alone.
3. Read the task entrypoint and linked active plan when one exists. A compact task record is valid; do not require a formal decomposition or exact headings when the required state and evidence are present.
4. If HANDOFF.md already exists, read and reconcile it with the task document before editing it; otherwise create it with the section headers from STEP 5 immediately after resolving the task. Never overwrite an existing handoff before reading it; fill the reconciled artifact as the remaining steps complete.

STEP 2: Capture Git State

Run all of the following bash calls in the same turn — they are independent. Batch them into a single response with parallel tool calls rather than issuing them one at a time.

# Branch and last commit
git branch --show-current
git log --oneline -5

# Working tree state
git status --short

# Uncommitted changes summary
git diff --stat
git diff --cached --stat

# Stash list
git stash list

STEP 3: Capture Implementation State

1. Identify current step: Read available step/status markers. If a compact record has no checkboxes, derive the current state from its evidence and next action instead of requiring the legacy format.
2. Reconcile with reality: Compare task doc claims against actual code. Check every file in the diff, not only the files named in steps:
   • Do files mentioned in checked steps exist?
   • Do tests for checked steps pass?
   • Are there files modified but not mentioned in any step? (exploratory changes, debug code, temp scaffolding — all go under "Gotchas")
   • Is there uncommitted work that belongs to no step at all? Document it.
3. Identify recently modified files:

   git diff --name-only $(git merge-base HEAD main)..HEAD
   

4. Capture test state:

   {{TEST_CMD}} 2>&1 | tail -20
   

The git diff --name-only call above can run in the same turn as the test command and the STEP 2 git calls — batch them with parallel tool calls.

STEP 4: Capture Context

1. Blockers: Any known issues, failing tests, unresolved errors
2. Key decisions: Implementation choices made during this session that aren't in the task doc
3. Deferred issues: Pre-existing problems discovered but intentionally not fixed
4. Gotchas: Surprising behaviors, workarounds applied, things the next session should know

STEP 5: Write HANDOFF.md

Write to <resolved-task-root>/HANDOFF.md (preserve any legacy path already selected). Use the existing handoff schema when one exists; the template below is a default set of facts, not a required legacy heading layout:

# Session Handoff

**Date**: YYYY-MM-DD
**Branch**: [branch-name]
**Last Commit**: [sha] [message]

---

## Current State

**Step in progress**: Step [N]: [description]
**Completed steps**: [list of checked steps with brief notes]
**Overall progress**: [X of Y steps complete]

## Files to Read First

Load these files to rebuild context (ordered by importance):

1. `[path/to/most-critical-file]` — [why: e.g., "main implementation file for this step"]
2. `[path/to/test-file]` — [why: e.g., "failing test that needs GREEN implementation"]
3. `[path/to/related-module]` — [why: e.g., "dependency modified in Step 2"]
4. `[path/to/task-doc]` — [why: "source of truth for requirements"]
5. `[path/to/context-file]` — [why: e.g., "database schema with new model"]

## Working Tree State

[git status output]

**Uncommitted changes**: [description of what's in progress but not committed]
**Stashes**: [any stashed work and what it contains]

## Test State

[test output summary — passing/failing counts]

**Failing tests**: [list with file:line if applicable]
**Reason**: [why they fail — e.g., "RED phase, implementation not written yet"]

## Key Decisions Made This Session

| # | Decision | Rationale |
|---|----------|-----------|
| 1 | [what was decided] | [why] |

## Blockers & Gotchas

- [any known issues the next session should be aware of]

## Deferred Issues

- [pre-existing problems not in scope, logged here for awareness]

## Next Actions

1. [Immediate next thing to do — be specific]
2. [Then this]
3. [Then this]

STEP 6: Update Task Document

1. Ensure all checked/unchecked steps accurately reflect code state
2. Add a note in the task entrypoint: **Handoff prepared**: See HANDOFF.md for session context. Link the handoff and the final evidence/next action from the task record before pausing.

HOW /si CONTINUE MODE USES HANDOFF.md

When /si detects Continue mode, it checks for HANDOFF.md in the resolved task root:

• If HANDOFF.md exists: Load it first, read the "Files to Read First" section, then reconcile with task doc. This is faster and more accurate than re-exploring.
• If HANDOFF.md is absent: Fall back to the current behavior (scan task doc checkmarks, run tests, read recent commits).

After /si Continue mode successfully resumes:

• Rename HANDOFF.md to HANDOFF-[date].md (archive, don't delete — useful for debugging session boundaries)

CONSTRAINTS

• HANDOFF.md stays uncommitted — it's a transient artifact consumed by the next session. Leave it in the working tree, not in git history.
• This skill only captures state — If you notice a quick fix while reviewing, log it under "Next Actions" and let the next session decide. Fixing mid-handoff corrupts the snapshot you are about to save.
• Be honest about state — if tests are failing, say so. If a step is partially done, say so. The next session needs truth, not optimism.