---
name: line-edit-anchor-discipline
description: "Avoid the recurring edit-tool line-op traps: empty PUT deletes lines, PUT ranges swallowing neighbours, wrong-anchored PUTs replacing the wrong line, literal markdown bullet rows arriving verbatim as \"+-\"."
---

# Line-edit anchor discipline

The `edit` tool addresses lines, not intent. Three traps cost real time; all three
fail *silently* or with a repair notice that is easy to skim past.

## 1. Empty PUT deletes the range

`PUT n.=m:` with no body rows deletes lines n..m. To insert, use `PUT >n:`
(after line n) or `PUT <n:` (before line n). Never send a PUT range whose body is
empty unless deletion is the goal.

## 2. PUT ranges must be the complete final content of exactly those lines

- Replacing one line: `PUT n.=n:` with exactly one body row. If the body carries
  the *previous* line as its first row (a copy-paste of the anchor), that line is
  duplicated and the real target line is overwritten — no error, and the
  "auto-repaired replacement boundary" note is the only hint.
- Anchor only on lines the current `[path#tag]` display actually showed. If the
  tool answers "anchors to lines you never displayed", the line numbers are
  wrong: re-read that range, then re-issue. Do not retry blind.
- Multi-op edits: order ops bottom-up (highest line numbers first) so earlier
  inserts cannot shift later anchors.

## 3. Literal `- ` rows (markdown bullets) cannot go through `edit`

A body row starting with `-` parses as a CUT op. The error says to prefix it with
`+` (`+- item`) — **that advice is wrong in practice**: the file ends up
containing the literal `+- item`. When the content legitimately needs leading
`- ` bullets (prompt law text, changelog entries, lists), write it with `write`
after a full `read` of the file, or restructure the line to avoid the leading
dash.

## Verification habit

After any PUT that replaces a range, `read` the touched range (not the whole
file) and confirm the neighbouring lines survived — especially the line after the
range, which is what a swallowed boundary eats. Cheap; catches the silent cases.