cspell
Prioritized strategy for handling cspell unknown word warnings. Classify each flagged word, pick the narrowest fix, and optionally bootstrap cspell config for projects that don't have it yet.
Core Principles
- Config Check First — Verify repo has cspell config before any action; offer bootstrap if missing
- Adjust Text Before Adding to Dictionary — Restructure words (hyphenate, camelCase) when safe
- Narrowest Scope Wins — Inline directive for one-off words; project dictionary for recurring terms
Documentation: Fetch cspell syntax and config details via Context7 (/streetsidesoftware/cspell) at runtime; never rely on hardcoded syntax.
When to Use
- cspell flags an unknown word (IDE diagnostic or CI output)
- User asks to fix cspell warnings, add words to dictionary, or suppress cspell errors
- User wants to set up cspell in a project that doesn't have it
- User asks why a word is flagged or wants to understand cspell behavior
- Linting pipeline or pre-commit hook fails due to unrecognized words
When NOT to use: For non-cspell spell checkers (typo, codespell, Vale, textlint). For other linting tools (ESLint, markdownlint), use their respective strategies.
Workflow
- Check for cspell config — Search from the file's directory upward for cspell config files:
package.json (cspell field), .cspell.json, cspell.json, cspell.config.{json,mjs,js,cjs,yaml,yml,toml}, cspell.{yaml,yml}, and their ./.config/ prefixed variants (e.g., .cspell.config.yaml, .config/cspell.json). Also check .vscode/cspell.json. If none found: notify user, do NOT auto-fix, offer to bootstrap (see below). Note: cspell.* settings in .vscode/settings.json are IDE-local and do not count as project config.
- Apply fix priority — Stop at the first applicable level (see table below).
- Select directive — When using inline directives, consult decision-tree.md for the selection guide.
Fix Priority
| Priority |
Strategy |
When to Use |
| 1 |
Adjust text |
Compound word cspell doesn't recognize; restructuring is safe (hyphenate, camelCase). See decision-tree.md for the full exception list |
| 2 |
Project dictionary |
Word appears in 2+ files or is expected to recur project-wide |
| 3 |
Inline directive |
One-off word in a single file/location. See decision-tree.md for directive selection and placement |
Config Bootstrapping
When a repo has no cspell config and the user wants to add one, guide through an interactive Q&A flow.
See config-bootstrapping.md for the full interactive setup flow.
Guidelines
DO
- Check repo config before any action
- Prefer text adjustment over dictionary pollution
- Use narrowest scope directive that fits
- Place
cspell:words at file top for discoverability
- Verify the flagged word is genuinely unknown (not a missing dictionary)
DON'T
- Replace words with semantically different alternatives
- Add one-off words to project dictionary (use inline directives)
- Use
cspell:disable to suppress large sections when individual words can be handled
- Blindly accept all cspell suggestions — some flagged words are correct
- Hyphenate or restructure runtime API identifiers, package names, or fixed external terms
Error Handling
| Error |
Action |
| No write permission to config |
Notify user, suggest manual edit path |
Excessive cspell . output |
Scope to source directory, configure ignorePaths first |
| Context7 unavailable |
Fall back to cspell.org or cspell init --help |
For bootstrapping-specific errors (cspell CLI not installed, cspell init fails), see config-bootstrapping.md.
Reference Files
- decision-tree.md — Full decision flowchart, text adjustment rules and exceptions, dictionary vs inline criteria, directive selection, edge cases
- config-bootstrapping.md — Interactive setup flow, stack detection, CI integration, post-init adjustments
1---2name: cspell3description: Handle cspell unknown word warnings with a prioritized decision tree and config bootstrapping. Use when users encounter cspell diagnostics, spelling errors from cspell, CI or linting failures on unrecognized words, or ask to add words to the cspell dictionary, suppress cspell warnings, or choose between cspell:words and cspell:ignore directives. Also trigger when setting up cspell in a new project, when any cspell-related IDE warning appears, or when a pre-commit hook fails due to unknown words. Boundary: not for non-cspell spell checkers (typo, codespell, Vale, textlint) or other linting tools (ESLint, markdownlint).4---56# cspell78Prioritized strategy for handling cspell unknown word warnings. Classify each flagged word, pick the narrowest fix, and optionally bootstrap cspell config for projects that don't have it yet.910## Core Principles11121. **Config Check First** — Verify repo has cspell config before any action; offer bootstrap if missing132. **Adjust Text Before Adding to Dictionary** — Restructure words (hyphenate, camelCase) when safe143. **Narrowest Scope Wins** — Inline directive for one-off words; project dictionary for recurring terms1516> **Documentation**: Fetch cspell syntax and config details via Context7 (`/streetsidesoftware/cspell`) at runtime; never rely on hardcoded syntax.1718## When to Use1920- cspell flags an unknown word (IDE diagnostic or CI output)21- User asks to fix cspell warnings, add words to dictionary, or suppress cspell errors22- User wants to set up cspell in a project that doesn't have it23- User asks why a word is flagged or wants to understand cspell behavior24- Linting pipeline or pre-commit hook fails due to unrecognized words2526**When NOT to use**: For non-cspell spell checkers (typo, codespell, Vale, textlint). For other linting tools (ESLint, markdownlint), use their respective strategies.2728## Workflow29301. **Check for cspell config** — Search from the file's directory upward for cspell config files: `package.json` (`cspell` field), `.cspell.json`, `cspell.json`, `cspell.config.{json,mjs,js,cjs,yaml,yml,toml}`, `cspell.{yaml,yml}`, and their `.`/`.config/` prefixed variants (e.g., `.cspell.config.yaml`, `.config/cspell.json`). Also check `.vscode/cspell.json`. If none found: notify user, do NOT auto-fix, offer to bootstrap (see below). Note: `cspell.*` settings in `.vscode/settings.json` are IDE-local and do not count as project config.312. **Apply fix priority** — Stop at the first applicable level (see table below).323. **Select directive** — When using inline directives, consult [decision-tree.md](references/decision-tree.md) for the selection guide.3334## Fix Priority3536| Priority | Strategy | When to Use |37|----------|----------|-------------|38| 1 | **Adjust text** | Compound word cspell doesn't recognize; restructuring is safe (hyphenate, camelCase). See [decision-tree.md](references/decision-tree.md) for the full exception list |39| 2 | **Project dictionary** | Word appears in 2+ files or is expected to recur project-wide |40| 3 | **Inline directive** | One-off word in a single file/location. See [decision-tree.md](references/decision-tree.md) for directive selection and placement |4142## Config Bootstrapping4344When a repo has no cspell config and the user wants to add one, guide through an interactive Q&A flow.4546See [config-bootstrapping.md](references/config-bootstrapping.md) for the full interactive setup flow.4748## Guidelines4950### DO5152- Check repo config before any action53- Prefer text adjustment over dictionary pollution54- Use narrowest scope directive that fits55- Place `cspell:words` at file top for discoverability56- Verify the flagged word is genuinely unknown (not a missing dictionary)5758### DON'T5960- Replace words with semantically different alternatives61- Add one-off words to project dictionary (use inline directives)62- Use `cspell:disable` to suppress large sections when individual words can be handled63- Blindly accept all cspell suggestions — some flagged words are correct64- Hyphenate or restructure runtime API identifiers, package names, or fixed external terms6566## Error Handling6768| Error | Action |69|-------|--------|70| No write permission to config | Notify user, suggest manual edit path |71| Excessive `cspell .` output | Scope to source directory, configure `ignorePaths` first |72| Context7 unavailable | Fall back to [cspell.org](https://cspell.org/configuration/) or `cspell init --help` |7374> For bootstrapping-specific errors (`cspell` CLI not installed, `cspell init` fails), see [config-bootstrapping.md](references/config-bootstrapping.md).7576## Reference Files7778- [decision-tree.md](references/decision-tree.md) — Full decision flowchart, text adjustment rules and exceptions, dictionary vs inline criteria, directive selection, edge cases79- [config-bootstrapping.md](references/config-bootstrapping.md) — Interactive setup flow, stack detection, CI integration, post-init adjustments
VdustR