The problem: The Notion API will tell you an edit succeeded when it silently dropped half your patches. It’ll tell you a comment anchor is unique when a phrase that repeats three paragraphs down makes it ambiguous. Both failures are invisible until someone reads the live document closely, usually the reviewer you were revising it for.
This names the three specific ways the API misleads you and pairs each with the check that catches it. update_content returns success even when an old_str doesn’t match (a stray em dash, a bold marker, a discussion-span wrapper around the target text), so every patch gets re-verified against a fresh fetch, never trusted from the response alone. Comment anchoring searches the whole document for the closing phrase, not just your target block, so before posting a comment you count how many times that phrase appears anywhere later in the page; more than once means the anchor is ambiguous and needs tightening. And notion-get-comments itself can silently under-return: an open comment the UI shows plainly can come back as zero results from the API, so the API’s comment count is treated as a floor, never a complete count, and confirmed against the reviewer’s own screenshot when it matters.
update_content call; a success response is not proof anything actually changedold_str match; include the span itself in the patch, or the edit silently skipsreplace_content, record every open thread’s anchor text and summary first; a full rewrite destroys every inline anchor at oncePart of Operator Skills, a collection of skills for running a real Claude Code setup.