Skip to content

fix: deliver the handoff brief to the slash commands - #24

Merged
d6veteran merged 1 commit into
mainfrom
claude/handoff-brief-reaches-commands
Jul 29, 2026
Merged

fix: deliver the handoff brief to the slash commands#24
d6veteran merged 1 commit into
mainfrom
claude/handoff-brief-reaches-commands

Conversation

@d6veteran

Copy link
Copy Markdown
Collaborator

Session handoff briefing was listed as aspirational. It was already built. Planning this turned it inside out.

175 tests (was 170). shellcheck clean.

What was actually there

Before
Profiles defining a ### Handoff Brief 17 / 17
Generated subagents carrying it 17 / 17
Generated /name slash commands carrying it 0 / 17
Coordinator profiles instructing the persona to produce one 2 / 2

Byte-identical opening and closing stems across all seventeen. Three DEVLOG entries treat "3 behaviors + handoff" as a structural invariant. The ROADMAP entry was written by paraphrasing the already-shipped robin.md text.

The defect, and why it landed on the worst possible surface

### Handoff Brief sat inside ## Required Interactive Behaviors, which strip_interactive_behaviors excises from every slash command.

profiles/coordinator.md:126 tells the user, at the exact moment of a handoff:

"We're moving into [domain] territory — want to switch to [Name]? Run /[name] right here to switch for this session, no restart needed."

and :128 then instructs the coordinator to ask that persona for a Handoff Brief.

The asker had the instruction. The answerer, on the path the coordinator itself recommends, had never been told what a Handoff Brief is. It would have to improvise from the coordinator's one-line description.

The fix

### Handoff Brief becomes ## Handoff Brief. This codifies what the structure already implied — the section was deliberately left unnumbered while its siblings are ### 1., ### 2., ### 3.

The stripper's end marker moves from ## Signature Question to ## Handoff Brief, so the excised range ends one section earlier. Position in the profile is unchanged.

Generator guard added. The generator now aborts on a profile with no ## Handoff Brief, matching the existing ## Greeting guard. Not ceremony: the stripper resets skip on that marker, so a profile without it would silently drop every later section from the slash command. The same latent failure mode exists today with ## Signature Question and goes unnoticed only because all seventeen happen to have one.

The drift test asserted the gap as correct, since its awk mirrors the stripper. Both moved in lockstep.

Parallel sessions had the same shape of gap

A session prompt carried Persona, Task, File scope and nothing about what had already been decided, so each session re-derived context it was never given. The /parallel template also seeds sessions with /akira — the same stripped surface.

Both coordinator profiles and commands/parallel.md gain a fourth Context field. A finished session with dependents writes a Handoff Brief that becomes the downstream session's Context.

Prompt-only, per your call: no new files, no stored state, no CLI surface. That also keeps it clear of the shared-state locking the branch index needed.

Verification

  • All five new tests fail on the previous tree. One removes the section from a profile in a throwaway copy and requires the generator to refuse, so the guard is proven rather than assumed.
  • Agents changed by exactly one heading level per file and nothing else — verified by reducing the whole 17-file diff to its unique change shapes, which are ### Handoff Brief## Handoff Brief and nothing more.
  • All four delivery surfaces confirmed end to end: profiles 17/17, agents 17/17, commands 17/17, and cmd_use carrying it into the global pin.

Roadmap

Moved from aspirational to shipped. That empties the aspirational list, since the other two items were retired in #23, so it now reads as an invitation to open an issue rather than an empty heading. Existing dated revision rows unchanged.


Generated by Claude Code

Session handoff briefing was listed as aspirational. It was not. All seventeen
personas have carried a Handoff Brief section since they were written, with
byte-identical opening and closing stems, and both coordinator profiles instruct
the coordinator to ask the outgoing persona for one at a switch. Three DEVLOG
entries treat "3 behaviors + handoff" as a structural invariant. The roadmap
entry was written by paraphrasing the shipped robin.md text.

The defect was delivery, and it landed on the worst surface. The section sat
inside Required Interactive Behaviors, which strip_interactive_behaviors excises
from every slash command, so 0 of 17 commands carried it against 17 of 17
agents. coordinator.md tells the user to run /<name> at the exact moment of a
handoff and then instructs the coordinator to ask that persona for a brief. The
asker had the instruction; the answerer, on the recommended path, did not.

The section is now a top-level ## Handoff Brief, which codifies what the
structure already implied: it was deliberately left unnumbered while its
siblings are ### 1., ### 2., ### 3. The stripper's end marker moves from
## Signature Question to ## Handoff Brief, so the excised range ends one section
earlier and the brief survives. Position in the profile is unchanged.

The generator now aborts on a profile with no ## Handoff Brief, matching the
existing ## Greeting guard. This is not ceremony: the stripper resets its skip
flag on that marker, so a profile without it would silently drop every later
section from the slash command. The same failure mode exists today with
## Signature Question and goes unnoticed only because all seventeen have one.

The commands drift test asserted the absence as correct, since its awk mirrors
the stripper. Both moved together.

Parallel sessions had the same shape of gap. A session prompt carried Persona,
Task, and File scope, and nothing about what had already been decided, so each
session re-derived context it was never given. Both coordinator profiles and
commands/parallel.md gain a fourth Context field, and a finished session with
dependents now writes a Handoff Brief that becomes the downstream session's
Context. Prompt-only: no new files, no stored state, no CLI surface.

Five tests added, all five failing on the previous tree. One of them removes the
section from a profile in a throwaway copy and requires the generator to refuse,
so the guard is proven rather than assumed.

ROADMAP and README move the entry from aspirational to shipped. That empties the
aspirational list, which now reads as an invitation to open an issue rather than
an empty heading. Existing dated revision rows are unchanged.

175 tests, up from 170. shellcheck clean. Agents changed by exactly one heading
level per file and nothing else.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019j5DHEZsoeCGRueTbNLuTb
@d6veteran
d6veteran marked this pull request as ready for review July 29, 2026 15:39
@d6veteran
d6veteran merged commit d58f2db into main Jul 29, 2026
3 checks passed
@d6veteran
d6veteran deleted the claude/handoff-brief-reaches-commands branch July 30, 2026 22:26
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants