---
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.