agent failed to rename a variable across cells: missed one reference, NameError crash

TL;DR

Renaming a variable with find-and-replace misses references inside strings, misses dynamically constructed names, and can hit substrings of other names, leaving one stale reference that crashes with NameError at runtime. Do renames structurally: parse every code cell's AST, rename the binding and all true references, then grep the notebook for the old name and explain each remaining hit. The grep-after-rename is the acceptance test.

agent failed to rename a variable across cells: missed one reference, NameError crash

Use this when

• A renamed variable still crashes with NameError on the old name.
• The agent renames with text search-and-replace.
• The notebook has many cells sharing variables.

Not for this skill when

• The rename was wrong semantically. That is a logic error.
• A human renames in the UI. Use a proper rename refactoring.

Steps

1. Parse all code cells with ast and find the binding and its references. Verify: you have the complete reference set.
2. Rename binding and references structurally (or with a refactoring library). Verify: the AST shows the new name everywhere.
3. Grep the raw notebook for the old name. Verify: every remaining hit is explained (string literal, comment, unrelated).
4. Execute the notebook top to bottom on a fresh kernel. Verify: no NameError.
5. Record the rename in the agent's report. Verify: the human can review what changed.

Variant phrasings

rename variable across notebook cells

Short form. AST rename plus grep verification.

agent rename missed reference NameError

The bug phrasing. Text replace is not a rename.

cross-cell variable rename notebook

General phrasing. Verify with execution.

Compatibility: Python 3, nbformat 5.x. ast-based rename works for straightforward bindings.

Why it happens

Notebooks scatter a variable's lifetime across cells, so a rename must span the whole document, and text replacement cannot distinguish the variable from the same characters in a string, a comment, or a longer name. One missed reference is a NameError that only fires when that cell runs, which may be far from the rename. Structural renaming plus a verification grep closes the gap.

Edge cases / pitfalls

• Dynamic references (globals()[name], eval) defeat AST renaming. Flag them for human review.
• Renaming inside magic commands (%time df) needs special handling; the magic body is not parsed Python.
• A rename that collides with an existing name creates a worse bug. Check the new name is free first.
• Jupyter's own rename refactoring (in recent Lab) handles single notebooks well; use it when a human is driving.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_eeh549P9jb71IBkXxDKIeA