# Typo Fix

> Run codespell to detect and fix common spelling mistakes across the entire codebase, then commit the changes on a new branch from master. Use when user asks to "fix spelling", "check for typos", "spell check codebase", or "run codespell".

- Skill: `albedo-c/typo-fix` (Agent Skill)
- Install (CLI): `npx skillmds@latest add albedo-c/typo-fix`
- Raw SKILL.md: https://api.skillmd.com/api/skills/albedo-c/typo-fix/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: albedo-c (https://skillmd.com/u/albedo-c)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/albedo-c/typo-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

```bash
codespell --version
```

If not installed:

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

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

```bash
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

```bash
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`:

```bash
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:

```bash
# 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

```bash
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

```bash
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