From 1ed35e3ba801a42085e11cc2b914e0c3873ba7fd Mon Sep 17 00:00:00 2001 From: Nick Sullivan Date: Tue, 21 Apr 2026 10:06:53 -0500 Subject: [PATCH 1/2] =?UTF-8?q?=E2=9C=A8=20Enhance=20handoff-context=20wit?= =?UTF-8?q?h=20save-session=20structural=20patterns?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Pulls the best ideas from affaan-m/everything-claude-code's save-session command to make handoffs more useful to the next session: - Evidence requirement on work_completed prevents hand-waved "done" status - Split attempted_approaches into failed_approaches + untried_approaches (different signals: don't-retry vs. maybe-try-next) - Dedicated decisions_made section so settled calls aren't relitigated - Dedicated blockers section distinct from work_remaining - Files as scannable table with Complete/In Progress/Broken/Not Started - Singular exact_next_step alongside priority-ordered recommendations - Honesty requirement: write "N/A" rather than skip sections silently Bumps version 1.0.1 -> 1.1.0. Keeps ephemeral /tmp + clipboard + XML structure intact; only the captured content expands. Co-Authored-By: Claude Opus 4.7 --- plugins/core/commands/handoff-context.md | 84 +++++++++++++++++++----- 1 file changed, 69 insertions(+), 15 deletions(-) diff --git a/plugins/core/commands/handoff-context.md b/plugins/core/commands/handoff-context.md index aad143d..2468866 100644 --- a/plugins/core/commands/handoff-context.md +++ b/plugins/core/commands/handoff-context.md @@ -1,7 +1,7 @@ --- # prettier-ignore description: "Generate context handoff and copy to clipboard for new session - preserves decisions, progress, and next steps across conversations" -version: 1.0.1 +version: 1.1.0 --- # Handoff Context @@ -20,31 +20,85 @@ Do not ask for permission - execute immediately. # Context Handoff [State the original, specific request or task] - [List everything successfully accomplished with file -paths and line numbers] [Detail work that still needs -to be done with priorities] [Document -approaches that didn't work and why] -[Preserve essential technical, project, and business context] - [Describe exact state of deliverables and system] - [Provide actionable next steps in priority order] - + + + [Architecture choices, tradeoffs accepted, approaches chosen — with the +reason each was picked over alternatives. Prevents the next session from relitigating +settled calls.] + +- [decision] — reason: [why this over alternatives] + + [Every item here MUST include evidence. "Confirmed by: test passed / +curl returned 200 / visible in Supabase / Postman response attached." Without evidence, +move the item to untried_approaches.] + +- [thing that works] — confirmed by: [specific evidence] + + +[Every file touched. Table format for scannability.] +| File | Status | Notes | +| ----------------- | ------------- | -------------------------- | +| `path/to/file.ts` | Complete | [what it does] | +| `path/to/file.ts` | In Progress | [what's done, what's left] | +| `path/to/file.ts` | Broken | [what's wrong] | +| `path/to/file.ts` | Not Started | [planned but not touched] | + + + [Work that still needs to be done, in priority order. Distinct from +blockers (these are doable now).] + + [Approaches tried that did NOT work. Pair each with the EXACT +failure reason so the next session does not retry blindly. "Threw X error because Y" is +useful; "didn't work" is not.] + +- [approach tried] — failed because: [exact reason / error message] + [Promising ideas that have NOT yet been attempted. Distinct from +failed — these are still open. Be specific enough that the next session knows exactly +what to try.] + +- [approach / idea] + + +[Unresolved external dependencies, open questions waiting on answers, things blocked on someone/something outside the session. Distinct from work_remaining (those are doable; these aren't yet).] + + + [Essential technical, project, and business context the next session +needs but can't derive from the code. Git branch, env state, related PR numbers, +stakeholder constraints, time-sensitive notes.] + + [The ONE most important action to take on resume. Precise enough that +starting requires zero thinking. Singular and concrete, e.g., "In +app/api/auth/login/route.ts line 42, set the JWT as httpOnly cookie via +cookies().set(...), then curl the endpoint to verify Set-Cookie header is present."] + + + +[Actionable next steps in priority order, as a backup to exact_next_step.] + + ``` + +Write "N/A" or "None" in sections that genuinely have no content — incomplete is worse than honest empty. Skipping a section is indistinguishable from forgetting to fill it, which leaves the next session guessing. An empty `None` is a positive signal; a missing `` tag is ambiguous. + +If `work_completed` has no evidence-backed items yet, write "Nothing confirmed working +yet — all approaches still in progress or untested." + Get timestamp with `date +%s`, use Write tool to save to `/tmp/context_handoff_[timestamp].md`, run `pbcopy < /tmp/context_handoff_[timestamp].md`, show confirmation. -Why Write tool: Avoids git hooks, no escaping issues, faster execution, prevents collisions. - +Why Write tool: Avoids git hooks, no escaping issues, faster execution, prevents +collisions. For clean copy/paste: Start with `# Context Handoff`, end with ``, no preambles or summaries. -For comprehensive documentation: Include file paths with line numbers, document all work including minor changes, include failed attempts, preserve error messages and stack traces, note time-sensitive information, include git status and branch info. - +For comprehensive documentation: Include file paths with line numbers, document all work +including minor changes, preserve error messages and stack traces verbatim, note +time-sensitive information, include git status and branch info. -Handoff should be immediately pasteable into new Claude conversation. New Claude instance should be able to continue work without additional context. +Handoff should be immediately pasteable into new Claude conversation. New Claude instance should be able to continue work without additional context — and should know which approaches to avoid retrying, which decisions are settled, and the single next step to take. -``` From 104dc4f880162ebd412df3e131eb20a480287f85 Mon Sep 17 00:00:00 2001 From: Nick Sullivan Date: Tue, 21 Apr 2026 10:14:30 -0500 Subject: [PATCH 2/2] =?UTF-8?q?=F0=9F=90=9B=20Fix=20four=20bot-review=20is?= =?UTF-8?q?sues=20in=20handoff-context?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Reroute unverified work_completed items to work_remaining instead of untried_approaches (they were attempted, not untried — both Codex and Cursor caught this contradiction) - Add bullet template to blockers section for consistent formatting - Restore system-state guidance in critical_context (services, migrations, feature flags — Cursor + Claude both flagged the current_state gap) - Drop markdown language tag from code block to reduce Prettier interference with template structure Co-Authored-By: Claude Opus 4.7 --- plugins/core/commands/handoff-context.md | 59 +++++++++++++++++------- 1 file changed, 42 insertions(+), 17 deletions(-) diff --git a/plugins/core/commands/handoff-context.md b/plugins/core/commands/handoff-context.md index 2468866..a4c4945 100644 --- a/plugins/core/commands/handoff-context.md +++ b/plugins/core/commands/handoff-context.md @@ -7,20 +7,23 @@ version: 1.1.0 # Handoff Context -Generate a comprehensive context handoff for the current conversation that can be copied and pasted to continue work in a new session. +Generate a comprehensive context handoff for the current conversation that can be copied +and pasted to continue work in a new session. -Create handoff following the XML-structured format, save to timestamped temp file, copy to clipboard automatically. Show brief confirmation: `📋 Copied to clipboard` +Create handoff following the XML-structured format, save to timestamped temp file, copy +to clipboard automatically. Show brief confirmation: `📋 Copied to clipboard` Do not ask for permission - execute immediately. -```markdown +``` # Context Handoff - [State the original, specific request or task] - + + + [State the original, specific request or task] [Architecture choices, tradeoffs accepted, approaches chosen — with the reason each was picked over alternatives. Prevents the next session from relitigating @@ -30,7 +33,8 @@ settled calls.] [Every item here MUST include evidence. "Confirmed by: test passed / curl returned 200 / visible in Supabase / Postman response attached." Without evidence, -move the item to untried_approaches.] +move the item to work_remaining as "Attempted, unconfirmed: [what was tried and why +verification was unclear]."] - [thing that works] — confirmed by: [specific evidence] @@ -45,7 +49,8 @@ move the item to untried_approaches.] [Work that still needs to be done, in priority order. Distinct from -blockers (these are doable now).] +blockers (these are doable now). Include "Attempted, unconfirmed: [description]" for +work that was tried but whose completion couldn't be verified.] [Approaches tried that did NOT work. Pair each with the EXACT failure reason so the next session does not retry blindly. "Threw X error because Y" is @@ -60,12 +65,17 @@ what to try.] - [approach / idea] -[Unresolved external dependencies, open questions waiting on answers, things blocked on someone/something outside the session. Distinct from work_remaining (those are doable; these aren't yet).] - +[Unresolved external dependencies, open questions waiting on answers, things blocked on +someone/something outside the session. Distinct from work_remaining (those are doable; +these aren't yet).] + +- [blocker] — waiting on: [who/what] — unblocked when: [condition] [Essential technical, project, and business context the next session needs but can't derive from the code. Git branch, env state, related PR numbers, -stakeholder constraints, time-sensitive notes.] +stakeholder constraints, time-sensitive notes. Also include overall system state: +services running or broken, migrations applied, feature flags set, env vars required.] + [The ONE most important action to take on resume. Precise enough that starting requires zero thinking. Singular and concrete, e.g., "In @@ -76,29 +86,44 @@ cookies().set(...), then curl the endpoint to verify Set-Cookie header is presen [Actionable next steps in priority order, as a backup to exact_next_step.] + + ``` -Write "N/A" or "None" in sections that genuinely have no content — incomplete is worse than honest empty. Skipping a section is indistinguishable from forgetting to fill it, which leaves the next session guessing. An empty `None` is a positive signal; a missing `` tag is ambiguous. +Write "N/A" or "None" in sections that genuinely have no content — incomplete is worse +than honest empty. Skipping a section is indistinguishable from forgetting to fill it, +which leaves the next session guessing. An empty `None` is a +positive signal; a missing `` tag is ambiguous. If `work_completed` has no evidence-backed items yet, write "Nothing confirmed working -yet — all approaches still in progress or untested." +yet — all approaches still in progress or untested." + -Get timestamp with `date +%s`, use Write tool to save to `/tmp/context_handoff_[timestamp].md`, run `pbcopy < /tmp/context_handoff_[timestamp].md`, show confirmation. +Get timestamp with `date +%s`, use Write tool to save to +`/tmp/context_handoff_[timestamp].md`, run +`pbcopy < /tmp/context_handoff_[timestamp].md`, show confirmation. Why Write tool: Avoids git hooks, no escaping issues, faster execution, prevents -collisions. +collisions. + -For clean copy/paste: Start with `# Context Handoff`, end with ``, no preambles or summaries. +For clean copy/paste: Start with `# Context Handoff`, end with ``, no +preambles or summaries. For comprehensive documentation: Include file paths with line numbers, document all work including minor changes, preserve error messages and stack traces verbatim, note -time-sensitive information, include git status and branch info. +time-sensitive information, include git status and branch info. + -Handoff should be immediately pasteable into new Claude conversation. New Claude instance should be able to continue work without additional context — and should know which approaches to avoid retrying, which decisions are settled, and the single next step to take. +Handoff should be immediately pasteable into new Claude conversation. New Claude instance +should be able to continue work without additional context — and should know which +approaches to avoid retrying, which decisions are settled, and the single next step to +take. +```