Handle cspell unknown word warnings with prioritized decision tree and config bootstrapping

Install

/plugin install vp-cspell@vdustr

Run it inside Claude Code after adding the marketplace with /plugin marketplace add VdustR/vp-claude-code-marketplace.

Contents

Discovered from source

Skills 1

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

  1. Config Check First — Verify repo has cspell config before any action; offer bootstrap if missing
  2. Adjust Text Before Adding to Dictionary — Restructure words (hyphenate, camelCase) when safe
  3. 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

  1. 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.
  2. Apply fix priority — Stop at the first applicable level (see table below).
  3. Select directive — When using inline directives, consult decision-tree.md for the selection guide.

Fix Priority

PriorityStrategyWhen to Use
1Adjust textCompound word cspell doesn't recognize; restructuring is safe (hyphenate, camelCase). See decision-tree.md for the full exception list
2Project dictionaryWord appears in 2+ files or is expected to recur project-wide
3Inline directiveOne-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

ErrorAction
No write permission to configNotify user, suggest manual edit path
Excessive cspell . outputScope to source directory, configure ignorePaths first
Context7 unavailableFall 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

Sponsors

Details

Marketplace
VdustR/vp-claude-code-marketplace
Source
plugins/vp-cspell
Category
Community
License
MIT
Keywords
cspell, spelling, linting, ide

More from VdustR/vp-claude-code-marketplace

All 12