---
name: closeout
description: Run the full session closeout protocol — handoff doc, session log, blocker log, doc updates, git commit/push, continuation prompt, and verbal summary. Use when ending a session.
disable-model-invocation: true
---

# Session Closeout Protocol

Run every step below in order. Do NOT skip any step. Check off each one as you complete it.

## Step 1: Write Handoff Document

Create a new file: `handoffs/HANDOFF_SESSION_[N]_[YYYY-MM-DD].md`

Determine the session number by checking the most recent handoff in `handoffs/` and incrementing by 1.

The handoff MUST include ALL of the following sections:
- **Session Summary** — everything accomplished, in plain language
- **Incomplete Items** — table of everything not finished, with exact status
- **Next Steps** — precise, specific actions (not vague), in priority order
- **Critical Files** — every file created or modified, with full paths and why it matters
- **Codebase Context** — relevant code sections, patterns, and conventions for the next session
- **Decisions Made** — table of decisions with reasoning
- **Known Issues & Bugs** — anything broken or concerning, with severity
- **Continuation Prompt** — a ready-to-paste prompt (see Step 6)
- **Context Package** — the 3-5 most relevant files for the NEXT session to read first (see below)
- **Related Handoffs** — links to previous handoff docs that are relevant to ongoing work

### Context Package (Auto-Generated)
Generate the context package automatically using these signals:
1. Run `git diff --name-only HEAD~5` to find recently changed files
2. Check `.session/checkpoint.md` for files modified this session
3. Prioritize: CLAUDE.md (always #1), then files changed this session, then active specs/plans
4. Format:
```
CONTEXT PACKAGE (read in this order):
1. [file path] — [why: what context it provides]
2. [file path] — [why]
3. [file path] — [why]
```
This prevents the next agent from having to search through everything to find relevant context.

## Step 2: Update Session Log

Add an entry to `docs/status/SESSION_LOG.md` — new entries go at the TOP (most recent first).

Include: what was worked on, what was completed (bulleted list), key decisions, blockers, and handoff filename.

## Step 3: Log Blockers

If you hit ANY obstacles, dead ends, or workarounds during the session, log them. Include:
- What the blocker was
- When it was identified
- What you tried (including things that DIDN'T work — this is important for future agents)
- What finally resolved it (or that it's still unresolved)

Also log the resolution pattern to `agent-learnings/PATTERNS.md` so future agents can find it.

If no blockers were encountered, skip this step.

## Step 4: Update Changed Docs

Update any project documentation that changed during the session:
- `CLAUDE.md` — update the status section (brief summary)
- Any specs or other docs that were affected

## Step 5: Commit & Push to GitHub

If the session changed ANY code or project structure:

1. Run `git status` and `git diff --stat` to review changes
2. Verify no sensitive files are staged (`.env`, credentials, etc.)
3. Stage specific files (prefer naming files over `git add .`)
4. Write a descriptive commit message summarizing what changed and why
5. Push to the working branch
6. Confirm push succeeded

If no code/data files changed (documentation-only session), you may skip the push.

## Step 6: Write Continuation Prompt

Include this in the handoff document AND present it to the user. The continuation prompt must:
- Reference the handoff doc by filename so the next agent reads it
- Summarize the most important context in 2-3 sentences
- List the specific next actions (exact tasks, not vague)
- Reference the Context Package files
- Be self-contained (the next agent can start working from this alone after reading the handoff)

Format:
```
Read the handoff at handoffs/HANDOFF_SESSION_[N]_[YYYY-MM-DD].md.
[2-3 sentence summary of what was done and current state.]

Context package (read first): [file1], [file2], [file3].

Next: [Specific action 1], [specific action 2], [specific action 3].
```

## Step 7: Clean Up Session State

The `.session/` directory will be archived automatically by the next session's start hook. But ensure the session state reflects the final state:
- Update `.session/state.md` — mark all completed items, note what's still pending
- Update `.session/checkpoint.md` — final checkpoint showing session ended cleanly

## Step 8: Verbal Summary

Tell the user:
1. What was accomplished this session
2. What's still pending or incomplete
3. What the next session should start with
4. Present the continuation prompt for them to copy-paste
5. Remind them to run `/startup` at the beginning of their next session

## Step 9: Learning File Consolidation (Every 10th Session)

If this is Session 10, 20, 30, or any multiple of 10:

1. Review all entries in `agent-learnings/PATTERNS.md`, `agent-learnings/MISTAKES.md`, and `agent-learnings/DECISIONS.md`
2. **Duplicate entries:** Merge into a single entry, keeping the richer version
3. **Contradicted entries:** Mark as `**SUPERSEDED** by [entry name]` — do not delete, so the reasoning history is preserved
4. **Entries now encoded in code/config:** Mark as `**Implemented** — see [file path]` so agents know the pattern is enforced automatically
5. **Stale entries** (`Last Validated` is 20+ sessions old): Move to a `## Archived` section at the bottom of each file
6. Add a note to the handoff document listing what was consolidated and why

This step prevents learning files from growing indefinitely. Skip if this is not a multiple-of-10 session.

## Reminders
- NEVER skip writing the handoff document — it is the most important closeout artifact
- NEVER commit secrets (`.env`, API keys, credentials)
- If context is getting heavy, say so and suggest wrapping up BEFORE hitting limits
- The Context Package in the handoff is critical — it saves the next agent from searching blindly