agent's cleanup failed: deleted a cell that defined a function used later, NameError

TL;DR

An agent that deletes 'unused' cells by shallow analysis can remove the cell defining a function called ten cells later, and the notebook dies with NameError far from the deletion. Deletion requires dependency analysis: build the def-use graph across all code cells, and only delete a cell when nothing else references its definitions. When in doubt, comment the cell out or flag it for the human instead of deleting. Deletion is irreversible; caution is the policy.

agent's cleanup failed: deleted a cell that defined a function used later, NameError

Use this when

• An agent's cleanup breaks the notebook with NameError.
• The deleted cell defined something used downstream.
• The agent deletes cells autonomously.

Not for this skill when

• A human deleted the cell. Restore from version control.
• The function was never defined. That is a different bug.

Steps

1. Restore the deleted cell from version control or the agent's backup. Verify: the notebook runs again.
2. Build a def-use analysis: parse all code cells, record definitions and references. Verify: the graph shows the deleted cell's function as used.
3. Change the cleanup policy: delete only cells with zero downstream references. Verify: the policy would have kept the cell.
4. Prefer non-destructive cleanup: comment out or tag cells for human review instead of deleting. Verify: nothing is irreversibly lost.
5. Add a post-cleanup execution test: the notebook must still run top to bottom. Verify: the test gates every cleanup.

Variant phrasings

agent cleanup deleted needed cell

Short form. Def-use analysis before deletion.

notebook cleanup NameError

The error phrasing. The deleted cell was load-bearing.

safe cell deletion notebook agent

The policy phrasing. Delete only unreferenced cells.

Compatibility: Python notebooks, any agent. The def-use principle is language-agnostic.

Why it happens

Notebooks hide dependencies across cells: a function defined in cell 3 and used in cell 30 looks 'unused' to any analysis that does not span the document. Shallow heuristics (empty outputs, old execution counts) misclassify load-bearing cells as dead. Deletion is the one cleanup operation that cannot be undone from within the notebook, so it needs the strongest analysis and the most conservative policy.

Edge cases / pitfalls

• This vertical's framing rule applies: never silently delete user code. Flag for review instead.
• Dynamic references (getattr, eval) hide uses from static analysis. Treat dynamic code as 'used'.
• The agent must back up before any deletion. No backup, no delete.
• A cleanup that breaks the build is worse than no cleanup. Gate on execution.

Provenance

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