Last Rites

Two-mode skill for session continuity: RECEIVE existing handoffs or CREATE new ones.

MODE DETECTION (READ FIRST)

Before doing anything, determine which mode you're in:

CRITICAL: If a handoff already exists and user points you to it, you are the RECEIVER. Do NOT create a new handoff. Read it and work.

RECEIVE MODE (You're the New Claude)

The handoff document is your mission brief. It was written FOR YOU by the previous Claude session.

Receive Workflow

1. Read the handoff the user points you to (e.g., docs/handoffs/002-feature.md)
2. Acknowledge what you learned: current state, critical knowledge, gotchas
3. Start on "Next Actions" - these are your immediate tasks
4. Read "Files to Read First" if you need more context
5. Work - continue the task from where the previous session left off

What the Handoff Contains (For You)

• Quick Start: How to get productive in 30 seconds
• Git State: Uncommitted work, recent commits
• Critical Knowledge: Things you MUST know (imperatives, not history)
• Gotchas & Warnings: Traps the previous Claude found
• Next Actions: Your TODO list, start here
• Open Questions: Things to investigate

Receive Mode Output

After reading the handoff, say something like:

Read handoff 002. Current state: [summary].
Starting on: [first next action].

Then BEGIN WORKING. Do not ask permission. The handoff IS your permission.

CREATE MODE (You're Ending a Session)

Preserve critical context before session compaction by creating an instruction document for the next Claude instance.

WHY CONTEXT FORKING MATTERS (READ THIS FIRST)

You have context bias. After a long session, you're blind to:

• What you assumed but never verified
• Details you think are obvious but aren't documented
• Holes in your understanding that a fresh Claude would notice immediately

Fresh agents see what you can't. By spawning agents WITHOUT your context, they:

• Ask "wait, what is this?" about things you've stopped questioning
• Notice missing documentation you forgot to write
• Find gaps between what you did and what you think you did

This is not redundancy - it's triangulation. Five agents reading the same codebase will notice five different things. Their combined blind spots are smaller than yours.

CRITICAL: Context forking is mandatory. All intel agents MUST run in background (run_in_background: true). Their work stays in output files, NOT in your context. You only receive the final handoff path. If you skip this, you'll run out of context before the handoff is written.

Core Principle

You are NOT writing a summary or obituary. You are writing mission orders for the next Claude session. The handoff document IS the system prompt for your successor.

Workflow

Phase 0: Extract Session Brief (YOU DO THIS)

Before spawning any agents, extract the session context from your conversation. You have this context - the agents don't.

Create a Session Brief by answering these questions:

## Session Brief (Parent Context)

### Feature/Task
[What specific feature or task was being worked on?]

### User's Goal (In Their Words)
[What did the user actually ask for? Quote them if possible.]

### Files Created/Modified This Session
- [file1.ts] - [what was done to it]
- [file2.md] - [what was done to it]

### Key Decisions Made
| Decision | Why | What Was Rejected |
|----------|-----|-------------------|
| [decision] | [rationale from conversation] | [alternatives discussed] |

### Gotchas Discovered During Session
- [Issue you hit and how you solved it]
- [Thing that didn't work as expected]

### Current State
[Where did the work end up? What's done vs pending?]

### Uncommitted Work
[List files that need to be committed]

### Next Steps (Your Understanding)
1. [What you think should happen next]
2. [Second step]

This brief is the foundation. Agents will verify it against reality.

Phase 1: Launch Background Intel Agents

Spawn five sub-agents in background mode. ALL must use run_in_background: true.

CRITICAL: Each agent gets a DIFFERENT verification focus + the Session Brief.

Task tool parameters for EACH agent:
- subagent_type: "Explore"
- run_in_background: true
- model: "sonnet"
- prompt: [Session Brief] + [Agent-specific verification focus]

CRITICAL: Agent Output Handling

Background agents write JSONL transcripts to output files, not clean reports. Each agent prompt includes an OUTPUT FORMAT section that tells the agent to output a structured report as their final message. When reading agent outputs:

1. The output file is JSONL (one JSON object per line)
2. Look for the LAST assistant message with "type":"text" content
3. That text contains the structured report
4. Use grep or tail to find the report, not Read (too large)

Example extraction:

tail -5 /path/to/agent.output | grep -o '"text":"[^"]*REPORT[^"]*"' | head -1

Or have the synthesizer agent do the extraction since it can use bash.

Agent 1: Git State Verifier

## Session Brief
[paste session brief here]

## Your Focus: Git State Verification

Verify the git state matches what the parent session claims:

1. Run `git status` - do uncommitted files match the Session Brief?
2. Run `git diff --name-only` - any files missing from the brief?
3. Run `git log --oneline -5` - what was recently committed?
4. Check if any work is staged vs unstaged
5. Look for any .gitignore issues with claimed files

## OUTPUT FORMAT (MANDATORY)

When done, output ONLY this exact format - NO conversation, NO explanation:

GIT STATE REPORT ================ Match: [YES/NO] Discrepancies: [list or "none"]

Uncommitted Files:

• [file]: [staged/unstaged]

Recent Commits:

• [hash] [message]

Commit Recommendation: [one line message]

Lost Work Risk: [none/low/high + what]

Keep under 50 lines. No prose. Just the report.

Agent 2: Documentation Verifier

## Session Brief
[paste session brief here]

## Your Focus: Documentation Verification

Verify the documentation matches the claimed work:

1. Read any docs mentioned in the Session Brief
2. Check docs/handoffs/ for existing handoff numbering
3. Read the 1-2 most recent handoffs - do they cover the same feature/topic?
4. Read AGENTS.md - does it reflect current patterns?
5. Look for any TODO comments in modified files
6. Check if new features have corresponding documentation

## OUTPUT FORMAT (MANDATORY)

When done, output ONLY this exact format - NO conversation, NO explanation:

DOCUMENTATION REPORT ==================== Documented: [YES/PARTIAL/NO] Gaps: [list or "none"]

Next Handoff Number: [NNN] Existing Handoffs:

• [NNN]: [topic] [relevant: yes/no]

AGENTS.md Status: [exists/missing] [needs update: yes/no] Patterns to Add: [list or "none"]

TODO/FIXME Found:

• [file:line]: [text]

Keep under 50 lines. No prose. Just the report.

Agent 3: Code State Verifier

## Session Brief
[paste session brief here]

## Your Focus: Code State Verification

Verify the code state matches the claimed implementation:

1. Read each file listed in "Files Created/Modified"
2. Verify the claimed functionality exists
3. Check for any incomplete implementations (TODO, FIXME, commented code)
4. Look for obvious bugs or issues
5. Check imports - are all dependencies present?

## OUTPUT FORMAT (MANDATORY)

When done, output ONLY this exact format - NO conversation, NO explanation:

CODE STATE REPORT ================= Match: [YES/PARTIAL/NO] Discrepancies: [list or "none"]

Incomplete Implementations:

• [file:line]: [issue]

Missing Dependencies: [list or "none"]

Critical Files (read first):

1. [file]: [why]
2. [file]: [why]

Issues Found:

• [severity]: [description]

Keep under 50 lines. No prose. Just the report.

Agent 4: Test/Run Verifier

## Session Brief
[paste session brief here]

## Your Focus: Runnability Verification

Verify the work can actually be run/tested:

1. Check package.json for relevant scripts
2. Look for test files related to the feature
3. Check .env.example for required environment variables
4. Look for any migration files that need to be run
5. Check for any build/compile steps needed

## OUTPUT FORMAT (MANDATORY)

When done, output ONLY this exact format - NO conversation, NO explanation:

RUNNABILITY REPORT ================== Runnable: [YES/NO/PARTIAL] Blockers: [list or "none"]

Commands:

• Dev: [command]
• Build: [command]
• Test: [command]

Environment Required:

• [VAR]: [description]

Setup Steps:

1. [step]
2. [step]

Test Coverage: [exists/missing] [files if exist]

Keep under 50 lines. No prose. Just the report.

Agent 5: Gotcha Hunter

## Session Brief
[paste session brief here]

## Your Focus: Finding Undocumented Gotchas

Look for things the parent session might have forgotten to mention:

1. Search for error handling in modified files - any edge cases?
2. Look for hardcoded values that might cause issues
3. Check for any TODO/FIXME/HACK comments
4. Look at recent commits for patterns of fixing mistakes
5. Check for any obvious security issues or anti-patterns

## OUTPUT FORMAT (MANDATORY)

When done, output ONLY this exact format - NO conversation, NO explanation:

GOTCHA REPORT ============= Issues Found: [count]

Gotchas (Session Brief Missed):

• [severity]: [description]

Watch For:

• [issue]: [why]

Hardcoded Values:

• [file:line]: [value] [risk]

Unanswered Questions:

• [question]

Security/Anti-patterns:

• [issue or "none"]

Keep under 50 lines. No prose. Just the report.

After launching all 5 agents, you will receive 5 output file paths. Store these paths.

Phase 2: Launch Synthesizer Agent (Background)

Once all 5 intel agents complete, launch a sixth synthesizer agent - also in background:

Task tool parameters:
- subagent_type: "general-purpose"
- run_in_background: true
- prompt: [synthesizer prompt with Session Brief + 5 output file paths]

Synthesizer Prompt Template:

You are the synthesizer for a session handoff. You have:
1. The parent session's Session Brief (their understanding)
2. Five verification reports from fresh agents (reality check)

## Session Brief (Parent's Claim)
[paste full session brief]

## Verification Report Files (JSONL format)
- [path1] - Git State Verifier
- [path2] - Documentation Verifier
- [path3] - Code State Verifier
- [path4] - Test/Run Verifier
- [path5] - Gotcha Hunter

## CRITICAL: Extracting Reports from JSONL

The output files are JSONL (JSON Lines) containing the full agent transcript.
Each agent was instructed to output a structured report as their FINAL message.

To extract each report, use Bash:

Extract the last text content containing "REPORT"

cat [path] | grep '"text"' | tail -3 | grep -i 'report'

Or use this pattern for each file:

tail -20 [path] | grep -oP '"text":"[^"]REPORT[^"]"' | tail -1

Do NOT use Read tool on these files - they're too large.

## Your Job

1. Extract all 5 structured reports using Bash
2. Compare each report to the Session Brief
3. TRUST THE AGENTS over the Session Brief when they conflict
4. Combine into a unified handoff that reflects ACTUAL state
5. Check docs/handoffs/ for the highest numbered file
6. Check if prior 1-2 handoffs cover the same feature/topic
7. Write the handoff to docs/handoffs/[NEXT_NUMBER]-[feature-name].md
8. Update AGENTS.md with learnings if it exists (skip if no AGENTS.md)

Key principle: The agents have fresh eyes. If they found something the
parent missed, include it. If they contradict the parent, note the
discrepancy and go with verified reality.

Use the handoff template structure below. Omit sections that don't apply.

When done, output ONLY: "Handoff ready: docs/handoffs/[NNN]-[feature-name].md"

Phase 3: Wait and Report

Use TaskOutput to wait for the synthesizer to complete. When it finishes, output ONLY what it returned:

Handoff ready: docs/handoffs/[NNN]-[feature-name].md

Then STOP. Do not:

• Summarize what was written
• Read the handoff back into your context
• Offer to do anything else
• Use any more context

Handoff Template (For Synthesizer)

# Handoff [NNN] - [Feature/Task Name]
Generated: [timestamp]

## Quick Start (30 seconds to productive)
Branch: `feature/xyz`
Run: `npm run dev` (port 3000)
See: [URL or file path to current work]
Status: [one line - what's working, what's not]

## Git State
Branch: [current branch]
Uncommitted files:
- [file1] - [brief description of changes]
- [file2] - [brief description of changes]
Recent commits on this branch:
- [hash] [message]
PR status: [if exists, link and status]

## Related Handoffs (Optional)
<!-- Include this section ONLY when the feature spans multiple sessions -->
<!-- Check if recent handoffs (1-2 prior) cover the same feature/topic -->
If deeper context needed:
- [NNN-1] `docs/handoffs/004-topic.md` - [what it covers that's still relevant]
- [NNN-2] `docs/handoffs/003-topic.md` - [architectural context or decisions]

## Environment
- Frontend: [command and port, if applicable]
- Backend: [command and port, if applicable]
- Database: [local/remote, connection details if relevant]
- Kill/restart required: [yes/no and when]
- Special considerations: [e.g., "production-only service, test carefully"]

## Immediate Context
You are continuing work on [specific task]. Current state: [where we are].

## User's Actual Goal
[High-level objective beyond the immediate feature]

## Priority/Pace
[Is this "ship today" crunch or "get it right" exploration?]

## Your Role: Orchestrator, Not Executor
**Default to sub-agents.** Before doing work directly, ask: "Can a sub-agent do this?"
- Multi-file exploration → Explore agent
- Research questions → Explore agent
- Complex implementation → general-purpose agent
- Your context is expensive. Sub-agents are cheap and parallel.

## Critical Knowledge
- [Imperative statement about what successor MUST know]
- [Another critical fact in command form]

## Decision Rationale
| Decision | Why | Alternative Rejected |
|----------|-----|---------------------|
| [decision] | [reason] | [what was rejected] |

## User Preferences Learned
- [Preference discovered during session]

## Gotchas & Warnings
- DO NOT [specific thing that will break]
- WATCH OUT for [subtle issue discovered]

## Hands Off (Don't Touch These)
- [Code area or file user doesn't want changed right now]

## Known Issues (Intentionally Deferred)
- [Issue] - [Why deferred]

## Next Actions
1. [First concrete step to take]
2. [Second step]
3. Update AGENTS.md with learnings (MANDATORY)

**SAFETY GUARDRAILS - The handoff must NEVER include:**
- ANY PR operations (PRs are user-only territory)
- Destructive git: `reset --hard`, `clean -f`, `push --force`
- Deployments or database mutations
- Secrets: API keys, tokens, passwords, .env values

## Files to Read First
- `path/to/critical/file.ts` - [why]

## Commands to Run

Start environment

[command]

## Open Questions
- [Question that next session should investigate]

## Confidence Levels
**High (Verified by agents):** [items agents confirmed]
**Medium (Parent claim, not verified):** [items from Session Brief only]
**Low (Single agent found):** [outlier insights - still worth noting]

Triggering This Skill

CREATE MODE - Execute Last Rites when:

• Context usage approaches ~90%
• User says "last rites", "prepare handoff", "context is getting full"
• Before any manual /compact command
• When switching to a significantly different feature

RECEIVE MODE - Follow existing handoff when:

• User says "review the handoff", "continue from handoff", "take this handoff"
• User points you to a docs/handoffs/*.md file
• You're starting a new session and user provides context from previous session

For the Next Session

See RECEIVE MODE at the top of this document. The next Claude session should:

1. Detect that user is pointing them to an existing handoff → RECEIVE MODE
2. Read the handoff as their mission brief
3. Start working on "Next Actions" immediately

The handoff document IS the system prompt for your successor. They should not need this section - the handoff itself tells them what to do.