docs-review

What this skill does

# Documentation Review Skill
# Metabase Writing Style Guide

## Core Principles

Write like you're talking to a colleague. Be conversational, not formal. Get people what they need quickly. Know your audience and match the complexity.

## Tone and Voice

**Do:**

- Use contractions ("can't" not "cannot")
- Say "people" or "companies" instead of "users"
- Be friendly but not peppy
- Acknowledge limitations honestly ("that's on us, not them")
- Jokes and Easter eggs are okay (permit them, don't suggest them)

**Don't:**

- Use exclamation points excessively
- Rely on tired tropes about nerdiness
- Use corporate jargon ("utilize", "offerings", "actionable insights")
- Tell people something is cool (show them instead)

## Structure and Clarity

**Lead with the important stuff:**

- Most important information first
- Lead with the ask, then provide context
- Cut text that adds little value (when in doubt, cut it)
- Each paragraph should have one clear purpose

**Make headings do the work:**

- Convey your actual point, not just the topic
- "Use headings to highlight key points" not "How to write a good heading"
- Use sentence case, no punctuation except question marks
- No links in headings unless entire heading is a link

## Instructions and Examples

**Tell people what to do:**

- Give the action before explaining why
- Put commands in execution order
- Provide context, steps, and reasoning
- Don't describe tasks as "easy" or "simple"

**Answer unasked questions:**

- Include answers to "dumb" questions you had when learning
- Don't literally include the question, just give the answer

## Formatting

**Code vs. UI elements:**

- Backticks for code, variable names, parameters only
- **Bold** for UI elements and labels (e.g., "Click the **Save** button")
- Don't use backticks or quotes for UI elements

## Writing Mechanics

- Limit pronouns when introducing new terms (repeat the term to reinforce it)
- Ampersands only in proper nouns, never as substitute for "and"

## Terminology Preferences

Use familiar terms from tools people already know:

- "Summarize" (like Excel) instead of "aggregate"
- "Take a look at" instead of "reference"
- "Filter" instead of technical database terms when appropriate

## Red Flags

Avoid these patterns:

- Multiple exclamation points
- Linking "here"
- Bullet lists to explain (use prose)
- Numbers that will change (guard against change)
- Describing things as "easy" or "simple"
- Stock photography-worthy content

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

**Code and examples:**

- [ ] Code examples that don't work or would error
- [ ] Commands not in execution order
- [ ] Full-width screenshots instead of scoped UI elements
- [ ] Excessive or unnecessary images

**Sentence construction:**

- [ ] Overuse of pronouns when introducing new terms

## Quick scan table

| Pattern                       | Issue                                         |
| ----------------------------- | --------------------------------------------- |
| we can do X, our feature      | Should be "Metabase" or "it"                  |
| click here, read more here    | Need descriptive link text                    |
| easy, simple, just            | Remove condescending qualifiers               |
| users                         | Should be "people" or "companies" if possible |

## Feedback format

**MANDATORY REQUIREMENT: Every single issue MUST be numbered sequentially starting from Issue 1.**

This numbered format is NON-NEGOTIABLE. It allows users to efficiently reference specific issues (e.g., "fix issues 1, 3, and 5") and track which feedback has been addressed.

### Local review mode format

When outputting issues in the conversation (local mode), use this format:

```markdown
## Issues

**Issue 1: [Brief title]**
Line X: Succinct description of the issue
[code or example]
Suggested fix or succinct explanation

**Issue 2: [Brief title]**
Line Y: Description of the issue
Suggested fix or explanation

**Issue 3: [Brief title]**
...
```

**Examples:**

> **Issue 1: Formal tone**
> Line 15: This could be more conversational. Consider: "You can't..." instead of "You cannot..."

> **Issue 2: Vague heading**
> Line 8: The heading could be more specific. Try stating the point directly: "Run migrations before upgrading" vs "Upgrade process"

### PR review mode format

When posting to GitHub (PR mode), use the **pending review workflow**:

**Workflow steps:**

1. **Start a review**: Use `mcp__github__create_pending_pull_request_review` to begin a pending review
   - This creates a draft review that won't be visible until submitted

2. **Get diff information**: Use `mcp__github__get_pull_request_diff` to understand the code changes and line numbers
   - This helps you determine the correct file paths and line numbers for comments

3. **Identify ALL issues**: Read through all changes and identify every issue worth mentioning
   - Collect all issues before posting any comments
   - Number them sequentially (Issue 1, Issue 2, Issue 3, etc.)

4. **Add review comments**: Use `mcp__github__add_pull_request_review_comment_to_pending_review` for each issue
   - **CRITICAL**: Post ALL comments in a SINGLE response using multiple tool calls in parallel
   - Each comment should reference a specific file path and line number from the diff
   - Start each comment body with `**Issue N: [Brief title]**`
   - Include the description and suggested fix

5. **Submit the review**: Use `mcp__github__submit_pending_pull_request_review` to publish all comments at once
   - Use event type `"COMMENT"` (NOT "REQUEST_CHANGES") to make it non-blocking
   - **Do NOT include a body message** - Leave the body empty or omit it entirely
   - All comments will appear together as one cohesive review

**Comment format example:**

```
**Issue 1: Formal tone**

This could be more conversational. Consider: "You can't..." instead of "You cannot..."
```

**IMPORTANT**:
- Each issue gets its own review comment attached to the pending review
- Number ALL comments sequentially (Issue 1, Issue 2, Issue 3, etc.)
- Always start the comment body with `**Issu