style-review

name	style-review
description	Review Besu 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 area and content type

Read the file path to determine:

1. Documentation area - whether the file lives in docs/public-networks/ or docs/private-networks/. Load the corresponding rule from .cursor/rules/product-public-networks.mdc or .cursor/rules/product-private-networks.mdc.
2. 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 (Besu, JSON-RPC, etc.).
• Consensus protocol names use correct casing (IBFT 2.0, QBFT, Clique).
• Standards spelled out on first use with identifier in parentheses (for example, "Ethereum Improvement Proposal 1559 (EIP-1559)"), short form on subsequent references.
• Area-specific terminology matches the corresponding product-*.mdc rule file.

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 (autogenerated sidebars; check sidebar_position or _category_.json).
• 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:

1. Line number - approximate location in the file.
2. Category - Voice/Tone, Terminology, Formatting, Content Type, Frontmatter, or Workflow.
3. Issue - what is wrong.
4. Suggestion - how to fix it.

Report format

## Style review: <file>

### Area: <public-networks or private-networks> | 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 block number can be specified..." → "Specify the block number..."

### Terminology
- Line 8: "IBFT2" → Use "IBFT 2.0" 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.