# Handover

> 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.

- Skill: `isvlasov/handover` (Agent Skill)
- Install (CLI): `npx skillmds@latest add isvlasov/handover`
- Raw SKILL.md: https://api.skillmd.com/api/skills/isvlasov/handover/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: isvlasov (https://skillmd.com/u/isvlasov)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/isvlasov/handover

---


# 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.