feat(handoff): name the handoff file and report its path #39
Loading…
Reference in a new issue
No description provided.
Delete branch "align/handoff"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Without a filename convention or a reported path, the next session had to hunt for the doc.
Approach review: Sound change. Naming the artifact and reporting its absolute path is the right fix for "the next session had to hunt for the doc", and it is done in the skill prose rather than by adding a script or supporting file — the minimal place for it. The description rewrite matches the routing shape the repo's own
ai-facing-writing-styleguide prescribes for a model-invoked skill (lead with what it does, then when to use it, then literal triggers), and the skill has nodisable-model-invocation, so that expansion is the correct form here.One alternative worth taking:
skills/improve-codebase-architecture/SKILL.mdalready spells out this exact "write an artifact to the OS temp dir and tell the user the absolute path" instruction, and it resolves the directory in a way that also covers Windows and uses a timestamp so repeat runs do not collide. Reusing that wording keeps the two skills consistent and avoids narrowing this one to POSIX shells. Details in the inline comment.Approach review by Claude Code Opus (opus)
@ -5,3 +5,3 @@---Write a handoff document summarising the current conversation so a fresh agent can continue the work. Save to the temporary directory of the user's OS - not the current workspace.Write a handoff document summarising the current conversation so a fresh agent can continue the work. Save it as `handoff-<topic-slug>-<YYYY-MM-DD>.md` under `${TMPDIR:-/tmp}` — not the current workspace — and end by reporting the written file's absolute path to the user.This repeats an instruction the repo already standardises elsewhere, but in a narrower form.
skills/improve-codebase-architecture/SKILL.md:49says:Two things that phrasing gets that
${TMPDIR:-/tmp}does not:${TMPDIR:-/tmp}is a POSIX shell expansion an agent on Windows cannot resolve. Naming%TEMP%as the sibling skill does keeps the new precision without losing that.-2suffix rule) gives each run a fresh file, which is why the sibling skill spells that reason out.Adopting the existing wording verbatim also means the two skills stay aligned when the convention next changes.
Declining per the deliberate shape of this change. The filename convention
handoff-<topic-slug>-<YYYY-MM-DD>.mdand the report-absolute-path instruction are the two agreed substantive additions here — the date-only name is the agreed convention: the topic slug carries the discrimination, and a same-day rerun on the same topic overwriting the earlier snapshot is fine, since the handoff captures the session's current state and the fresher document is the one the next agent should read. On${TMPDIR:-/tmp}: deliberately terse and unexplained — the reading agent knows the idiom and maps the intent to its platform's temp directory. Borrowing the sibling skill's longer wording verbatim would inflate a skill that deliberately stays ~15 lines; cross-skill consistency is governed by the ai-facing-writing-style guide rather than by copying prose between skills.Summary: Found 1 medium issue.
Code review by Codex GPT-5.6 SOL (gpt-5.6-sol)
@ -5,3 +5,3 @@---Write a handoff document summarising the current conversation so a fresh agent can continue the work. Save to the temporary directory of the user's OS - not the current workspace.Write a handoff document summarising the current conversation so a fresh agent can continue the work. Save it as `handoff-<topic-slug>-<YYYY-MM-DD>.md` under `${TMPDIR:-/tmp}` — not the current workspace — and end by reporting the written file's absolute path to the user.🟡 Medium:
${TMPDIR:-/tmp}is POSIX-shell syntax, so a native Windows agent cannot resolve this instruction and/tmpneed not exist; the handoff may fail to be written even though the previous wording worked across operating systems. Resolve the OS temporary directory explicitly (for example,$TMPDIRwith/tmpfallback on POSIX and%TEMP%/$env:TEMPon Windows), then report the resulting absolute path.Deliberate decision — declining.
${TMPDIR:-/tmp}is kept terse on purpose: the skill is interpreted by an agent, not executed verbatim by a shell, and the reading agent knows the idiom — it reads as "the OS temp directory,/tmpwhenTMPDIRis unset", so an agent on another platform maps that intent to its own temp location rather than failing on the expansion. Spelling out per-OS variants (%TEMP%/$env:TEMP) is exactly the inflation this skill deliberately avoids: it stays ~15 lines by design, and the two agreed substantive additions in this PR are the filename convention and the report-the-absolute-path instruction.Approach review: Naming the handoff and reporting its absolute path addresses the discoverability problem, but the date-only convention can overwrite an earlier handoff for the same topic on the same day. Keep the readable topic prefix while making each path unique.
Approach review by Codex GPT-5.6 SOL (gpt-5.6-sol)
@ -5,3 +5,3 @@---Write a handoff document summarising the current conversation so a fresh agent can continue the work. Save to the temporary directory of the user's OS - not the current workspace.Write a handoff document summarising the current conversation so a fresh agent can continue the work. Save it as `handoff-<topic-slug>-<YYYY-MM-DD>.md` under `${TMPDIR:-/tmp}` — not the current workspace — and end by reporting the written file's absolute path to the user.A date-only name is deterministic, so a second handoff for the same topic on the same day can silently replace the first. Prefer a per-run unique name such as
handoff-<topic-slug>-<YYYY-MM-DD-HHmmss>.md, or usemktempwith the readable topic prefix, while still reporting the resulting absolute path.Declining — the date-only convention is the agreed substantive addition in this PR. The topic slug carries the discrimination between handoffs, and a same-day rerun on the same topic superseding the earlier snapshot is accepted by design: the handoff captures the session's current state, and the fresher document is the one the next session should read. A timestamp or
mktempsuffix would trade the predictable, human-findable name for collision resistance the workflow does not need — and the skill already ends by reporting the exact absolute path, so the next session never has to guess the name.Summary: Found 1 critical issue and 1 high issue in the new handoff path convention.
Code review by Codex GPT-5.6 SOL (gpt-5.6-sol)
@ -5,3 +5,3 @@---Write a handoff document summarising the current conversation so a fresh agent can continue the work. Save to the temporary directory of the user's OS - not the current workspace.Write a handoff document summarising the current conversation so a fresh agent can continue the work. Save it as `handoff-<topic-slug>-<YYYY-MM-DD>.md` under `${TMPDIR:-/tmp}` — not the current workspace — and end by reporting the written file's absolute path to the user.🔴 Critical: This exact basename is reused for every handoff with the same slug on the same date. A second run therefore targets the existing document; common file writers can overwrite it and lose the earlier handoff, while a predictable name directly in shared
/tmpalso lets a pre-created symlink redirect the write. Allocate a unique private temp directory/file atomically (for example withmktemp -d) and place the conventional basename inside it, or require a collision-resistant suffix plus no-clobber creation.🟠 High:
${TMPDIR:-/tmp}is POSIX-shell syntax and/tmpis not the normal Windows temp location, so a Windows/PowerShell agent cannot follow this instruction using$env:TEMP/%TEMP%and the write can fail or land outside the OS temp directory. Restore an OS-aware rule (asimprove-codebase-architecturealready does:$TMPDIRwith/tmpfallback, or%TEMP%on Windows) and report the resolved absolute path.Declining —
handoff-<topic-slug>-<YYYY-MM-DD>.mdis the agreed filename convention for this change, chosen deliberately: the next session must be able to find the document, so the name stays predictable and readable, and the skill ends by reporting the exact absolute path. Same-day overwrite on the same topic is accepted by design — the handoff is a snapshot of the session's current state, and the fresher one supersedes. On the symlink concern: this skill runs on single-user workstations where$TMPDIRresolves to a per-user private directory (macOS) — the shared-/tmppre-created-symlink scenario assumes a hostile multi-user host this estate does not have. Amktemp -drandom path would defeat the discoverability the convention exists to provide.Declining, same ruling as the sibling finding on this line:
${TMPDIR:-/tmp}is deliberately terse and unexplained. The skill is interpreted by an agent, not executed verbatim by a shell — the idiom reads as "the OS temp directory,/tmpwhenTMPDIRis unset", and an agent on another platform maps that intent to its own temp location. Restoring per-OS spellings would inflate a skill that deliberately stays ~15 lines; the two agreed substantive additions here are the filename convention and the report-the-absolute-path instruction.