# Session Pause

> Write a detailed session handoff file by hand so the next session can pick up where this one left off. Use when the context window is filling up, you're switching phases, or you're stopping for a break.

- Skill: `iamneilroberts/session-pause` (Agent Skill)
- Install (CLI): `npx skillmds@latest add iamneilroberts/session-pause`
- Raw SKILL.md: https://api.skillmd.com/api/skills/iamneilroberts/session-pause/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: iamneilroberts (https://skillmd.com/u/iamneilroberts)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/iamneilroberts/session-pause

---


# Session Pause

Generate a detailed handoff file so a fresh session can pick up seamlessly.

## Steps

1. **Gather git state** by running these commands:
   - `git rev-parse --show-toplevel` (repo root — used for repo tagging)
   - `git branch --show-current`
   - `git status --short`
   - `git diff --stat`
   - `git log --oneline -5`

2. **Summarize from session memory** — write these sections:
   - **What Was Accomplished**: completed tasks with file paths
   - **Decisions Made**: key decisions with rationale
   - **Files Created or Modified**: table with file path, action, description
   - **Remaining Work**: actionable next steps with specific file paths
   - **Open Questions**: anything needing user input

3. **Determine output path**:
   - Use the repo root from `git rev-parse --show-toplevel` as the base directory (resolves to the worktree root when inside a worktree)
   - If `docs/summaries/` exists under that base, write there
   - Otherwise create `.claude-sessions/` under that base
   - Filename: `pause-{YYYY-MM-DD}-{topic-slug}.md` where topic-slug is a 2-3 word summary of the work

4. **Write the handoff file** using atomic write (write to `.tmp` then rename):

```markdown
# Session Pause: {Topic}
**Date:** {YYYY-MM-DD} at {HH:MM}
**Repo:** {output of `git rev-parse --show-toplevel`}
**Branch:** {branch}
**Uncommitted changes:** {yes/no}
**Stale if:** {1–4 mechanically checkable conditions that invalidate this handoff, pinned to exact refs — e.g. "main moves past {SHA}" · "PR #{N} merges" · "{path} changes" · "prod redeploys off {deploy-id}"; write `nothing — self-contained` if it can't rot}

## What Was Accomplished
1. {task} -> output at `{file path}`

## Decisions Made
- {decision}: {what} BECAUSE {why}

## Files Created or Modified
| File Path | Action | Description |
|-----------|--------|-------------|
| `{path}` | Created/Modified | {what changed} |

## Git State
```
{git status --short}
```

## Recent Changes
```
{git diff --stat}
```

## Recent Commits
```
{git log --oneline -5}
```

## Remaining Work
1. **Next**: {specific action with file paths}
2. **Then**: {specific action}

## Open Questions
- [ ] {question} — impacts {what}

## Instructions
Continue the work from this session. Start with the Remaining Work section.
Review git state to confirm nothing has changed since the handoff. Evaluate each
"Stale if" condition in the header: if any holds, say which, treat the claims it
covers as stale, and re-verify them against the live artifact before acting.
```

4.5. **Curate the handoff.** If a `curator` agent is available (ships in this collection as `agents/curator.md`; check by attempting the dispatch, skip silently if not), dispatch it (Agent tool, `subagent_type: curator`) with the handoff file path. It verifies the handoff's claims against git/files/read-only checks and the repo's invariants doc, if any. Append its report to the handoff file under `## Curator Verification` (atomic write) — this catches confabulation before the next session trusts it.

5. **Warn about uncommitted changes** if `git status --short` shows output. If the curator returned a CONTRADICTED claim, flag it prominently — the next session must not trust it as-is.

6. **Tell the user**: "Handoff saved to `{path}`. Type `/clear` to continue — if the `auto-resume.sh` hook is installed it loads automatically, otherwise run `/session-resume`."
   - If inside a worktree, also mention: "Note: this handoff is in the worktree. `/session-resume` will find it and switch back into the worktree automatically."