session

Session

Three modes plus a lightweight checkpoint pattern. Pick based on intent:

========================================

Handoff mode — end-of-session handoff for /resume/context-resume

Validate, prune, capture, and write. Counterpart to /context-resume.

Target: 2-3 minutes interactive, under 1 minute with --auto.

Arguments

Parse $ARGUMENTS:

• --auto: Fully non-interactive. Never ask the user anything. Auto-fix verifiable issues, silently skip ambiguous ones, auto-save learnings, auto-write handoff.

Step 0: Validate Persisted State

This step runs first, before capturing anything new. Review what's currently saved and prune stale or incorrect items.

0A. Memory Validation

Read the project's MEMORY.md (at ~/.claude/projects/<project-path>/memory/MEMORY.md). For each memory entry:

1. Read the memory file it points to
2. Verify against current state — check if the memory's claims are still true:
   • File paths mentioned → Glob/Read to confirm they exist
   • Function/class names → Grep to confirm they exist
   • Configuration claims → Read the config file to verify
   • Project state claims (e.g., "using X library", "deployed on Y") → check package.json/requirements.txt/git history
   • Process/workflow claims → verify against current tooling
3. Classify each memory:
   • Verified — claims confirmed against code/config. Keep as-is.
   • Stale — claims contradicted by current state. Update or remove.
   • Unverifiable — can't confirm or deny from code alone (e.g., user preferences, external system references). Keep as-is.

With --auto: Silently update or remove stale memories. Keep unverifiable ones. No user interaction.

Without --auto: Present stale items and proposed fixes. Ask once: "Update these? Pick numbers, edit, or skip."

0B. Handoff File Validation

If a previous handoff file exists at ~/.claude/notes/projects/<slug>/context-resume.md:

• Check if open PRs listed are still open (via gh pr view)
• Check if branches listed still exist
• Check if "next steps" are still relevant (were they completed this session?)

This informs Step 4 — the new handoff overwrites the old one, but knowing what changed helps write better next steps.

0C. Notes Validation

If ~/.claude/notes/ contains project-scoped notes or lessons, scan for:

• References to deleted files or renamed functions
• Outdated patterns (e.g., "use X" when X was replaced by Y)

With --auto: Silently remove or update verifiably stale notes.

Without --auto: Flag stale notes and ask once.

---

Step 1: Scan Session

Gather everything automatically — no user interaction needed.

Run in parallel:

• git log --oneline --since="8 hours ago" (adjust if user specifies a timeframe)
• git diff --stat + git stash list
• gh pr list --author @me --json number,title,state,updatedAt
• Search documentation/planning/ for status markers (IN PROGRESS, PENDING, COMPLETE)

Present a brief summary of findings.

Dirty working tree:

• With --auto: Leave uncommitted changes as-is. Note them in the handoff file.
• Without --auto: Ask once: "Uncommitted changes — commit first or leave them?"

---

Step 2: Capture Learnings

Review the session for knowledge worth persisting. Look for:

• Patterns, gotchas, debugging insights discovered
• Times the user corrected your approach
• Commands or workflows that worked well

Scope each item:

• Project-scoped → write to auto-memory at ~/.claude/projects/<project-path>/memory/
• Cross-project → write to ~/.claude/notes/ (use /notes or /lessons conventions)

With --auto: Auto-save all identified learnings without asking. Classify and write silently. Skip anything ambiguous about scope — default to project-scoped.

Without --auto: Present all candidates in a numbered list grouped by destination. Ask once: "Add any? Pick numbers, edit, or skip." Do not ask separate rounds for notes vs lessons.

Size checks (mention only if exceeded):

• MEMORY.md > 150 lines → nudge to prune (or auto-prune with --auto by removing lowest-value entries)
• Global notes > 100 lines → nudge to prune

---

Step 3: Changelog + Stale Plans (Optional)

Changelog: If CHANGELOG.md exists, compare session commits against [Unreleased]. Flag missing entries.

• With --auto: Auto-add missing changelog entries.
• Without --auto: Offer to add them.

If no changelog, skip silently.

Stale plans: If documentation/planning/ exists, check for:

1. Completed but unarchived — all phases ✅ COMPLETE but still in documentation/planning/.
2. Stale and abandoned — idle 14+ days with incomplete phases.

• With --auto: Auto-archive completed plans via git mv. Flag stale plans in the handoff file for next session's attention.
• Without --auto: Offer archive/delete/skip.

If none found, skip silently.

