alirezarezvani/claude-skills / productivity/handoff/skills/session-handoff
session-handoff
VerifiedWrite 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.
| File | Kind | Size |
|---|---|---|
| README.md | markdown | 1.2 KB |
| SKILL.md | skill md | 9.6 KB |
| assets/example_handoff.md | markdown | 2.3 KB |
| references/configuration.md | markdown | 5.3 KB |
| references/deduplication_discipline.md | markdown | 4.5 KB |
| references/handoff_prompt.md | markdown | 4.3 KB |
| references/handoff_structure.md | markdown | 4.5 KB |
| references/redaction_checklist.md | markdown | 4.6 KB |
| scripts/cleanup.py | script | 5.1 KB |
| scripts/config_loader.py | script | 4.9 KB |
| scripts/handoff_self_check.py | script | 13.1 KB |
| scripts/handoff_template_generator.py | script | 7.9 KB |
| scripts/redaction_linter.py | script | 9.2 KB |
| scripts/setup.py | script | 9.6 KB |
| scripts/skill_recommender.py | script | 8.0 KB |
references/deduplication_discipline.md
View on GitHub# Deduplication Discipline
Matt's core rule, made operational:
> Do not duplicate content already captured in other artifacts (PRDs, plans, ADRs, issues, commits, diffs). Reference them by path or URL instead.
This document turns that rule into a list of concrete *do-this-not-that* pairs the agent applies before saving.
## Why this matters
A handoff that duplicates artifacts goes stale the moment the artifact updates. A handoff that references artifacts stays correct as long as the references resolve. The reader follows links to canonical sources; they don't trust the handoff to be the source of truth.
A second reason: duplication grows the file, which grows the next session's context window, which costs tokens and attention. Every paragraph that isn't a link is a paragraph the next agent has to read.
## The do-this-not-that pairs
### 1. The diff
| Don't | Do |
|---|---|
| Paste the diff into the handoff. | Reference the branch (`feature/foo`) or PR (`#123`). |
| List every file you touched. | "Touched 14 files across `src/auth/` and `tests/auth/` — see PR for full list." |
| Quote a 40-line code block to "preserve context." | Link to the file path + line range: `src/auth/login.ts:42-87`. |
### 2. The PRD
| Don't | Do |
|---|---|
| Retype the PRD as bullet points. | Link to the PRD path. |
| Summarise the PRD because "the next agent might not have access." | If they don't have access, the access is the bug — fix that. |
| Paraphrase the user stories. | Reference them by ID. |
### 3. The commit message
| Don't | Do |
|---|---|
| "I committed a fix for the redaction edge case." | "Fixed redaction edge case — `a1b2c3d`." |
| Narrate the commits in order. | "5 commits on `feature/foo`. See `git log feature/foo`." |
### 4. The issue / ticket
| Don't | Do |
|---|---|
| Restate the bug from the issue body. | "See issue #456." |
| Copy the acceptance criteria. | "Acceptance criteria in #456." |
| Quote the latest comment. | "Latest comment from @teammate at issue #456." |
### 5. The conversation itself
| Don't | Do |
|---|---|
| Recap the conversation chronologically. | Compress to State of play + Open decisions. |
| List every question the user asked. | Surface only the questions that became decisions. |
| Include the back-and-forth that led to a conclusion. | Just the conclusion. |
### 6. Suggested skills
| Don't | Do |
|---|---|
| List 20 skills "in case any are useful." | Pick 3-5 and say *why each*. |
| Recommend a skill without explaining the link to the goal. | "code-review — to review the PR before opening it." |
| Re-explain what each skill does. | The next agent reads the SKILL.md if needed. |
### 7. Artifacts
| Don't | Do |
|---|---|
| Embed the full PR description. | Link to the PR. |
| Quote the relevant lines from an ADR. | Link to the ADR path + section. |
| Paste a CI log to show what failed. | Link to the failing CI run + one-line summary ("type-check failed at L42 of `foo.ts`"). |
## What survives the rule
Some content must live inline in the handoff because it doesn't exist anywhere else:
- **Open decisions and your lean** — these are *new* information the conversation produced. Inline them.
- **State of play prose** — the synthesis itself. The artifacts exist; the synthesis is the handoff.
- **Forcing constraints** — "Deadline: EOD." These often live only in the conversation.
- **Sub-text and known-unknowns** — "Reviewer hates verbose tests, so keep new tests short." This shapes the work and isn't in any artifact.
If you're unsure, ask: *does removing this and replacing with a link lose any information?* If no, replace it. If yes, keep the inline content.
## Anti-pattern: defensive duplication
Defensive duplication looks like: *"I'll paste the diff inline too, just in case the link breaks."*
Resist. If links can break, that's a separate problem — fix the link, don't duplicate. Defensive duplication causes the second failure mode this rule is designed to prevent: a handoff that contradicts the artifact it duplicates.
## Sources
- Matt Pocock, *Handoff skill* (MIT) — the original rule.
- Karpathy, *Software 3.0 talk* (2025) — context engineering: every duplicated paragraph is a future contradiction.
- Cory Doctorow, *Writing for the machine that reads* (essay) — references over copies, durably.
- Google SRE Workbook — postmortem hygiene: link to evidence, do not paraphrase it.
- Atlassian, *Confluence handoff template guide* — the same discipline at organizational scale.
- Edward Tufte, *Beautiful Evidence* — the principle of *information density*: one source of truth per fact.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 472k | Updated | Claude CodeCodex | Verified | Install |
| 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: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |