Vale Lint & Fix

Run Vale on files, then fix issues directly based on the lint output.

Workflow

1. •Run Vale with JSON output on the target file(s):

vale --output=JSON <file-or-glob>

1. •

   Parse the JSON output. Each issue has:

   • •Line, Span (column range) — location
   • •Check — rule name (e.g. Microsoft.Passive, write-good.Weasel)
   • •Message — human-readable explanation
   • •Severity — error, warning, or suggestion
   • •Action.Name — suggested fix type (replace, remove, edit)
   • •Action.Params — replacement candidates
2. •

   Read the file and fix each issue:

   • •For replace actions with clear suggestions: apply the best-fit replacement
   • •For stylistic issues (passive voice, wordiness, weasel words): rewrite the sentence
   • •For issues requiring judgment: use context to determine the best fix
   • •Skip rules that conflict with the document's domain (e.g. medical terminology flagged as jargon)
3. •

   Re-run Vale after fixes to verify issues are resolved. Repeat if needed.

Scope Rules

• •If no file is specified, ask the user which file(s) to lint
• •For globs (e.g. docs/*.md), process each file sequentially
• •Only fix error and warning by default; include suggestion if user asks for thorough review

What NOT to Fix

• •Domain-specific terminology flagged incorrectly (medical, legal, technical terms)
• •Intentional stylistic choices (e.g. first person in a blog post)
• •Code blocks and frontmatter — Vale should already skip these, but double-check