ezos26/claude-skills/last-rites

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