Read-before-edit — gate before file modification

Rule

Every file you modify must have been read in the same session.

Not in the previous session. Not "sometime". In this session.

Why

• Files change between sessions (you or another agent commit changes)
• Agent memory is unreliable
• Overwriting without reading = losing someone else's work
• Edit tools require exact match — without reading the latest version, Edit fails

Flow

About to modify file X?
  └── Did you read X in this session?
        ├── YES → Edit / Write
        └── NO  → Read X first, then Edit / Write

Practical rules

1. Read before the first Edit in a session

2. Re-read after long operations (build, subagent, branch switch, lots of time)

3. Write-new-file doesn't require Read — but Glob first to make sure the file doesn't exist

4. Bulk edit via sed/awk — forbidden

Without reading the diff is unknown. Regex on production code = risk. Edit tool has exact match, safer.

Red flags

• "From memory I know this file has function X" → re-read
• "I'm editing a file I haven't opened but I know what it does" → STOP, Read
• "I'll skip Read, I know the structure" → memory is lying to you, Read
• "File hasn't changed since my last Read 30 min ago" → maybe it did, Read

What to do when Edit fails on "string not found"

You have a stale snapshot in memory:

1. Re-read the file fresh
2. Find the current fragment
3. Update old_string to current content
4. Edit again

DO NOT try different regex, replace_all: true "to make it work", or sed/awk fallback.

Integration with other harness skills

• Plan-before-code: plan lists files to edit — each must be Read first
• Phase continuity brief: brief shows commits since last session → files requiring Read before touching
• Tool failed → STOP: Edit fail = tool failed = STOP and diagnose (re-read)

Effect

• Zero overwritten work
• Zero "magical" merge conflicts
• Edit always works on first try
• Session audit trail shows Read → Edit pair per file