Generated from cat-harness/skills/sdlc/sdlc-core/handover-report.md — do not edit here.
✎ Edit this page’s source

Handover report

An agent’s state lives in three places that do not survive it: the chat, its scratchpad, and uncommitted work in its worktree. A handover report moves the parts that matter into the repository, as a committed bean note, so the next agent starts from fact rather than from guesswork.

To produce one under time pressure, follow prepare-for-handover: it commits and pushes first, then writes this report citing the pushed SHAs.

This skill is not agent-handoff, which hands one task to a named agent in another environment. A handover report is a snapshot of everything one agent is holding, written for whoever turns up next, which may be no one in particular.

When to write one

When told a stall is likely. Write it first, before continuing any work. A report written after the stall is never written.
Before a long or risky step: a 30-minute regenerate, a big merge, a disk-heavy run.
At the end of an arc, even a successful one, if anything stays open.
When a steward or the owner asks.

Write it short and early, then update it. A 20-line report pushed now is worth more than a complete one that never lands.

Where it goes

A bean note on the bean you are working, or on its epic if you hold several:

bun run cat beans:note <bean-id> --title "handover: <role> <date>" \
  --body-file <file> --branch <your-branch>
bun run cat beans:notes          # rewrites the index; commit both files
git add -A && git commit && git push

One file per branch per bean, so two agents writing handovers never conflict (bean-coordination §”Adding to a bean — a note, not an append”). Write it in your own worktree. Some tools write into the main checkout instead; if you are a subagent, check git status there afterwards.

Push it, even onto a draft PR or a red branch. An unpushed report does not exist.

The template

Mix narrative with formal content. The tables are what a triage agent parses; the prose is what a person reads.

## Handover report: <role> (<session or agent>)

- **Session:** <session URL, or the parent session plus agent id>
- **Written:** <UTC time>, <why: stall expected / end of arc / asked>
- **Role and mandate:** <one line; the owner rulings that bound you>

### Where I'm going (current arc)
<2–4 sentences: the goal, the epic it serves, and what "done" looks like.>

### Done so far
- <outcome, with PR, commit or bean>

### Next in queue
1. <next concrete step: command, file, PR>
2. …

### In flight
| item | kind (PR / branch / bean / process run) | state | next action | owner |
|---|---|---|---|---|

### Blockers and dependencies
| blocker | waits on | since | expires / re-check |
|---|---|---|---|

### Decisions pending (owner)
- <question, with options and your recommendation, so it can be asked cold>

### Unpushed or at-risk state
- <scratchpad files, local commits, running jobs, and whether each is reproducible>

### Dispatch lines (copy-paste, one per unstarted item)
Do bean folio-assistant-<id> on branch <branch-to-create> of repo <owner>/<repo>.
Do bean folio-assistant-<id> on branch <branch-to-create> of repo <owner>/<repo>.

### How to resume
<the first three things the next agent should do, in order>

Rules

Facts with provenance. Write “CI red on abc123 (check X)”, not “CI is flaky”. Give SHAs, PR numbers and bean ids, never “the branch”.
Say what is NOT pushed. Unpushed commits, scratchpad plans and running background jobs are exactly what a stall destroys. Name each one, and say whether it can be rebuilt.
Owner rulings verbatim, with the date. A ruling paraphrased in a handover becomes a different ruling by the second handover.
Never put secrets in it. Name secrets, never give their values.
Blocks follow bean-blocking: what it waits on, since when, and when to re-check, so a stale block can be told from a live one.
Update in place. Re-run beans:note on the same branch and bean, which gives the same file. Do not append a second report.
Every unstarted item gets a DISPATCH LINE, in one fixed sentence.
```
Do bean folio-assistant-<id> on branch <branch-to-create> of repo <owner>/<repo>.
```
The owner asked for exactly this shape, twice, 2026-10-03: “for the agent, i mean something like "Do bean folio-assistant-tlk2 on branch claude/blissful-ride-c2f26u-rename-script of repo litlfred/folio-assistant."” — and then “make sure those short dispatch is part of the handover skills, so it is used again”. It is a format, not a suggestion: write it verbatim with the three slots filled.
Why one sentence, and why these three slots. A dispatch is read by somebody with no context — the owner pasting it into a new session, or a steward handing out work. The three slots are the minimum that makes it actionable alone: the BEAN says what and carries its own Done-when, the BRANCH stops two agents landing on one ref, and the REPO is required because an agent’s session may be scoped to a different one. Drop any slot and the recipient has to come back and ask.
Three rules measured the same day:
- Name a branch that does not exist yet, and say so. A line naming a branch that was already finished sent an agent to a dead ref, which it reported back as “that branch does not exist and the bean is already completed” — a whole round lost to a stale line.
- One bean per line. Not a theme, not “the three remaining X”. The bean is what carries the Done-when, and a line that names a theme hands over a judgement instead of a task.
- Order them, and say what is ordered. If a line must follow another, write that above the block — not inside the sentence, which stays fixed. A handover that lists four dispatchable beans with a hidden prerequisite is worse than one that lists the one that is ready.
dispatch-agent governs what happens AFTER the line is sent — the progress contract and the heartbeat. This rule is only about writing the line so the work can be handed on at all.

Processes that run this skill

process	step(s) that name it
Stalled-agent triage: collect handovers, consolidate themes, recommend, re-route	Collect or reconstruct a handover report per agent