Enhance /handoff-context with save-session structural patterns

[TechNickAI]

Summary

• Pulls 7 structural improvements from affaan-m/everything-claude-code's save-session command into our /handoff-context — same ephemeral clipboard purpose, richer captured content.
• Forces the LLM to be honest about kinds of information: what's confirmed vs hand-waved, what failed vs untried, what's decided vs open.
• Bumps plugins/core/commands/handoff-context.md from v1.0.1 → v1.1.0.

What changed

Addition	Why
Evidence requirement on work_completed	Each item must pair with "confirmed by: [test passed / curl 200 / etc.]". Prevents wishful "done" claims.
Split failed_approaches + untried_approaches	Mixed into one blob previously. Different signals: don't-retry vs. maybe-try-next.
decisions_made (new)	Settled architecture calls get their own section so next session doesn't relitigate.
blockers (new)	Distinct from work_remaining — those are doable, these aren't yet.
files table	Scannable | File | Status | Notes | instead of prose, with Complete / In Progress / Broken / Not Started.
exact_next_step (new)	ONE concrete action on resume, precise enough for zero-think restart. Complements priority-ordered recommendations.
honesty-requirement section	"Write 'N/A' rather than skip" — a missing tag is indistinguishable from a forgotten section.

What intentionally did NOT change

• Still silent/no-prompt ("execute immediately")
• Still writes to /tmp/context_handoff_[timestamp].md
• Still copies to clipboard with pbcopy
• Still XML-tagged for LLM parsing

Test plan

• Run /handoff-context on an in-progress session, paste into a fresh session, verify the new Claude instance can continue without additional context
• Verify exact_next_step precision — resuming should require zero thinking
• Confirm empty sections get filled with "N/A" rather than omitted
• Confirm clipboard copy still works on macOS

🤖 Generated with Claude Code

[claude]

Code Review — /handoff-context v1.1.0

Overview

This PR pulls 7 structural improvements into /handoff-context, making context handoffs more honest, specific, and actionable. The core additions — evidence requirements on completed work, split failed/untried approaches, decisions_made, blockers, files table, and exact_next_step — are all genuinely useful and well-motivated.

---

Strengths

• Evidence requirement on work_completed is the standout addition. "Confirmed by: test passed / curl returned 200" prevents wishful-done claims and forces the LLM to distinguish confirmed from assumed.
• failed_approaches vs untried_approaches split provides two distinct signals: don't-retry vs. maybe-try-next. This is a meaningful semantic improvement over a single blob.
• decisions_made section prevents relitigating settled architectural calls across sessions — high value for long-running tasks.
• honesty-requirement section with the "N/A rather than skip" convention is pragmatic. A missing tag is ambiguous; an explicit <blockers>None</blockers> is a positive signal.
• exact_next_step gives zero-friction session resumption — one concrete action, precise enough to start without thinking.

---

Issues and Suggestions

1. Closing tag placement inconsistency

Some sections close their tag inline with the last bullet, while others use a separate line. This inconsistency could affect how an LLM parses or formats the output:

<!-- Inline close (current) -->
- [thing that works] — confirmed by: [specific evidence] </work_completed>

<!-- vs. separate line (current) -->
</recommendations>
</context_handoff>

Suggest making all closing tags consistent — either all inline or all on their own line. Separate lines are easier to read and less likely to get lost.

2. <blockers> section lacks bullet list template

Every other section with list content provides a bullet example:

- [decision] — reason: [why this over alternatives]

But <blockers> only has prose description with no template bullet. This inconsistency may cause the LLM to format it differently from other sections. Suggest adding:

- [blocker] — waiting on: [who/what] — unblocked when: [condition]

3. <current_state> section was removed without a replacement

The original had:

<current_state> [Describe exact state of deliverables and system] </current_state>

The <files> table captures file-level status well, but system-level state (services running, DB migrations applied, feature flags set, env vars configured) has no home now. Consider whether <critical_context> is meant to absorb this, and if so, make that explicit in the description.

4. pbcopy is macOS-only (pre-existing, worth flagging)

The test plan notes "Confirm clipboard copy still works on macOS" — this is still macOS-only with no Linux/WSL fallback. This was pre-existing, but given the PR touches <implementation>, it's a good opportunity to add a fallback:

pbcopy < /tmp/context_handoff_[timestamp].md 2>/dev/null || \
  xclip -selection clipboard < /tmp/context_handoff_[timestamp].md 2>/dev/null || \
  xsel --clipboard --input < /tmp/context_handoff_[timestamp].md 2>/dev/null || \
  echo "Clipboard copy not available on this platform"

---

Minor Notes

• Version bump 1.0.1 → 1.1.0 is correct semver for additive, backwards-compatible changes.
• Removal of "include failed attempts" from quality-guidelines is intentional and appropriate — it's now handled by dedicated sections.
• Long unwrapped line in <blockers> description is inconsistent with the rest of the diff's formatting style.

---

Summary

The structural additions are solid and the motivations are well-reasoned. The main asks are: fix closing tag consistency, add a bullet template to <blockers>, and clarify what replaces <current_state>. The macOS clipboard issue is a nice-to-fix if there's appetite.

Verdict: Approve with minor suggestions — the improvements are clearly net-positive for session continuity.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 1ed35e3ba8

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Keep attempted-but-unverified work out of untried bucket

The instruction to move any work_completed item without evidence into untried_approaches causes factual misclassification: work that was already attempted (but not yet verified) will be labeled as “not yet attempted,” which can make the next session repeat work or miss partially implemented changes. This also conflicts with the later definition of untried_approaches as ideas that have not been attempted, so the handoff schema can become internally inconsistent.

Useful? React with 👍 / 👎.

[TechNickAI]

Fixed in 104dc4f. Changed the instruction to route unverified items to work_remaining as 'Attempted, unconfirmed: [what was tried and why verification was unclear]'. That preserves the semantic distinction: work_remaining = needs doing (including partially attempted), untried_approaches = never attempted.

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 1ed35e3. Configure here.}

[TechNickAI]

Fixed in 104dc4f:

• Closing tag consistency: The project's global Prettier hook (~/.claude/hooks/post-tool-format.sh) runs proseWrap: always on all .md writes, which collapses short content + closing tag onto one line. This is a pre-existing Prettier config behavior — the tags are all present and structurally correct, just inline. Dropped the markdown language specifier from the code fence to reduce formatting interference, but Prettier still reflowes inside the block. Claude reads the template correctly either way.
• <blockers> bullet template: Added - [blocker] — waiting on: [who/what] — unblocked when: [condition]
• <current_state> gap: Restored system-state guidance inside <critical_context> — now explicitly mentions services running/broken, migrations applied, feature flags, env vars required.
• pbcopy macOS-only: Pre-existing, untouched in this PR. Out of scope — adding Linux clipboard fallbacks would need testing. Declining.

[claude]

Follow-up Review — after 104dc4f fixes

The previous review covered the main concerns well and the author's fixes in 104dc4f are solid. Here's a clean read of the current state.

---

Fixes confirmed good

• <blockers> bullet template added (- [blocker] — waiting on: [who/what] — unblocked when: [condition]) ✅
• <critical_context> system-state gap closed — now explicitly mentions services running/broken, migrations applied, feature flags, env vars ✅
• Closing tag Prettier explanation is reasonable — the tags are structurally present; Prettier's proseWrap: always reflowing them inline is a known behavior ✅

---

Two remaining nits

1. <exact_next_step> example is too framework-specific

The current example:

"In app/api/auth/login/route.ts line 42, set the JWT as httpOnly cookie via cookies().set(...), then curl the endpoint..."

cookies().set(...) is Next.js App Router API. For a general-purpose cross-project tool, a more neutral example (e.g., one that shows the file + line + action + verification pattern without a framework-specific call) would be more instructive for non-web sessions.

2. <recommendations> framing is slightly confusing

[Actionable next steps in priority order, as a backup to exact_next_step.]

"Backup" implies fallback/alternative, but recommendations is additive — it's broader context beyond the single next step. "Additional steps after exact_next_step, in priority order" better describes the relationship.

---

Overall

The structural improvements are a clear win. Evidence-backed work_completed, the failed vs untried split, decisions_made, and exact_next_step all solve real problems that cause context loss across sessions. The additions are well-motivated and the honesty-requirement section is a nice meta-layer.

Both nits above are low-priority — the command will work correctly as-is. Ready to merge.