2.1 KiB
name, description
| name | description |
|---|---|
| line-edit-anchor-discipline | 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.