Human-readable refactor

Refactor the target in $ARGUMENTS into clear, idiomatic, repository-native code.

This is a code quality workflow, not an authorship-hiding workflow. Do not falsify provenance, commit metadata, PR text, or disclosure notes. If a project requires AI disclosure, preserve that requirement.

Operating rules

1. Preserve observable behavior.
2. Do not change public APIs, external contracts, persisted formats, database schema, route names, event names, or config keys unless explicitly requested.
3. Use the style already present in nearby production code and tests.
4. Make small, reviewable changes.
5. Prefer renaming, deletion, simplification, and deduplication over new abstractions.
6. Do not add dependencies.
7. Do not add broad try/catch, logging, caching, retries, validation, or defensive branches unless the existing behavior already requires them.

Audit pass

Before editing, inspect the target and nearby files. Produce a short plan with:

• Current responsibilities.
• Existing tests or verification commands.
• Comments to keep, rewrite, or delete.
• Names to improve, with old → new mapping.
• Duplicate/dead/speculative code candidates.
• Public API or migration risks.

Cleanup rules

Comments

Delete comments that merely restate code, such as:

• “Loop through…”
• “Check if…”
• “Return the result…”
• “Initialize variable…”
• “This function handles…”

Keep or rewrite comments that explain:

• Why a decision exists.
• Domain constraints.
• External API quirks.
• Security or data integrity invariants.
• Complex algorithms after simplification is exhausted.

Names

Rename generic identifiers to domain-specific names.

Bad patterns:

• data, result, item, obj, temp, helper, manager, processor, handler, utils, doThing, processData, handleRequest

Preferred patterns:

• domain noun for values/state.
• precise verb phrase for functions.
• names consistent with neighboring files.

Do not rename public exports or serialized fields unless explicitly approved.

Structure

• Inline one-off helpers when the helper hides more than it clarifies.
• Extract helpers only when it names a real domain concept or removes meaningful duplication.
• Remove dead branches, unused parameters, unused types, unused wrappers, and speculative extension points.
• Simplify nested conditionals with guard clauses when that matches local style.
• Prefer direct code over generic abstractions with one implementation.

Verification

Run the narrowest relevant verification command after each pass:

• existing unit tests for touched files,
• typecheck,
• lint,
• build,
• or a project-specific command from AGENTS.md/CLAUDE.md.

If verification cannot run, state why and identify the residual risk.

Output

Return:

1. Summary of changes.
2. Files changed.
3. Behavior-preservation evidence.
4. Naming/comment decisions.
5. Risks or follow-up refactors intentionally left out.