Documentation Review Skill

@./../_shared/metabase-style-guide.md

Review mode detection

IMPORTANT: Before starting the review, determine which mode to use:

1. PR review mode: If the mcp__github__create_pending_pull_request_review tool is available, you are reviewing a GitHub PR

   • Use the pending review workflow to post all issues as one cohesive review
   • Follow the workflow steps in "PR review mode format" below

2. Local review mode: If the MCP tool is NOT available, output issues in the conversation

   • Format all issues in a numbered markdown list (as described in "Feedback format" below)

Review process

1. Detect review mode - Check if mcp__github__create_pending_pull_request_review is available
2. Read the changes through once to understand intent
3. Check all issues that violate style guide or significantly impact readability
4. Only flag issues worth mentioning - if it won't make a material difference to the reader, skip it
5. REQUIRED: Number ALL feedback sequentially - Start from Issue 1 and increment for each issue found

Review checklist

Run through the diff looking for these issues:

Tone and voice:

• Formal/corporate language ("utilize" not "use", "offerings", etc.)
• "Users" instead of "people" or "companies"
• Excessive exclamation points or overly peppy tone
• Telling readers something is cool instead of showing them

Structure and clarity:

• Important information buried instead of leading
• Verbose text that adds little value
• Paragraphs without clear purpose
• Vague headings that don't convey the point
• Instructions explain "why" before telling "what to do"
• Tasks described as "easy" or "simple"

Links and references:

• Linking the word "here" instead of descriptive text
• Links in headings (unless entire heading is a link)

Formatting:

• Ampersands as "and" substitute (except proper nouns)
• Inconsistent list formatting