refine-code

Refine Code

Reduce the effort needed to understand and maintain existing code while preserving its observable behavior and supported contracts. Rank improvements by cognitive load removed, not lines deleted.

Scope and authorization

Apply the user's intent to every mode:

• Assess, audit, find, review, or report: inspect and propose; do not edit code, docs, or configuration.
• Refactor, simplify, apply, clean up, or delete: implement the requested changes and verify them. Do not stop at suggestions or ask again merely because a change crosses files.
• Continue within existing authorization. Ask only for an unresolved choice that materially changes scope, safety, supported behavior, or a hard-to-reverse decision. Prepare the concrete alternatives first.

Use the files, revisions, and boundaries the user named. For recent work, inspect Git status and the relevant staged, unstaged, committed, and untracked changes. Preserve unrelated work. Read applicable repository instructions; consult neighboring code and decision records only where they explain the change in question.

Choose the relevant guidance

• Code: local readability, types, and organization. Use the guidance below.
• Architecture: coupling, module responsibilities, or testability. Read references/ARCHITECTURE.md.
• Entropy: dead code, duplicate state, unused configuration, or safe deletions. Read references/ENTROPY.md for consumer and compatibility checks.

Combine only the guidance the task needs; there is no mandatory mode sequence. If local friction has a structural cause, explain it and address it within scope. A broader redesign requires a separate decision only when it exceeds the request.

Code

Use these questions where they expose a concrete improvement:

• Deletion: if the abstraction vanished, would complexity disappear or move into callers? Keep it when it hides needed knowledge, ownership, or policy.
• Reading: where must a maintainer keep scattered facts in mind? Bring related logic together or name a meaningful intermediate value.
• Types: do types accurately represent runtime values? Narrow only with evidence from producers and consumers; static types alone do not prove external input or persisted data safe.