---
name: state-hygiene
description: Enforces safe handling of an agent's own durable state/notes files (e.g. state/notes.md, state/TODO.md, or anything else under state/ meant to survive a container restart) - read the file before archiving, overwriting, or pruning it, split resolved work into small dated archive files instead of growing one giant live file, and never shell-pipe-append (>>) into a notes file. Use this whenever you are about to write to a durable notes/state file, especially right before a context-compaction checkpoint, when told to "flush state" or "write down anything relevant", or when a live notes file has grown large and needs an archive pass.
---

# State Hygiene

Durable notes/state files (your `CLAUDE.md`, `state/notes.md`, `state/TODO.md`,
and anything else under `state/`) are your memory across container resets and
context compactions. They only work if you actually read them before you
change them - writing blind is how history gets silently destroyed or
duplicated.

## Before writing to any durable notes file

1. **Read it first.** Never overwrite or append to a notes/state file based
   on memory or assumption of its current contents - the file may have moved
   on since your last read (another turn, another agent touched shared
   space, a prior session ended mid-edit). Read (or re-read the relevant
   section) immediately before editing.
2. **Never pipe-append.** Don't do `echo "..." >> state/notes.md` (or
   equivalent) from a shell command. That's a blind write with no chance to
   see - and reconcile with - what's already there. Use your file-edit tool
   (read, then edit/write) instead.
3. **Prefer a targeted edit over a full rewrite** for anything long-lived: an
   edit is less likely to accidentally clobber unrelated content than
   regenerating the whole file from your current context.

## Keeping a notes file lean

- Split into a **live file** (only what's currently active/gated/relevant -
  this is what you re-read every turn, keep it short) and an **archive
  subdirectory** (e.g. `state/notes-archive/`) for resolved/closed work,
  moved out of the hot path, never deleted. Don't drop archived files
  loose at the top level of `state/` alongside the live files - a
  dedicated subdir keeps `ls state/` showing only what's live.
- Archive in **dated, per-topic chunks** - `YYYY-MM-DD-<topic>.md` - not one
  ever-growing archive blob. `ls` on the archive subdir should read like a
  timeline.
- When you finish a piece of work, collapse its entry in the live file to a
  one-line "done" summary and move the full detail into a new dated
  archive file.
- A live file well past ~500 lines (or into four figures) is overdue for an
  archive pass - do it at a natural checkpoint (finishing a task, a
  context-compaction prompt, or whenever you notice it).

If your environment ships its own hive-wide/repo-wide notes convention doc,
treat that as the canonical source and this skill as a reminder to follow
it - don't duplicate its rationale into your own notes either.