| name | style-review |
| description | Review documentation for editorial compliance (voice, terminology, formatting, content type, frontmatter, workflow). Use before submitting a PR or when asked to audit existing pages. |
Style review
When to use
- You want to check existing content for style, terminology, formatting, or content-type issues.
- You are preparing to submit a PR and want a structured editorial pass.
Inputs
The user provides a file path or directory to review. If not provided, ask what to review.
Step 1: Identify the content type
Read the file path to determine the content type (which subfolder determines the expected
structure, for example, concepts/, how-to/, reference/). Use
.cursor/rules/content-types.mdc for the mapping.
Step 2: Run Vale (if available)
Try running Vale on the target file:
vale <file-or-directory>
If Vale is not installed, skip this step and note it in the report. Continue with the manual review.
Step 3: Review against editorial rules
Read the file fully. The following points are quick reminders; use the linked .mdc files as the
source of truth for full criteria, examples, and edge cases.
Voice and tone (editorial-voice.mdc)
- Active voice and present tense used throughout.
- Second person ("you"), not "the developer" or "users."
- Contractions used naturally.
- No marketing language, superlatives, or promotional tone.
- No em dashes or en dashes; use commas, parentheses, or semicolons.
- First sentence of each section gets to the point.
- No slang, figures of speech, or culturally specific idioms.
Terminology (terminology.mdc)
- Product names match the required forms.
- Standards spelled out on first use with identifier in parentheses (for example,
"Ethereum Improvement Proposal 1559 (EIP-1559)"), short form on subsequent references.
Markdown formatting (markdown-formatting.mdc)
- Lines wrapped at roughly 80 columns.
- Each sentence on its own line.
- Code blocks have a language tag.
- Links use relative paths within the area, absolute paths across areas.
- Descriptive link text; no "click here" or bare URLs.
- Admonitions use Docusaurus syntax and are not nested.
- Tables are aligned in source Markdown.
- No duplicate H1 if frontmatter contains a
title field.
Content type compliance (content-types.mdc)
- Page structure matches the expected content type for its folder.
- Concept pages: no step-by-step instructions, ends with "Next steps."
- How-to pages: goal stated first, prerequisites listed, numbered steps.
- Reference pages: format matches surrounding pages in the same section.
- Tutorial pages: complete walkthrough with expected output at each step.
Frontmatter
description field present (one sentence for SEO).sidebar_label only when needed (default nav label would be too long or wordy); otherwise omit.- No duplicate H1 if
title is set in frontmatter.
Contributor workflow (contributor-workflow.mdc)
- If the file is new, verify sidebar ordering is correct.
- If the file was moved or renamed, verify a redirect exists in
vercel.json.
- Cross-area links use absolute URL paths.
Step 4: Generate the report
Present findings as a structured report grouped by category. For each issue:
- Line number - approximate location in the file.
- Category - Voice/Tone, Terminology, Formatting, Content Type, Frontmatter, or Workflow.
- Issue - what is wrong.
- Suggestion - how to fix it.
Report format
## Style review: <file>
### Content type: <type>
### Summary
- X issues found (Y from Vale, Z from manual review)
- Severity: A critical, B suggestions
### Voice and tone
- Line 12: Passive voice - "The value can be set..." → "Set the value..."
### Terminology
- Line 8: "JSON RPC" → Use "JSON-RPC" per terminology.mdc.
### Formatting
- Line 45: Code block missing language tag.
- Line 22: Em dash found - replace with comma or period.
### Content type
- Page is in `concepts/` but contains numbered step-by-step instructions. Move steps to a
how-to page and link to it.
### Frontmatter
- Missing `description` field.
If reviewing a directory, produce one report per file, then a summary at the end showing totals
across all files.
If no issues are found, say so explicitly.
