/handover

name: handover
description: Session handover — end a session by systematically updating project state files for continuity. Use this when the session is ending, the user asks for a "handover", or when significant progress needs to be recorded.

Handover (Write State)

Update project files so the next session can pick up exactly where this one left off.

Step 1: Review the session

Before touching any files, reflect: what was created or significantly changed? What decisions were made? What was discovered or learned? Were new key files created (e.g. in `work/`) that a fresh session would need to know about?

Step 2: Update root files

Check every `.md` file in the project root. Follow each file's own update instructions (found at the top of the file); if a file has none, update it whenever this session's work has made it stale.

**Common root files and their update logic:**

| File | How to update | |------|---------------| | STATUS.md | Rewrite with current state (current position, recent decisions, next steps, open questions) | | LEARNINGS.md | Append only what passes the file's inclusion criteria — a durable insight a future session would act on. Most sessions add nothing. Do NOT use as a session log. | | BACKLOG.md | Move new granular tasks or unresolved issues here. Keep `STATUS.md` "next steps" focused only on immediate session continuity. | | CLAUDE.md | Update pointers — add new key files, remove stale pointers, update descriptions | | README.md | Update if project description, status, or structure changed | | PRD.md | Update if requirements shifted | | ARCHITECTURE.md | Update if architectural decisions changed | | ROADMAP.md | Update if chunks were completed, added, or reordered | | ORCHESTRATION-PLAN.md | Mark completed chunks, update build progress |

Not every project has all of these. Check what exists.

Step 3: Follow CLAUDE.md pointers

For each file CLAUDE.md references beyond the root (e.g. `work/` artefacts, orchestration logs): does the pointer still point to the right location? Has this session's work made the file stale? Update if needed.

Step 4: Hygiene checks

Structural checks only — don't deep-read files.

• **CLAUDE.md compliance** — lean pointer file standard: one-line project identity; points to key files without absorbing their content; no embedded architecture, requirements, status, or workflow descriptions; no stale sections duplicating files it points to. Fix non-compliance now.
• **Dangling pointers** — every file path referenced in CLAUDE.md and STATUS.md exists. Flag broken references to the user — don't silently remove; the file may have been moved.
• **Git hygiene** — run `git status`: junk files (`.DS_Store`, `*.swp`, `__pycache__/`, `.pyc`) → add to `.gitignore`; untracked files that don't look like this session's work → flag to the user, don't delete.

Step 5: Report

Tell the user: which files were checked; which were updated and briefly what changed; hygiene issues found (with actions taken or flagged); anything that needs the user's judgement.