| name | session-handoff |
| description | Document a dead end so future sessions avoid re-exploring. Writes an abandon record to .claude/abandoned/<date>-<topic>.md capturing what was tried, why it failed, and what was learned. Invoked as `/session-handoff --abandon`, or when the user says "abandon this", "this didn't work", "scrap this approach", or "dead end". Also used by claude-flow Phase 1 (Explore/Archive path) and the research skill. Normal state-export handoffs are written by the `next` skill to docs/plans/<date>-session-handoff.md — not by this skill. |
| user-invocable | true |
Session Handoff — Abandon Mode
Token Economy
Apply token-economy whenever this skill would otherwise trigger broad exploration, repeated file reads, multi-file scans, or heavy reference loading.
- Load only the phase, reference, or script needed for the current step.
- Prefer targeted search and line-range reads over whole-file slurping.
- Batch independent tool calls and keep narration/results tight.
- If the task is tiny or the file set is already known, apply the relevant patterns inline instead of loading extra material.
Archive failed approaches so future sessions don't re-explore them. The record becomes
visible as "previously ruled out" context at the next SessionStart.
Role Contract
You are the abandon-record scribe for failed or intentionally stopped work. Your
role is to preserve what was tried, why it failed, and what should not be
re-explored by the next session.
Scope
Use this skill only for dead ends, abandoned approaches, or explicit
/session-handoff --abandon requests. Return the abandon-record path, branch
status, and any saved artifact details; normal resumable handoffs stay with the
next skill.
When to invoke
- User says "abandon this", "this didn't work", "scrap this approach", "dead end"
/session-handoff --abandon (explicit invocation)claude-flow Phase 1 Explore → Archive path (invoked automatically)research skill recommends this when a line of investigation hit a wall
What this skill does NOT do
- Normal state export for cross-session resume — that's the
next skill's job. It writes a
narrative handoff doc to docs/plans/<date>-session-handoff.md and commits it.
- Post-commit learning capture — that's
anthropic-skills:session-learnings (+
anthropic-skills:consolidate-memory).
The process
Step 1 — Gather abandon context
Collect:
- Current branch (
git branch --show-current)
- Modified files (
git diff --name-only and git diff --cached --name-only)
- Phase/step if claude-flow is active (read
.claude/workflow-state.json if present)
Then ask the user (or infer from conversation):
- What was the approach? The specific thing that was tried.
- Why is it being abandoned? Technical limitation, wrong direction, better approach found.
- What was learned? Insight worth preserving so future attempts don't re-explore.
Step 2 — Write the abandon record
Create $PROJECT/.claude/abandoned/ if needed. Write to
$PROJECT/.claude/abandoned/YYYY-MM-DD-<topic>.md:
# Abandoned: <topic>
**Date:** YYYY-MM-DD
**Branch:** feature/xyz (deleted / kept for reference)
## What was attempted
Brief description of the approach and what was built.
## Why abandoned
- Reason 1
- Reason 2
## What was learned
- Insight that should inform future attempts
- Technical discovery worth preserving
## Files modified
- `path/to/file.py` — what was changed
## Saved artifacts (if applicable)
- **Patch:** `abandoned/YYYY-MM-DD-<topic>.patch`
- Base SHA: `<git rev-parse origin/main>` (run at save-time)
- Net: `+N / -M` lines (run `grep -c "^+" / "^-"` and record)
- **Stash:** `<message from git stash list>` in canonical clone
A future session reading this record needs the base SHA to compare against origin/main at resume-time — if they differ, the patch's deletion context is stale and applying it will silently revert intervening commits. Recording +N / -M at save-time gives the resumer a sanity check against the description. See per-project memory feedback_verify_saved_patch_base_before_apply.md and pattern_parked_patch_double_anchor.md.
Step 3 — Clean up
- If on a feature branch with no commits worth keeping: offer to delete the branch
- If on a feature branch with useful partial work: note "kept for reference" in the record
- Remove
.claude/handoff.md if it exists (stale state dump from the retired normal mode)
Step 4 — Announce
Tell the user:
- Path to the abandon record
- That the SessionStart hook surfaces the
abandoned/ dir contents as "previously ruled out"
context in future sessions
- Whether the branch was deleted or kept
MCP integration
The claude-flow MCP server exposes .claude/abandoned/*.md as resources; MCP-speaking
clients can read abandon records programmatically without parsing files.
Recovery: app crash mid-session
When the Claude Code app crashes and a session is lost, the JSONL transcript is recoverable on disk at ~/.claude/projects/<project-slug>/<session-uuid>.jsonl. Read it to determine what shipped vs. what was pending — the transcript captures every tool call and message so you can reconstruct the in-flight commits, branch state, and outstanding user corrections without re-exploring. Cross-check against git log --oneline -20 + gh pr list --state all --search "merged:>=<date>".
To find the right transcript, list ~/.claude/projects/<project-slug>/*.jsonl sorted by mtime; the most recent file matching the project is usually the lost session. head -3 of the JSONL gives you the cwd + sessionId so you can claude --resume <sessionId> from the original directory.
Related
next — writes durable narrative handoffs for active work streams (different artifact, different purpose)anthropic-skills:session-learnings — captures learnings after successful commitsclaude-flow Phase 1 — the Explore/Archive path invokes this skill automatically
