specialist-handoff

Specialist Handoff

Purpose

Before every normal terminal response, write one immutable project-local record of what this specialist inspected, did, produced, could not resolve, and recommends next. The chat response wakes the caller; the Markdown file lets the caller verify the work without reconstructing it from transcript prose.

This is an artifact contract, not runtime state. Pi session JSONL and the hidden <agent_status> plus <agent_handoff> notification remain authoritative for runtime completion, Error, Stop, and continuation.

When To Apply

The immutable handoff and terminal template apply to actual specialist children, not the user-facing Research Assistant. In single-Agent mode the Research Assistant may use the long-document recovery recipe below, but gives a natural user-facing result without creating a specialist handoff for itself.

Apply this Skill to every normally terminating Search, Experiment, Writing, Figures, or Review run, including:

• complete, partial, and blocked outcomes;
• a fresh child run;
• every turn that continues a completed agent id.

A hard runtime Error or external interruption may prevent file creation. Never invent a handoff for work the specialist did not complete or observe.

Long Documents And Interrupted Writes

Apply this recipe before generating a long report, manuscript, or handoff. A complete draft is required before publication; it need not be generated in one tool call. Context-window capacity is not an output-token or time budget.

1. Establish the section order. Create a unique hidden .parts-<role>-<UUID>/ directory beside the intended draft, within the role's authorized artifact root. Review's report pieces belong under reviews/; manuscript pieces under manuscript/. Record the directory and ordered filenames in working notes.
2. Use one write call per small section, for example 01-scope.md, then 02-findings.md. Split a long section further. Wait for each successful result and inspect the saved section before moving on; keep calls comfortably below the model's output limit. Do not put all sections into one tool batch or one giant shell command. write replaces a file, never appends.
3. After interruption, inspect the exact attempted file and confirmed pieces. A streamed path or prose announcement is not execution evidence. Preserve completed pieces; regenerate only missing or incomplete pieces. A read error other than confirmed absence is a blocker to resolve, not permission to overwrite. Never blindly append a retry or retransmit the whole document.
4. Read the pieces and check required sections, findings, evidence locators and ordering. Assemble an explicit ordered list, not a wildcard, locally into a fresh unique draft. This short Python recipe reads every piece before opening the destination, retains pieces on failure, and refuses to overwrite a draft: