Handover

---
name: lore:handover
description: Hand work over to a later session, in two parts. Part one writes a handover note so the next session continues this one after /clear or compaction; SessionStart points the next session to the note automatically. Part two writes the handover section for work that stops before its finish point, turns follow-up work into a seed issue a fresh session can orient on cold, holds the shape of the handover section that build writes at every finish point, and the next-run offer for the follow-ups a build run filed. Use when the user says "handover", "hand over", "write a handover", before they run /clear on unfinished work, when a build run stops early, or when follow-up work surfaced and should go to a new session. Run with "/lore:handover".
user_invocable: true
---

# Handover

The skill has two parts. Run part one when this session stops and the next
session in this directory continues it. Run part two when work stops before
its finish point, when `build` reaches a finish point, or when follow-up work
should go to a new session. When both fit, run both. At a `build` finish
point, run part two only: the handover note there is the user's to write.

# Part one: the handover note

`orient` rebuilds understanding from the repo. A handover carries what the
repo does not hold: decisions, dead ends, the next ask. SessionStart injects
the path of the note after `/clear` or compaction, and offers it in one line
on a fresh start. The next session reads the whole file. Nothing runs before `/clear`, so write the note first.

## Write the note

Draft it in these sections. Keep empty sections with "none".

```md
## Goal
What the work is for, in one or two sentences.

## Decisions
Each decision made this session, and why. Include what was rejected.

## Done
Commits, PRs, issues filed — with ids and branch names.

## In flight
Uncommitted changes, running jobs, worktree paths, branches.

## Next
The next ask, as the first thing the new session does.

## Open questions
Questions for the user that are not answered yet.

## Where to look
Files, commands and URLs the next session needs first.

## Traps
What failed and why, so the next session does not repeat it.
```

Rules:

- Run `lore style show writing-rules` first; the note follows them.
- State facts with their source: path, commit, run id, log.
- Write for a reader with no memory of this session.
- A note has no size limit: the next session reads the file. Cut history, keep state.

## Store it

Pipe the note to `lore handover write` with a quoted heredoc:

```bash
lore handover write <<'EOF'
## Goal
...
EOF
```

A new note replaces the old one for this directory. Then tell the user:

- the note is stored and the path `lore handover write` printed;
- `/clear` now starts a session that receives the note;
- `lore handover show` prints it at any time.

## Do not

- Paste the transcript or long tool output into the note.
- Write a note for another directory; the note belongs to the current one.

# Part two: the handover section and the seed issue

**Tier note:** this part runs in the main session at frontier-tier. The part is not delegated
to a subagent.

Run `lore style show writing-rules` before you write. The handover section and the seed issue
are team-facing text.

## The handover section

One `## Handover` section, in one home:

| Work | Home |
|---|---|
| `build` in `epic` mode | the epic issue body |
| `build` in `loop` mode | the wrap-up PR body |
| `build` in `issue` mode | the PR body |
| work with no PR and no epic | a seed issue (below) |

Shape:

```md
## Handover

- **Shipped:** <what merged, with the merge SHA> | nothing yet
- **Decisions:** <ADR links, one per line> | none
- **Deviations from the PRD:** <what differs and why> | none
- **Follow-ups:** <owner/repo#n, one per line> | none
- **Known limits:** <what does not work yet, where it was observed> | none
```

Work that stops before its finish point adds two lines:

```md
- **State:** <open branches, worktrees and PRs; the ledger path and its last resume line>
- **Next step:** <the exact command a fresh session runs>
```

Link to each home; do not restate an ADR or an issue. A missing fact gets `TODO:` and the
question.

## When work stops early

