25 lines
2.3 KiB
Markdown
25 lines
2.3 KiB
Markdown
---
|
|
name: line-edit-anchor-discipline
|
|
description: "Avoid the recurring edit-tool line-op traps: empty PUT deletes lines, PUT ranges swallowing multi-line block delimiters, and anchors landing mid-expression. Use whenever issuing CUT/PUT line edits on tagged files."
|
|
---
|
|
|
|
# Line-edit anchor discipline (CUT/PUT ops on tagged files)
|
|
|
|
Five self-inflicted syntax wounds in one session (franksign, 2026-10-21) all trace to three rules.
|
|
|
|
## Rules
|
|
1. **An empty PUT body DELETES the targeted lines** (tool warns: "Interpreted an empty PUT body as deletion"). Twice it ate a whole log entry / a closing `}`. For no-ops use nothing; for deletes use explicit `CUT`.
|
|
2. **Never PUT a range whose endpoints cut through a multi-line block.** If a `| {`-style union variant, a frontmatter `---` fence, or a `test(...)` closer straddles the range boundary, the replacement swallows the opener/closer and strands the body. Pre-condition: line N-1 and M+1 must be block-complete. Fix-after-the-fact pattern: read the broken region raw, then `PUT k.=k:` to restore the single swallowed line (e.g. the missing `---`, the orphaned ` | {`, `}` → `});`).
|
|
3. **Search-hit reads do not authorize PUT.** A grep/folded-summary read marks lines as "never displayed"; the edit tool refuses and echoes actual content. That refusal is a free verification — re-check the echoed lines match intent, then straight-retry with the same tag.
|
|
|
|
## Costly mistakes seen
|
|
- Empty `PUT 7-7:` deleted a just-written log entry; restoring required re-issuing the full entry text.
|
|
- `PUT 6.=7` replacing `timestamp`+`---` dropped the frontmatter close fence → lint-breaking file silently.
|
|
- `PUT 10.=11` on a union type swallowed ` | {` opening a 12-line variant → cascade of LSP "unexpected label" warnings.
|
|
- `CUT` of a stranded opener left its dangling `.json())` behind; balance errors surface only at EOF (`expected ')' but file ends`) — locate by reading regions raw, not by widening the payload.
|
|
|
|
## Discipline
|
|
- After any edit that reports a syntax error or a warning: read the touched region with `:raw` before the next op; fix the single wrong line, do not resend the block.
|
|
- "no change: byte-identical" means your anchor math is off — re-read, don't append more content.
|
|
- Prefer replacing whole coherent blocks (start line = block start, end line = block end) over edits that end mid-statement.
|