Codespell fix

What I do

• Run codespell to generate a list of spelling suggestions (no auto-write)
• Read and review every suggestion to confirm it is a genuine misspelling (not a technical term, variable name, or domain-specific word)
• For each valid fix: read the affected line in the file, understand the context, and manually apply the correction using file editing tools
• Create a new git branch from master named fix/typo-YYYYMMDD (using today's date)
• Stage changed files, review the diff, and commit with a clear message

When to use me

Use this skill when you want to sweep the codebase for spelling mistakes in:

• Comments and docstrings
• String literals and error messages
• Documentation files (.md, .mdx, .rst, .txt)
• Variable names and identifiers that contain English words

Step-by-step workflow

1. Verify codespell is available

codespell --version

If not installed:

pip install codespell
# or, if uv is available (preferred):
uvx codespell --version

2. Run a dry-run preview (no changes yet)

codespell \
  --quiet-level 3 \
  --skip=".git,*.lock,*.min.js,*.min.css,node_modules,__pycache__,.venv,venv,dist,build,*.svg,*.png,*.jpg,*.jpeg,*.gif,*.ico,*.woff,*.woff2,*.ttf,*.eot" \
  .

Flags explained:

• --quiet-level 3: suppress binary file warnings, only show actual misspellings
• --skip: skip binary files, generated files, and dependency directories

3. Think before you fix — review every suggestion critically

Before touching any file, exercise judgment for each suggestion:

Skip the fix if any of the following are true:

• The word is a technical term, acronym, or abbreviation (e.g. repr, recvd, usr, init).
• The word is a variable name, function name, class name, or identifier used in code logic — even if it looks misspelled.
• The word appears in user-generated content: UI labels, error messages shown to end-users, user-facing strings copied from a spec or design, translatable strings, or copy that a product owner intentionally authored. Changing these without product review can break UX, translations, or user expectations.
• The word is a proper noun, brand name, or domain-specific term that only looks wrong to a generic spell-checker (e.g. mixin, teardown, webhook, signin).
• The file is auto-generated (lock files, compiled output, vendored code) — skip the entire file.
• The suggested correction changes meaning or produces an awkward result in context.

Apply the fix only if:

• The word is genuine prose that a human typed and clearly misspelled (variable names, function names, class names, comments, docstrings, README/docs text, log messages for developers).
• The suggested word is unambiguously correct in context.
• Changing it cannot break runtime behaviour, translations, or user-visible copy.

4. Create a new git branch from master

git fetch origin
git checkout master
git pull origin master
git checkout -b fix/typo-$(date +%Y%m%d)

If the default branch is main instead of master:

git checkout main && git pull && git checkout -b fix/typo-$(date +%Y%m%d)

5. Apply fixes manually

For each spelling suggestion from codespell:

1. Read the file at the line containing the misspelling:

   • Use your agent's file-reading capability to load the file
   • Find the exact line and word codespell flagged

2. Re-apply the judgment from step 3 — confirm the word deserves a fix before proceeding.

3. Apply the fix manually:

   • Use your agent's file-editing capability to replace only the misspelled word
   • Do NOT use --write-changes — apply fixes one at a time so each change is deliberate
   • Do NOT batch-apply all suggestions blindly

Example workflow for each file:

# Run codespell to see suggestions (output shows file:line:misspelling -> suggestion)
codespell --quiet-level 3 --skip="...,*.svg,*.png" .

Then for each suggestion, read the file, locate the line, and edit:

• Old: "This fuinction processes data"
• New: "This function processes data"

6. Review the diff

git diff

Carefully inspect each change. If any fix looks wrong (corrected a technical term, variable name, etc.). Revert that specific change

7. Stage and commit

git add -A
git commit -m "fix: typo/spelling correction/whatever is the most appropriate commit message"

Rules and guardrails

• Avoid changing variable names, function names, class names, or any identifier that appears in code logic — only fix human-readable prose (comments, docstrings, strings intended for display, documentation). Exception: if a variable name is an obvious typo and you update every usage site, that is acceptable.
• Preserve user-generated content — do not alter user generated content or any text that was intentionally authored by a product owner or designer. When in doubt, skip the fix.
• Do not mix spelling fixes with other changes in the same commit
• If more than 10 files are changed, split into multiple commits by file type (docs first, then source)
• Do not mention you used codespell anywhere