# Style Review

> Review Zesu documentation for editorial compliance (voice, terminology, formatting, content type, frontmatter, workflow). Use before submitting a PR or when asked to audit existing pages.

- Skill: `consensys-incorporated/style-review-2` (Agent Skill)
- Install (CLI): `npx skillmds@latest add consensys-incorporated/style-review-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/consensys-incorporated/style-review-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: consensys-incorporated (https://skillmd.com/u/consensys-incorporated)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/consensys-incorporated/style-review-2

---


# 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 which subfolder it lives in (for example, `concepts/`, `how-to/`,
`reference/`, `get-started/`, or the top-level `troubleshooting.md`). Use
`.cursor/rules/content-types.mdc` for the structural expectations of each type.

Also load `.cursor/rules/product-zesu.mdc` for product-specific conventions.

## Step 2: Run Vale (if available)

Try running Vale on the target file:

```bash
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 (Zesu, Consensys).
- Shared Ethereum and web terms use the required casing (JSON-RPC, web3, dapp, onchain, etc.).
- 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 between pages.
- 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.
- Troubleshooting entries: short, grouped by symptom, link out for longer fixes.

### 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 it has been added to `sidebars.js` in the correct category and
  position (sidebars are manually maintained, not autogenerated).
- If the file was moved or renamed, verify a redirect exists in `vercel.json`.
- Verify no claims are made about Zesu CLI options, configuration, or behavior that have not been
  checked against the codebase or official reference.

## 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>

### 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: "ZESU" → Use "Zesu" 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.

### Workflow
- New page is not listed in `sidebars.js`. Add it under the appropriate category.
```

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.