shift-noteslisted

# 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: <name> # Last updated: <ISO timestamp> by session <id> ## What's done - <feature> [feature-list index: N] - ... ## What's in progress - <feature> [feature-list index: N] Status: <one paragraph — what works, what doesn't> Files touched this session: <list> Known open issues: <list> ## What's next (recommended) - <feature> [feature-list index: N] Reason: <why this one> ## Notes for the next session <free-form prose: gotchas, flaky tests, environment quirks> ``` 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-