# Shift Notes > Write and read the between-session handoff file so a fresh agent with no memory can pick up where the last one stopped without re-deriving context. Structured prose, not JSON — the model writes prose better. - Skill: `elitongadotti/shift-notes` (Agent Skill) - Install (CLI): `npx skillmds@latest add elitongadotti/shift-notes` - Raw SKILL.md: https://api.skillmd.com/api/skills/elitongadotti/shift-notes/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: elitongadotti (https://skillmd.com/u/elitongadotti) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/elitongadotti/shift-notes --- # Shift Notes The hard problem in long-running agents is not doing work in one session — it's bridging the context gap between sessions. Every fresh agent starts with zero memory. If it has to reconstruct project state from the code, it burns 5-10 minutes and a chunk of context before writing a line. If it has a well-shaped handoff file, that drops to 30-60 seconds. That handoff file is `claude-progress.txt` (or equivalent). Prose, not JSON. The model writes prose more naturally, and the read is cheap. ## The format — write into this shape ``` # Project: # Last updated: by session ## What's done - [feature-list index: N] - ... ## What's in progress - [feature-list index: N] Status: Files touched this session: Known open issues: ## What's next (recommended) - [feature-list index: N] Reason: ## Notes for the next session ``` Enforced softly by the prompt, not by validation. Free text is the point — the notes section is where the previous shift warns the next one about the thing that isn't captured anywhere else. ## Writing the notes — at end of session - **Move the completed feature** from "in progress" to "done". - **Recommend the next feature** in "what's next" with a one-line reason (unblocks-N, low-risk, prerequisite-for-M). - **Notes-for-next-session** is the highest-leverage field. Use it for: flaky tests you hit, dependencies that surprised you, spec ambiguities you resolved one way (so the next agent doesn't re-litigate), env vars that need to be set. - **Do not delete "done" entries.** They're audit trail. If the section gets long, that's a signal to compact the whole notes file at v0.2 milestones, not to prune mid-project. ## Reading the notes — at start of session - Read the whole file. It's small. - **If shift notes and git log disagree, trust the git log.** The notes can be truncated by a crashed session; the log can't. This is a load-bearing rule. - Cross-reference "what's done" against the feature list. If the notes claim done but the feature list says not-done, run `broken-window-check`. - Pick work from "what's next" unless it's stale (a new session already picked it). ## Red flags - **Notes rewritten every session from scratch.** Lose history, lose audit trail. Append and edit in place, don't overwrite. - **"What's done" section grows unboundedly.** Fine up to ~40 entries. Past that, compact by feature milestone. - **Ambiguous "in progress" prose.** The next session will misread "the button is wired but the state doesn't refresh" as "done" if you write "button works". Be precise about what fails. - **Notes drift out of sync with the feature list.** Feature list is source of truth for pass/fail state; notes are the prose gloss. When they disagree, the list wins. - **JSON handoff file.** Tried and abandoned — the model wrote shorter, less useful notes when forced into JSON. Prose wins for prose. ## What NOT to put in the notes - Full file contents. Reference paths, not blobs. - Chain-of-thought for the session. Compact it into a status line. - Anything that belongs in the feature list (pass/fail state) or in git (what changed). ## Pairs with - `broken-window-check` — smoke-tests the last "done" feature the notes claim. - `spec-first` — the spec is the contract; the notes are the ledger against it. - `context-budget` — the notes are the compact recap the context-budget skill wants.