| name | post-change-refactor |
| description | Refactor concepts implicated by the current uncommitted change before commit. Use concept-bounded scope even when completion requires untouched code, but Jidoka-stop before unapproved cross-subsystem refactoring. Remove duplication, unclear naming, shotgun surgery, dead / test-only / redundant code, and oversized files; run related tests. Use after finishing implementation work, before commit, or on: refactor change, clean up change, post-change refactor, before commit cleanup, tidy current change. |
Clean concepts implicated by the **current uncommitted change** so they are
cohesive, capability-named, and non-speculative, then return control for commit.
Purpose: Local wrap-up gate before commit — structure only, no new behavior.
Output: Refactored tree + ## REFACTOR COMPLETE, or an impact report +
## REFACTOR JIDOKA STOP. Do not commit — the caller commits after success.
**Mandatory first read:** `.cursor/agent-map.md` (navigation + focused test commands).
Scope is concept-bounded, not file-bounded. A candidate must be triggered
by an issue introduced, exposed, or materially aggravated by the current change
or highly related code. Such code represents the same concept, duplicates the
same knowledge, or must change to leave it coherent. Dependency adjacency alone
is neither required nor sufficient.
Find the smallest complete set of representations, callers, tests, fixtures,
and configuration needed for coherence, including untouched code when needed.
Every edit must serve that candidate; do not initiate nearby cleanup.
Discover scope:
git status
git diff
git diff --cached
Git does not use the Nix prefix. All other repo tooling does:
nix develop -c …
Plan justification (decision boundary):
Keep code justified by the current change or the immediate next
plan unit when .planning/ exists (read and the active phase
or quick dir). Anything justified only by a later phase, or by "we might
need it later", is speculative — remove it. No plan → justification comes
only from the current change. The immediate next plan unit may justify
retaining code, but does not independently trigger unrelated refactoring.
- **"New" duplication** means at least one copy is newly introduced or
closely related to newly introduced code — not that every copy is new.
Collapse it even when the other side already existed.
- Look for copy-pasted blocks and parallel structures with cosmetic
differences that the change introduced or made visible (new code
repeating logic that already lived elsewhere).
- The same concept in two representations counts as duplication, not just
literal copies.
- **Action:** collapse onto a single representation. Prefer reusing an
existing helper in the right layer (language reader, extension, shared
tokenizer utility in `code_reader.py`) over inventing a new one.
- Read every new or renamed identifier — files, modules, classes, functions,
variables, tests, fixtures.
- Ask: does the name match what a domain reader expects? Does it match
Lizard's language (complexity metrics, language readers, tokens, state
machines, CCN, NLOC, extensions)?
- **Action:** rename when intent is unclear, misleading, mixes layers, or
leaks phase numbers / sequence info. Names describe **capability**, not
development history.
- Shotgun surgery: **one logical concept** (e.g. a default threshold, a
language keyword list, an extension option name) forces edits in many
places for one purpose.
- Give the concept **one** representation. The next change of that shape
should touch that place — not be scattered again.
- Acceptable extra touchpoints: tests that assert the concept. Do not
hardcode the same value in reader, extension, CLI options, and test
fixtures in parallel.
- **Action:** consolidate now behind one seam (one constant, config, or
module). Leave only low-likelihood one-offs unabstracted.
Remove aggressively whatever the change introduced or exposed that is not
justified by the current change or the immediate next plan unit:
For every file in the current diff and every file proposed for editing:
Run **related** tests for the changed files — not the whole suite.
Use `nix develop -c …` for all commands except `git`.
On successful completion, report a short summary to the caller:
