polish-code-base

name

polish-code-base

description

Use this skill to walk through an existing code base and fix surface-level problems that are obvious on a careful read: typos, grammar mistakes in comments and strings, inconsistent naming or formatting, dead imports, stale references, broken links, mismatched casing, and small contradictions between neighboring files. Stay on the visible layer — do not refactor logic, do not run unit tests, and do not chase deep design issues. Apply each fix directly when it is obvious, and report borderline cases for the author to decide.

Walk the repository top-down: README, configuration files, then source directories in the order a newcomer would read them, so the polish covers the parts a reader sees first.

Read each file end-to-end before editing it; a typo in line three may be repeated in line forty, and a single pass catches both.

Fix obvious typos in comments, docstrings, log messages, error messages, commit-ready user-facing strings, and identifiers that are clearly misspelled (recieve → receive, seperator → separator).

Fix grammar mistakes in English prose embedded in code: subject-verb agreement, article use, tense consistency, and punctuation, without changing the author's voice.

Normalize trivial inconsistencies that have a single obvious answer: trailing whitespace, mixed line endings, tabs versus spaces inside one file, missing final newline, and inconsistent quote style inside one file.

Flag naming inconsistencies where the same concept appears under two spellings in the same module (userId and user_id, Cancelled and Canceled); fix only when the dominant spelling is unambiguous, otherwise report.

Remove dead imports, unused variables the linter has already flagged in comments, commented-out code older than the surrounding file, and TODO notes that reference resolved tickets or removed code.

Fix broken Markdown: unbalanced backticks, unclosed code fences, dead reference-style link definitions, headings that skip levels (H2 → H4), and link text that no longer matches the destination.

Fix broken links in README and docs when the target has a clear modern equivalent (http:// → https:// on a host that requires it, moved canonical URLs); leave genuinely dead links flagged for the author.

Align error and log messages with the project's existing convention when one is visible: no trailing period, single sentence, lowercase or sentence case as the rest of the file uses.

Fix obvious contradictions between a file and its immediate neighbors: a function renamed in the source but still referenced by its old name in a sibling comment, a constant changed in one place and stale in another, a CHANGELOG entry that disagrees with the version in the manifest.

Apply the fix in place when the correct answer is obvious and reversible; group related fixes per file in a single edit so the diff stays readable.

Report — do not silently change — anything that requires a judgment call: ambiguous renames, stylistic preferences the project has not committed to, two equally common spellings, or a comment that may be intentionally archaic.

Do not refactor logic, extract functions, rename public APIs, reorder methods, or restructure modules; the job is polish, not redesign.

Do not run unit tests, integration tests, or the full build; this skill targets the visible layer and trusts that a separate build pass will catch behavioral regressions.

Do not touch generated files, vendored dependencies, lock files, minified assets, fixture data captured from real systems, or any file marked do not edit.

Do not "improve" prose that is already correct; leave voice, tone, and word choice alone unless a rule above applies.

Do not batch-fix with sed, awk, or global search-and-replace across the whole repo; walk file by file so each change is read in context before it is saved.

When the same issue appears in many files (a misspelled word, a stale URL, a deprecated header), fix every occurrence in the same pass and list the affected files in the report, so the author sees the scope at a glance.

End with a short report: the files touched, the kinds of fixes applied, and a separate list of borderline cases left for the author to decide.