docs-style-check

name	docs-style-check
description	Check modified documentation pages against prose style rules. Auto-trigger after writing or editing docs content in docs-site/docs/. Also trigger on "check style", "style guide", "docs review", "validate docs". Should run as a final step whenever docs .md files are modified. IMPORTANT: anytime docs-site/docs/**/*.md files are modified, this should always run automatically without being asked.

Docs style check

You are a documentation editor for CLI Forge. Whenever you detect that the user is writing or editing documentation files in docs-site/docs/ (.md files), automatically run this check and fix any issues. Do not wait to be asked.

Phase 1: Placement check

CLI Forge docs have a simple structure:

• docs/guides/ — narrative, task-oriented pages for humans (quick start, how-to guides)
• docs/cli/ — auto-generated CLI reference (do NOT manually edit these files)
• Examples — live in examples/ as runnable TypeScript files with YAML front-matter descriptions

For every new or moved page, check:

1. Guide vs. reference: Is this a learning page (guide) or a lookup page (reference)? Guides belong in docs/guides/. Reference content is auto-generated in docs/cli/.
2. Not duplicating examples: If the page is mostly a code walkthrough, it may belong as an example in examples/ rather than a guide.
3. Do not edit docs/cli/: These files are generated by cli-forge generate-documentation. If they have issues, fix the generator or the CLI source code instead.

Phase 2: Style validation

Step 1: Run Vale and fix errors

Run mise exec -- vale <modified-files> to check the modified files.

• errors — fix these automatically. Edit the file to resolve the violation.
• warnings — fix these automatically when the fix is unambiguous (e.g., sentence case headings). For ambiguous cases, suggest the fix and ask.
• suggestions — mention them to the user but do not auto-fix.

Step 2: Manual checks Vale doesn't catch

After Vale, manually verify:

• Code examples are complete and runnable — no pseudo-code or incomplete snippets
• Links are valid — relative paths resolve to actual files
• Front-matter is present — guides should have title, description, and order in YAML front-matter
• Sentence case headings — Vale catches most, but verify edge cases with acronyms or product names

Handling false positives

Use inline Vale comments to suppress legitimate exceptions:

<!-- vale CliForge.Headings = NO -->

## extractLicenses

<!-- vale CliForge.Headings = YES -->

Common cases where suppression is appropriate:

• CLI option headings (e.g., ## extractLicenses) — camelCase by design. Prefer wrapping in backticks first (## `extractLicenses`).
• Technical terms that trigger marketing language rules in context where they are precise

Do NOT suppress rules just to avoid fixing real violations.

Output summary

After fixing, report what you did:

## Style check results

### Placement: [PASS/FAIL]
[List any violations or confirm placement is correct]

### Vale: [X errors fixed, Y warnings fixed, Z suggestions noted]
[Summary of changes made]

### Manual fixes: [list of additional fixes applied]