Menu
Pre-PR pass over a docs page or diff. Checks frontmatter, links, terminology, voice, and runs the same linters CI runs. Use before opening a PR.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Apply Windsor's docs writing style — voice, frontmatter, link conventions, structure, mermaid usage. Use before writing or editing any markdown in this repo.
Run real windsor commands against the docs to confirm they're accurate. Designs efficient validation cycles that stack multiple assertions inside a single init→up→down lifecycle.
Investigate the windsorcli/cli and windsorcli/core repos before writing or revising docs about an evolving feature. Tells you what the code actually does, when it changed, and what's in flight.
| name | docs-review |
| description | Pre-PR pass over a docs page or diff. Checks frontmatter, links, terminology, voice, and runs the same linters CI runs. Use before opening a PR. |
Pre-PR review skill for the Windsor docs repo. Pairs with
docs-style — that one is for writing,
this one is for checking.
If the diff touches behavior the docs describe — commands, flags,
file layouts, output — run upstream-history
first to confirm the claims still hold against cli/core HEAD.
Review the diff, not the whole page, unless the page is new.
Reach for git diff origin/main...HEAD -- '*.md'.
For each changed page, run these passes. Each has a clear pass / fail signal — don't editorialize on things outside the pass.
Every changed page that's a documentation page (not README, not LICENSE) must have:
---
title: ... # non-empty, sentence-case, no trailing period
description: ... # non-empty, one sentence, under 160 chars
---
CI rejects pages without title: via the frontmatter check in
docs-quality.yml.
Internal links must use site paths (root-relative, no /docs/
prefix), not relative .md paths. Grep the diff:
git diff origin/main...HEAD -- '*.md' | grep -E '\]\(\.\.?/[^)]+\.md\)'
External links must be [label](url), not bare. Markdownlint MD034
catches the latter.
Cross-repo links (/reference/cli/..., /reference/core/...,
/cli/...) resolve only on the live site — lychee skips them via the
website-origin exclude in lychee.toml. If the page leans heavily on
cross-repo links, sanity-check the target paths manually against the
website's content tree.
Run Vale locally:
vale .
Pay attention to:
Windsor.MarketingWords (warning) — drop the word, don't argueWindsor.Spelling (error) — terminology must match the tableWindsor.FutureTense (suggestion) — "will support" → link an issueWindsor.Hedging (suggestion) — drop "basically", "just", etc.Don't fight the Microsoft rules that fire as suggestion. Fix
error and warning levels; ignore suggestion unless the prose
genuinely reads better with the change.
Skim each changed page against the canonical shape:
A page may genuinely not need every section. But if a page is missing a lead, that's always a problem.
Run the linters the CI workflow runs:
markdownlint-cli2 "**/*.md" "#node_modules"
cspell --no-progress "**/*.md"
lychee --config lychee.toml --no-progress '**/*.md'
alex --quiet '**/*.md'
Don't open the PR with red on any of these.
Report findings as a checklist. Group by file. For each finding give:
content/workstation/overview.md:42)must-fix (CI will reject or the page is broken),
should-fix (style/voice problem worth a round-trip), or
consider (subjective)Example:
### content/blueprints/overview.md
- **must-fix** · content/blueprints/overview.md:12 — Internal link
uses relative path. Replace `../cli/up.md` with
`/reference/cli/commands/up`.
- **should-fix** · content/blueprints/overview.md:34 — `seamlessly
integrates` trips Vale's MarketingWords rule. Describe what the
integration actually does.
- **consider** · content/blueprints/overview.md:1 — Description is
174 chars; the OG tag truncates around 160.
End with one sentence on overall readiness: "Ready to merge after must-fix items" or "Needs another pass before review."