code-refinement-discipline

A refactor is earned when the current shape creates real maintenance, correctness, or cognitive cost, such as duplicated domain rules, defensive branches for impossible shapes, or weak types bypassing invariants. Length, unfamiliarity, or aesthetic unevenness alone do not justify changes.

Start by reading repo instructions, callers, schemas, and tests to identify the behavior that must be preserved. Then work in coherent slices, patch the smallest set of files per responsibility, and run the nearest meaningful checks after each change.

Avoid style-only churn, file moves for visual neatness, premature generic utilities, compatibility shims without a supported external contract, and speculative memoization or caching. Also avoid collapsing domain structure into simpler code that loses validation or readability.

Stop when remaining issues are unrelated, speculative, or cosmetic. Do not stop after the first obvious cleanup if the same boundary still has duplicated rules, unclear ownership, or broken verification.

Run package-local format, lint, typecheck, and tests for contained changes. Broaden checks when touching shared schemas, public exports, authorization, persistence mapping, route contracts, or cross-feature UI, and verify rendered output for UI changes.

Fix the root cause of the failure rather than papering over it. Do not add fallback behavior, weaker types, looser schemas, optional fields, catch-all errors, or ignored promises to make the failure disappear.