Improve code maintainability

Turn an observed maintenance cost into a scoped code change with evidence before and after.

Start with a finding from the inspector. Name the cost it exposes, such as fixing the same rule in several modules or changing many callers to add one supported case. Code age and personal taste are weak reasons for a rewrite.

Find the responsibility

Read the affected module, its callers, and its tests at a recorded revision. Ask what callers must know to use it correctly, including errors, ordering, and configuration. A useful improvement puts shared decisions behind a small interface and keeps their implementation in one place.

Check domain names and invariants as well. If two modules use the same word for different things, clarify that distinction before extracting shared code. Do not create a package merely to move files. Identify who will use and own its interface.

Propose one change

Create an issue containing the finding, affected callers, intended result, and checks that will establish it. For example, if three importers each implement the same path rules, propose one module that owns those rules and test it through the interface its callers use.

Record the observable results that must remain stable. Separate a structural change from a new product requirement so reviewers can judge each one. Keep a larger migration in independently reviewable steps with a clear stopping point.

Use the development cycle

Send the accepted issue through planning, implementation, and review. Ask the reviewer whether the change actually removed duplicated knowledge or made callers simpler. Moving the same complexity into several new abstractions does not establish an improvement.

Keep the original finding in the work log. It becomes the basis for evaluation and the later check that the maintenance cost decreased.

For instruction changes, continue with Improve agents, prompts, and skills.