1. **Resolve what you can.** Run `lore workflow ledger-check` (epic: pipe the board comment into
   `lore workflow ledger-check -`). Send a feature-idea line through § A deferred feature idea.
   File each other `left` line you can through [`file-issue`](../file-issue/SKILL.md) and set it
   `filed` with `lore workflow ledger-set`. In epic mode, add
   `--board -`, pipe the board comment in, and write the printed body back to the comment; see
   [build's epic tail](../build/epic-tail.md) § 2. Leave ADR and term candidates open for the next
   session; name them under **State**.
2. **Write the handover section** into its home. With no home, write a seed issue.
3. **Write the logbook entry.** Run `lore log add --ref <ref> --text-file <file>` as
   [build's logbook.md](../build/logbook.md) says. The ref is the PR, the seed issue or
   `branch@sha`. The entry may end with a `Waiting on:` line that names the blocker.
4. **Leave the resume line.** `lore workflow ledger-add --kind resume --text "<state>" --next
   "<next ask>"` (epic: with `--path -`, pasted into the board's `## Ledger`).
5. Tell the user that `/clear` is safe, and print the next step.

## A deferred feature idea

The filing rule sends a feature idea to the roadmap, not to an issue.

- Add the item on the open branch of the work: `epic/<issue>` in `epic` mode, else the build
  branch. Run `cd <worktree> && lore roadmap add "Title" "Paragraph"` in one shell call. Commit
  the item there. Name the item under **State**.
- An idea with findings that a cold session would rediscover also gets a seed issue. Write the
  seed before the roadmap item, and end the item's paragraph with `Seed: <owner/repo#n>`.
- When no open branch carries the work, or the branch has merged, the seed issue that this
  handover writes holds the idea alone. Its **Next step** names the roadmap item, under the
  `orient` command. `to-epic` adds the item.
- Where the idea has a `left` line, set it as step 1 of § When work stops early says. The
  outcome is `approved` for a roadmap item, `filed <owner/repo#seed>` for a seed alone.

## Next run

A `build` run reaches this step after its merge. Skip the step when the run filed no follow-ups.

1. **Collect** the follow-ups: the `filed` ledger lines and the **Follow-ups** of the handover
   section. A roadmap item gets no next run; `orient` picks it up from the roadmap.
2. **Group** them. Give each group one next run:

   | Group | Next run |
   |---|---|
   | one small, clear issue | `/lore:build issue <owner/repo#n>` |
   | an epic tracker with a build order | `/lore:build epic <owner/repo#n>` |
   | related issues, or work without a shape | a seed (§ Seed issue), then `/lore:orient <owner/repo#seed>` |

3. **Offer** the next runs in the final message, one line each, with its command. The user can
   copy a command and run it after `/clear`. A seed line says that the seed is written first.
   Ask which run to start in this session.
   - On a yes: start that run. For a seed, write the seed first.
   - Silence or a no: stop. The message already holds the commands.
   - An unreachable user: put the lines in the report. Start nothing.

## Seed issue

A seed is a discussion seed, not a spec. It carries the intent and the context that is expensive
to rebuild. The new session forms the work through `orient → grilling → to-epic`. Do not slice or
decide scope here.

1. **Harvest** the follow-up work from this session: new problems, deferred ideas, loose ends,
   traps met. Take it from the context; do not interview. A deferred feature idea follows
   § A deferred feature idea.
2. **Group** the threads into seeds, one future epic each. A small, clear defect or concrete
   change needs no seed: file it as an issue. Confirm the grouping with the user.
3. **Write** each seed in the template below. Make **Findings** rich; that is the handover value.
   When a wiki note for this session exists, try `lore workflow seed-lift <note> --wiki-root
   <wiki-root>` first. On exit 0, use its `origin` and `findings` fields, and add its
   `source_note` under **Pointers**.
4. **Publish** each seed through [`file-issue`](../file-issue/SKILL.md) in caller-template mode.
   Label it `epic-seed` (create the label if missing). Link the originating epic and PRs. Do not
   edit the finished epic.

Print each seed reference and the command for the fresh session:
`/lore:orient <owner/repo#seed>`.

<seed-template>
## Intent
What we want to do next, as the seed for discussion, in domain language. Not a solution.

## Origin
Where this came from: the epic (`owner/repo#n`), merged PRs and commits, and why it surfaced.

## Findings from this session
The context a fresh session would rediscover: constraints, decisions made, dead ends, traps,
what turned out true or false.

## Open questions
What `orient` and the grilling dig into before the work takes shape.

## Pointers (starting points, may be stale)
Modules and files, docs, ADRs, `CONTEXT.md`, related issues, repos involved.

## Out of scope / deferred
What this seed leaves out.

## Next step
A fresh session starts here: `/lore:orient owner/repo#<this-seed>`.
</seed-template>