---

Step 4: Write Handoff File (branch-scoped)

Location: ~/.claude/notes/projects/<project-slug>/context-resume/<branch-key>.md

Per-branch handoff files coexist — you get a separate handoff for each branch/worktree, overwritten each session on that branch but not across branches.

Slug derivation: Git remote org/repo with / replaced by --. Fallback: directory name. Must match what /context-resume uses.

Branch key derivation (in this order):

1. git branch --show-current → if non-empty, sanitize by replacing / with - (e.g., feat/auth-redesign → feat-auth-redesign). This is the branch key.
2. Detached HEAD → _detached-<sha-short> (e.g., _detached-abc1234)
3. Not in a git repo → _unknown

Worktree note: Worktrees are branch-scoped in git — a worktree = a branch checked out at a different path. The branch name is the right key; worktree path is not needed.

Write tool creates parent directories automatically.

Required output shape (YAML frontmatter at top, then free-form body):

---
written_at: <ISO 8601 timestamp w/ timezone, e.g. 2026-04-22T14:45:32-04:00>
branch: <branch-key>
slug: <project-slug>
summary: <one-line summary of what the session did — max 120 chars; used by /gm hivemind briefing to orient the next session>
---

# Session handoff — <repo> / <branch> — <YYYY-MM-DD local date>

## Session summary
<1-3 sentence narrative: what did we do, why>

## Current state
<repo / branch / working tree / open PRs or tags>

## Shipped this session
<concise bullets or table>

## Next steps
<what should the next session pick up>

## Notes for next session
<surprising/gotchas/context not obvious from the code>

The frontmatter is parsed by TheClauu's hive-mind cache (bin/sources/handoffs.py) to surface a one-liner at session-start (e.g., "Last handoff 2h ago — '…summary…'"). The written_at timestamp and summary are therefore non-optional; other frontmatter fields are informational.

The handoff file is agent-optimized — structured for machine parsing, not human reading. It's ephemeral and overwritten each session on the same branch.

After writing:

• With --auto: Silent.
• Without --auto: "Handoff written to ~/.claude/notes/projects/<slug>/context-resume/<branch>.md. Use /context-resume next session on this branch."

---

Step 4b: Dump to Notion Session Log (optional, team-visible)

After writing the local handoff file, also push the session context to the shared Notion "Data Team Session Log" database so teammates can see exactly where you left off.

Run (in the background, non-blocking):

python3 <plugin-root>/bin/dump_session_context.py <cwd> <transcript_path>

