## TL;DR
Add the legitimate words to the project dictionary instead of touching the code. Put them in the `words` array in `cspell.json` (or a shared dictionary file) so every future PR gets them for free. Re-run cspell and confirm a clean exit before pushing.

## Verbatim error
```text
cspell error: unknown words found in PR, how to fix dictionary
```

## Steps

1. Run cspell on the flagged files: `cspell --no-progress docs/guide.md src/review.ts` (your real paths).
   Expected: output lists each unknown word with its file and line, like `Unknown word (foobar)`.

2. Sort the flagged words into real typos and legitimate terms. Fix the real typos in the source files.
   Expected: only product names, technical jargon, and identifiers remain flagged.

3. Add the legitimate words to `cspell.json` at the repo root:
   ```json
   {
     "words": ["foobar", "reviewdog", "golangci"]
   }
   ```
   Expected: re-running cspell on the same files reports no issues and exits 0.

4. For words shared across repos, put them in a dictionary text file (one word per line) and reference it from `cspell.json` under `dictionaryDefinitions`, so teams share one list.
   Expected: new repos get the shared words by importing the config, not by copy-pasting word lists.

## Use this when
- cspell flags correct technical terms or product names in a PR.
- You need to add words to the cspell project dictionary.
- An agent's PR fails spell check on identifiers the agent invented correctly.

## Not for this skill when
- The flagged words are actual typos (fix the spelling, do not add typos to the dictionary).
- cspell crashes or cannot find its config (check the config path and JSON syntax first).
- You want spell checking for a language cspell does not cover (that needs a different tool).

## Variant phrasings
- cspell unknown words how to add to dictionary
- cspell fails PR on technical terms
- cspell.json words list not working

## Why it happens
cspell ships with general-language dictionaries, so any domain term, product name, or code identifier looks like a misspelling to it. The project dictionary is the intended escape hatch, but teams often never populate it, so every PR rediscovers the same false positives. A curated word list turns the gate from noisy to useful.

## Edge cases
- Case sensitivity: adding `foobar` also covers `Foobar` in most configs, but all-caps acronyms sometimes need their own entry. Check with `cspell trace WORD` to see how a word resolves.
- Compound identifiers like `reviewBot` get split into `review` and `bot`; if a fragment is flagged, add the fragment, not the compound.
- Generated files and lockfiles should be in `ignorePaths`, not in the dictionary. Do not add minified bundle tokens as words.
- Words with digits (like `utf8`) are usually fine, but version strings in docs churn; prefer ignoring generated changelogs over dictionarying every version token.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_k3b6J_G3E26vkjj_oOXgIA