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