# Refactoring and rename methodology

Hard-won mechanics for renames, module moves, and file re-shelving in this codebase — distilled
from the frame rename, the 2026-07 naming pass (`dev/archive/naming_pass_plan.md`), and the
doctest sweep (`dev/archive/doctest_handoff.md`). Every item below cost a real incident or a real
near-miss. `contributor/naming_rules.md` says *what* may be renamed; this note says *how*.

## Before you start

- [ ] **Exhaustive inventory first.** Grep every inbound reference to the tokens/files you will
  touch — code, tests, docstrings, docs prose, `CLAUDE.md`, `dev/` — before changing anything. For
  file moves this is non-negotiable: the reference sweep is planned from the inventory, not
  discovered from build failures.
- [ ] **Inventory BOTH import forms**: `import x.y as z` *and* `from x import y as z`. A missed
  `from`-alias once silently broke the uniform seam.
- [ ] **Plan longest-token-first substitution order**, so substring collisions cannot fire; renames
  of bare names that other layers share must be **word-bounded and module-scoped**.

## During the rename

- [ ] **Frontend-method collisions need scoped renames.** Many backend names double as frontend
  method names (`apply_corewise_transpose`, `retract`, `rank_adjustment_sweep`); those need
  *qualified* (alias-scoped) renames, with bare renames only inside the defining module — a blind
  bare rename mangles the frontend.
- [ ] **Substring module names need lookbehinds** (`orthogonalization.py` ⊂
  `t3_orthogonalization.py`).
- [ ] **`getattr(module, 'name')` string references are invisible to token renames** — the suite
  catches them, loudly; expect and fix them rather than being surprised.
- [ ] **Slash-glob prose** (`compute_xis/mus/...`) and **brace-glob docstrings**
  (`probing.{a,b,c}_*`) never match a token sweep — find and fix them by hand.

## Gates

- [ ] **Never pipe the gate.** `pytest ... | tail` reports the *pipe's* exit code, not pytest's —
  use `set -o pipefail`, or capture the status directly.
- [ ] **Never edit tracked files while a gate runs.** One mixed-tree incident forced a reset and a
  deterministic replay; the gated tree must be exactly the committed tree.
- [ ] **The docs build is a gate too**: `sphinx -W` (zero warnings) after any change that touches
  docstrings, doc pages, or file locations — it is what catches missed cross-references.

## Delegating mechanical sweeps to agents

- [ ] **One agent per file.** Two agents editing the *same* file race and lose each other's edits;
  different files in parallel is fine.
- [ ] **Always re-verify by running** — the delegate's green report is not the gate; re-run the
  module's doctests/tests yourself after it finishes.