Where <plugin-root> is the TheClauu plugin install root (available as $CLAUDE_PLUGIN_ROOT in hooks, or derive from the skill's own path).

Graceful degradation: If notion_session_log_db_id is not set in ~/.theclauu/config.json, the script is a silent no-op. Never block or error-message the user because of a missing Notion config.

What this writes to Notion:

• Upserts a page in the "Data Team Session Log" DB keyed by branch name.
• Sections: Done (session commits), In progress (uncommitted changes + TODO markers), Gotchas (extracted from transcript), Resume commands (checkout + env activation steps).
• History section is append-only — each session adds one timestamped entry; never deletes previous entries.

With --auto: run silently, no output. Without --auto: if the dump succeeded and Notion was configured, optionally note "Session context also written to Notion (Data Team Session Log)."

---

Integration Points

Other skills should trigger /session-handoff --auto at natural end-of-work boundaries:

• /commit-push-pr — after PR is created, suggest or auto-run handoff
• /implement-plan — after final phase is complete
• Pre-restart hooks — before systemctl restart or session teardown
• Context compaction — when the system compresses context, trigger a background handoff to capture state before it's summarized away

---

Rules

• Speed over thoroughness. Scan, validate, write. Do not turn this into a documentation exercise.
• One approval round per step (interactive mode only). Do not ask multiple rounds of questions within a step.
• No compound commands. Never chain commands with &&, ||, or ;. Make separate parallel tool calls instead — allowed-tools patterns only match simple commands, not compound ones.
• User says skip, you skip. The handoff file is the only non-optional output.
• With --auto, never ask. Auto-fix verifiable issues, skip ambiguous ones, save learnings, write handoff. Zero interaction.
• Validate before capture. Step 0 always runs before Steps 1-4. Don't save new state on top of stale state.
• Handoff file is ephemeral. Not a log. Overwritten each session.

========================================

Resume mode — start of new session, pick up from last handoff

Restore context fast. Target: under 30 seconds.

Step 1: Identify Project, Branch & Read Handoff

Derive the project slug:

1. git remote get-url origin — extract org/repo (e.g., artemis-xyz/api-server)
2. Fallback: current directory name
3. Replace / with -- for the file path (e.g., artemis-xyz--api-server)

Derive the branch key:

1. git branch --show-current → if non-empty, replace / with - (e.g., feat/auth-redesign → feat-auth-redesign)
2. Detached HEAD → _detached-<sha-short>
3. Not in a git repo → _unknown

Handoff lookup, in order:

0. Notion Session Log (v0.4+, team-visible): If notion_session_log_db_id is set in ~/.theclauu/config.json, query the "Data Team Session Log" DB for a page matching the current branch. Use bin/sources/notion.py::find_session_page_by_branch. If found, read its Done / In progress / Gotchas / Resume sections and surface them. Attribution line: "(from team Notion log — last edited by <Engineer> <N>h ago)". This means a teammate's handoff is visible even if they never ran /session-handoff locally — the SessionEnd hook writes to Notion automatically.

   If the Notion lookup fails (API down, token missing, db_id not configured), fall through silently to step 1.

1. Branch-specific (v0.3.5+): ~/.claude/notes/projects/<slug>/context-resume/<branch-key>.md

2. Legacy single-file fallback: ~/.claude/notes/projects/<slug>/context-resume.md (from v0.3.4 and earlier)

3. Cross-context fallback (v0.3.25+): If nothing found for the current slug, look at the TheClauu hive-mind cache at ~/.theclauu/cache.json. Read handoffs.all[0] — if it exists and age_seconds < 86400 (<24h), it's a recent handoff from a different slug (e.g. user ran /session-handoff from a subrepo then opened the next session in the parent workspace). Surface it explicitly: "Fresh handoff on <slug>/<branch> from N minutes ago — <summary>. To fully resume that thread: cd <slug-short> && claude then /context-resume. Otherwise continuing fresh here."

4. No handoff found: list any sibling context-resume/*.md files (i.e., handoffs for other branches) and print: "No handoff for this branch. Other branches have handoffs: [list]. Work fresh, or manually read one of those?"

When a handoff is found, read it — this is the most valuable context. Staleness check: if older than 14 days, flag it ("Last handoff was N days ago — context may be stale") but still read it. Weight the live scan more heavily when stale.

Do NOT fall back to stale legacy handoffs (e.g., a 2+ week old file) when a fresh cross-slug handoff exists — the cross-slug one is always higher signal than a stale current-slug one. Prefer recent over exact-match.

Step 2: Scan Current State (in parallel)

Run these in parallel:

Git: git status, git log --oneline -15, git branch --list, git stash list

PRs: gh pr list --author @me, gh pr list --review-requested @me

Plan docs: ONLY if the repo has a documentation/planning/ directory (exact path, not a generalized plans/ search). Grep for IN PROGRESS and PENDING status markers. Check for 00_OVERVIEW.md or 00_TECH_DEBT.md. Also flag any sessions where all phases are ✅ COMPLETE but haven't been archived to documentation/archive/ — suggest archiving. Do NOT scan docs/superpowers/plans/ or other legacy claudefather paths — those belong to a deprecated system and surfacing them as "active" adds noise.

Project context: Skim CHANGELOG.md unreleased section if present.

Do NOT read CLAUDE.md or MEMORY.md here — Claude already has those in context.

Step 3: Present Briefing & Suggest Starting Point

Use the format from references/templates.md.

Suggest what to work on, prioritized:

1. Fresh cross-context handoff (<24h) — "You just handed off <slug>/<branch> N minutes ago: <summary>. Resume that thread?" (Always wins; even over current-repo signals, because it's the engineer's last action in any context.)
2. Current-repo handoff next steps — "Last session's next-steps: [...]. Pick one?"
3. PR with changes requested — "PR #N has changes requested. Address those first?"
4. In-progress plan doc — "Phase N is in progress. Continue with /implement-plan?"
5. PRs to review — "N PRs waiting for review. Run /review-pr N?"
6. Dirty working tree — "Uncommitted changes. Review and commit first?"

Ask: "What would you like to focus on?"

Rules

• Read-only. Never modify files, never commit.
• Speed over depth. Scan, summarize, suggest. No deep analysis.
• No compound commands. Never chain commands with &&, ||, or ;. Make separate parallel tool calls instead — allowed-tools patterns only match simple commands, not compound ones.
• Handoff file is gold. Prioritize curated handoff context over raw git scanning.
• Slug must match /session-handoff. Both use: git remote org/repo with / to --, directory name fallback.

========================================

Name mode — label a session for easy /resume identification

Generate a descriptive session name in the format: DESCRIPTION - REPO#PR - BRANCH (all caps).

The session name must reflect what this session actually did — not just whatever branch is currently checked out. Sessions often switch branches, run in worktrees, or do investigative work unrelated to the current HEAD. Ground the name in the conversation, then use git state to confirm (or flag divergence).

Step 1 — Synthesize the session's actual work (from conversation, not git)

Before running any commands, write down in your head:

• What did we do this session? (e.g., "investigated dexs_swap_pairs directional-row dedup bug", "shipped webhook retry logic", "reviewed PR #123")
• Did we ship code, investigate, review, or mix? Investigative sessions may not map to any branch/PR.
• Did the session reference a specific PR number or branch by name? That explicit reference beats whatever is checked out now.
• Did we switch branches or worktrees during the session? If so, which branch holds the session's work?

This synthesis is the primary input. Steps 2–4 gather evidence to reconcile it with git state.

Step 2 — Gather git signals (all of them, not just current branch)

Run these in parallel:

git branch --show-current
git worktree list
git log --walk-reflogs --oneline -20 HEAD          # branches visited recently
git log --oneline -10 --all --source               # commits across all branches
git status --short                                 # uncommitted work on current branch
basename $(git remote get-url origin) .git

If the session mentioned a specific PR/branch not on this checkout, also check it directly:

gh pr view <number> --json number,title,headRefName
gh pr list --head <branch> --json number,title --limit 1

Step 3 — Reconcile: does the current branch match the session's work?

Compare the Step 1 synthesis against the Step 2 signals. One of these is true:

A. Match — current branch and its PR (if any) reflect the session's work. → Use DESCRIPTION - REPO#PR - BRANCH.

B. Mismatch (the common failure mode) — current branch is unrelated; real work was elsewhere. Signs of mismatch:

• No commits on current branch during this session, but the conversation shipped/investigated something specific.
• Session explicitly referenced a different PR/branch by name or number.
• reflog shows we switched away from the work branch recently.
• Files discussed in the session don't match recent diffs on current branch.

When mismatched, do not silently take the current branch. Choose one:

• If the session's real work branch is identifiable (from conversation or reflog), name with that branch and its PR.
• If the session was investigative (no branch is a natural home), drop the branch/PR entirely and use DESCRIPTION alone.
• If uncertain, output the name you believe is correct and a one-line note explaining the mismatch so the user can override.

C. No git context — not in a repo, or session spanned unrelated repos. → Use DESCRIPTION alone.

Step 4 — Generate a 3–4 word description

• Primary source: your Step 1 synthesis of what the session actually did.
• Secondary: PR title and commit messages of the branch you selected in Step 3, not necessarily the current one.
• Capture the essence, not the mechanics. Prefer outcome/topic over action verbs when investigative.
• Examples: AUTH FLOW REFACTOR, FIX STALE CACHE BUG, DEXS SWAP PAIRS DEDUP DIAGNOSIS

Step 5 — Assemble and output

• Matched branch/PR: DESCRIPTION - REPO#NUMBER - BRANCH
• Matched branch, no PR: DESCRIPTION - BRANCH
• Investigative / mismatch with no natural branch: DESCRIPTION

All caps. Output as:

/rename DESCRIPTION - REPO#NUMBER - BRANCH

If you detected a mismatch in Step 3, append one short note after the command explaining what you chose and why — so the user can correct you in one turn instead of getting a wrong name silently.

Examples

Matched:

/rename AUTH FLOW REFACTOR - HUNTRESS#53 - FEAT/AUTH-REDESIGN

Investigative, current branch unrelated:

/rename DEXS SWAP PAIRS DEDUP DIAGNOSIS
Note: current branch FEAT/NATIVE-TRANSFERS-P2P-CLASSIFICATION (PR #3769) is unrelated to this session's work — dropped branch/PR from the name.

Session ended on wrong branch after context switch:

/rename FIX STALE CACHE BUG - DBT#3443 - FIX/CACHE-INVALIDATION
Note: HEAD is on main, but this session's work landed on fix/cache-invalidation (PR #3443) per reflog — named by the work branch, not HEAD.

========================================

Migration

Consolidated from legacy skills. Pick the mode/lens based on intent.