keel-handover

/keel-handover — write the session block

Add a new session block to the TOP of HANDOVER.md's "Session blocks" section (rules.md §1.4). Newest first; never edit past blocks. Write the block in ENGLISH even on a non-English project (§9.31: HANDOVER/LESSONS are machine-read and @-imported every session — EN is the cheaper token surface); TASKS/PLAN/reports lines you touch stay in the project language, and the user's verbatim words may stay quoted as-is.

Steps:

1. Read the current HANDOVER.md. If it already has 3 blocks (or exceeds ~150 lines), run /keel-distill first to rotate the oldest block out (critical facts → LESSONS.md, raw block → docs/handover-archive.md).

2. Write this session's block: ### <YYYY-MM-DD HH:MM> — @<git user.name> — <one-line status> (time = when the block was first created; the @<git user.name> attributes the session's author so multi-user handovers stay legible — read it from git config user.name; single-user projects still get it, at zero cost). One block per SESSION, not per day: if THIS session already wrote a block (a mid-session handover, or /keel-compact re-running this), UPDATE that block in place — keep its original HH:MM. A NEW session always adds a NEW block, even on the same day — same-day sessions must stay distinguishable. The block contains:

   • (a) Completed — what was done, dated; link decisions to their ADR/docs; include one-liners for TASKS.md items finished this session (then delete them from TASKS.md). Multi-user exception (.claude/project-owner exists and you are NOT the owner): do not delete your finished items — MOVE each to a TASKS ## Review section (create it if missing) as - [x] <id> ... (@you) — evidence: reports/team/<@you>/<task>_fix_<date>.md. The evidence is a FILE — verify it EXISTS before writing the line (a chat summary is not a delivery, rules.md §10.40): the solution note sits in YOUR author folder and its index line lands in reports/team/README.md as delivered. Pathless lines and missing files are flagged at session start, and the owner's probe may also test your UNDERSTANDING of the delivery (rules.md §10.41). Review ROUTING is then the owner/orchestrator's: mechanical verification is delegated and appends — verified ✓ (owner part: <one sentence>) to the line; on accept the OWNER deletes the item and flips the index line to closed <date> accepted (reject → back to ## Now + one reason line, index back to wip). The owner's own items follow the normal delete flow.
   • (b) Tried, didn't work — approaches that failed + the reason, so they aren't retried. This is the highest-value section — don't skip it.
   • (c) Latest updates — the most recent concrete changes.
   • (d) Next steps — prioritized, for the next session.

   Signal only — a block is project STATE for the next session, not a transcript. Before writing a line, test it: would a FRESH session need it to continue, AND is it not already in git log or .claude/ritual-log? If it fails either test, drop it. EXCLUDE: VCS/ritual bookkeeping ("committed/ pushed N commits", sha ranges, "ran /keel-distill / /keel-compact") and conversational meta ("user asked if I saved", "don't rush", who said what). A DECISION that merely touches git is different — keep the WHY ("left settings.json unstaged — it holds the machine's allow-list"), drop the mechanics. At the ~150-line cap this noise is exactly what crowds out the facts that matter. One line = one fact. A line that needs a second sentence of story, a table, or a round-by-round account is a REPORT — write it under reports/ and leave the line as the fact + a pointer. The entry-budget hook blocks a new line over its per-line cap (HANDOVER_LINE_CHARS, default 400): measured on a live project, a 150-LINE cap stayed green while one line grew to 135 KB, and the file's weight fired auto-compact three times in five minutes. Rhythm: update the block at the end of each WORK BLOCK, not only at session end. Auto-compact is never blocked, so the only net under it is a disk that is already current; field case: a fix committed at 07:41, auto-compact at 07:43, and its WHY reached disk at 07:53 only because a ritual happened to run. If the SessionStart hook reports a STALE-DISK debt, settle it here FIRST — a compaction crossed this session's work before the block was written.

3. PLAN.md (if the project uses it): flip the phase statuses that changed this session, refresh Current focus, regenerate the diagram block from the table (see /keel-plan step 2) — patch the file, never rewrite it wholesale. If the wip phase's gate looks MET (its ## Now items all checked, gate evidence exists), propose /keel-phase-review to the user — don't run it unasked: flipping a phase to done is the review's job, not this skill's (rules.md §2.7).

4. Update the global Open questions / pending user decisions section (add new, delete resolved).

5. Drain TASKS ## Discovered (an INBOX, not storage — this includes project variants like ## Discovered-team): converge every line OUT — a real task → ## Next (with a done-when) · a domain/provider fact → docs/ (architecture "known limitations" / the project's R-request or integration doc) · a lesson → LESSONS.md · a design decision → an ADR · resolved/superseded → DELETE (git keeps it). Entries are ONE line; anything longer is a report/spec/ADR fragment — write it there, leave a pointer. A line that survives two handovers is in the wrong file; leave only this session's genuinely untriaged finds (the re-ground hook flags week-old leftovers).

6. Sweep the conversation for unwritten agreements (rules §9.31): any rule/test/gotcha agreed this session that isn't in LESSONS.md yet — ask, then append.

7. Set the _Last updated:_ line to today's date + a one-line status.

8. Do NOT commit/push without user approval (rules.md §1.3, §6.15).