paginated-note-writeback-hygiene

name	paginated-note-writeback-hygiene
description	Safely update paginated markdown notes during source-backed intake/backfill work without corrupting content or losing checkpoint integrity.

Paginated Note Writeback Hygiene

Use this when editing long, paginated notes that were read in slices and then patched back into place during intake/backfill work.

Goal

Keep backfills correct, compact, and reversible while avoiding accidental corruption from partial reads, duplicated blocks, or stale line anchors.

When to use

• Updating Inbox/backfill notes from source batches
• Patching a markdown file that was inspected with offsets / windows
• Inserting a new batch section into an already long note
• Applying a checkpoint after triage/writeback

Workflow

1. Read the local neighborhood first.
   • Re-read the exact target span before patching.
   • If the file was previously inspected with offset/limit, treat it as partial until the surrounding lines are re-read.
2. Patch with unique anchors.
   • Use nearby headings and content, not line numbers from a paginated read.
   • Avoid patching against raw read_file line prefixes (123|...) because those can be injected artifacts, not real file content.
3. Keep group boundaries intact.
   • One source/thread group should stay compacted as one block.
   • Deduplicate repeated facts inside the group before writeback.
4. Verify the write.
   • Re-read the edited region after patching.
   • Confirm headings, bullets, and inserted sections look exactly as intended.
5. Commit checkpoints only after successful writeback.
   • Run the exact batch checkpoint snippet only after the target source lines were fully processed.
   • Do not commit source lines that were not actually triaged.

Pitfalls

• Partial file reads can cause patch tools to warn that the file was “last read with offset/limit pagination”; re-read the target span before overwriting.
• A patch against a partial view may accidentally include rendered line numbers in the file; always verify the edited region afterward.
• If a batch section is inserted into a long note, confirm that adjacent sections still render cleanly and no headings were merged.
• Do not create one note per raw row when multiple rows belong to one conversation/thread.

Verification checklist

• Edited region re-read after patch
• No injected LINE| prefixes in the saved file
• Source ranges / URIs preserved
• Group deduped before writeback
• Checkpoint advanced only for fully processed sources

Support files

• references/paged-patch-failure.md — concise example of a partial-read patch hazard and the cleanup pattern.