ph

---
name: ph
description: Prepare session handoff for continuation in a new conversation. Use when 'prepare handoff', 'save progress',
  'session handoff', 'I need to stop', 'prepare for next session', 'hand off', 'write handoff', or when the user wants to
  pause mid-implementation and resume later in a fresh context window.
allowed-tools: Read Write Edit Bash Glob Grep
metadata:
  claude_argument_hint: '["task-directory"]'
compatibility: Portable clients may not enforce Claude Code invocation guards or project setup behavior.
---

<!-- claudops-build: project-config-pointer -->
> If `.claude/skills/ph/SKILL.md.disabled` exists, stop before reading a fallback.
> **Project configuration:** If the current project contains `.claude/skills/ph/SKILL.md`, read and apply it instead of this bundled default. The project copy is the capability source of truth.
> **Repository context:** Read `../setup/references/task-context.md` when resolving a task, project commands, named agent roles, or legacy `.claude/` resource paths. Use repository evidence and applicable project instructions; a missing local workflow copy does not require setup. Resolve bundled resources from the installed skill, never from the target cwd.

# 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.

```bash
# 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**:
   ```bash
   git diff --name-only $(git merge-base HEAD main)..HEAD
   ```
4. **Capture test state**:
   ```bash
   {{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:

```markdown
# 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.