Skip to content

alirezarezvani/claude-skills / productivity/handoff/skills/session-handoff

session-handoff

Verified

Write a handoff document so a fresh session or another agent can pick up exactly where this one left off: goal, current state, decisions, next steps and the skills to load, referencing existing files instead of copying them, with secrets redacted before saving. Use whenever the user is ending a session, switching machines, running low on context, or asks for a handoff, a handoff doc, a 'pick up where we left off' summary, or to compact the conversation for next time. Saves to a location the user picks on first run (OS temp, home folder or per-project .handoff/) and can auto-load the latest handoff at the next session start.

references/handoff_prompt.md

View on GitHub
# Handoff Prompt — Mandatory Checklist for the Agent

This is the discipline that turns a free-hand summary into a faithful handoff. Walk every item before writing the doc. **No exceptions.**

The goal of the checklist is one thing only: prevent the model from free-handing a rosy summary that drops the actual blockers.

## Step 1 — Walk the conversation explicitly

For **each topic** discussed in the conversation, classify it as exactly one of:

1. **Include in State of play** — work that's done, in flight, or blocked. Reference the artifact (PR, branch, commit, file path).
2. **Log as an Open decision** — a question the next agent must answer before continuing.
3. **Drop with reason** — out of scope for the handoff. Note it inline as a comment if the decision to drop is non-obvious.

If a topic spans multiple classifications, split it. Do not merge.

> **Anti-pattern:** writing the State section by skimming the conversation top to bottom. That misses dropped threads and blocked items that came up mid-conversation.

## Step 2 — Verify each State item against an artifact

For every bullet in **State of play**, name the artifact that proves it:

- "Implemented X" → name the commit hash or PR number.
- "Tested Y" → name the test file or CI run.
- "Documented Z" → name the doc path.
- "Blocked on W" → name the issue, comment, or external party.

If you cannot name an artifact, the item is either not yet done, or it's an Open decision. Reclassify.

> **Anti-pattern:** "Implemented the new endpoint." — vague, unverifiable, and the next agent has no idea where to look.

## Step 3 — Surface every Open decision

A handoff that hides decisions makes the next session repeat work. For each decision:

- State the question in one sentence.
- List the options already considered (even if rejected).
- State which option you lean toward and why — or "no lean yet."
- Name the constraint that forces the decision (deadline, budget, dependency).

> **Anti-pattern:** "TODO: figure out caching." — gives the next agent no starting point.

## Step 4 — Pick 3-5 skills, no more

For **Skills to use**:

- Hard cap at 5.
- Each entry: skill name + one-line *why this session needs it*.
- If you find yourself listing more than 5, you haven't picked. Choose.
- If you find yourself listing fewer than 3, ask: is something obvious missing? (Often a review skill or a verifier.)

> **Anti-pattern:** listing every skill that might be tangentially useful. The reader stops reading after item 8.

## Step 5 — Artifacts as paths and URLs only

For **Artifacts**:

- Branches, PRs, issues, file paths, doc URLs.
- One line each.
- Never paste content. If the next agent needs to see the diff, they open the branch.

> **Anti-pattern:** pasting the PRD because "what if they can't access it?" If they can't access it, the link is the bug — fix that, don't duplicate.

## Step 6 — Run the redaction linter before saving

Before save, the linter scans for secrets and PII. In strict mode it blocks save until findings are resolved. Use the inline marker `<!-- handoff:allow secret -->` to whitelist a specific match if it's a false positive.

Patterns it cannot catch (do these by eye):

- Internal hostnames and IPs that aren't shaped like obvious secrets.
- Names of customers, partners, or unrelated third parties.
- Free-form leakage in narrative ("Last week Ann from FinCo asked us to…").

## Step 7 — Compare against Matt's no-duplication rule

Final pass before save:

- Does any section paste content that exists elsewhere? Replace with a link.
- Does any section narrate the conversation linearly? Compress to State + Decisions.
- Does any bullet say "the user did X"? Rewrite as the artifact (commit, message, decision).

## What "done" looks like

A handoff is done when:

1. Every State bullet has an artifact reference.
2. Every Open decision has a one-sentence question + at least one option.
3. Skills to use has between 3 and 5 entries.
4. Artifacts has only paths/URLs.
5. Redaction linter exits clean (or all findings are whitelisted with reason).
6. A fresh agent could pick up the work without reading the original conversation.

Test the last item by asking yourself: *if I close the conversation right now and a stranger opens this doc, do they know the next 30 minutes of work?* If no, go back to Step 1.
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall