43 lines
2.1 KiB
Markdown
43 lines
2.1 KiB
Markdown
---
|
|
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.
|