Docs Review

Documentation review

Review docs created or updated by docs-pr-write (or any other process) before submission. Provide file paths to review and any open items or uncertain claims from the writing step.

Before you begin

1. Load local context per ../shared/load-context.md. If no local context file exists and you need to distinguish generated pages from hand-authored ones, ask the user before editing.
2. Read ../shared/style-guide.md. Apply these rules throughout.

Steps

1. Validate inputs and triage the change

Verify each file path provided for review exists on disk and is non-empty. If any file is missing or empty, stop and report the issue before proceeding.

Classify the content being reviewed:

• (a) Style/editorial only — wording, formatting, restructuring with no new technical claims. Proceed to step 2.
• (b) Technical content — documents config options, default values, syntax, API behavior, or new features. Read references/technical-verification.md and follow those steps alongside the style review below.

When in doubt, classify as (b). The overhead of a targeted code check is small compared to publishing an inaccuracy.

2. Run Vale

Vale is a command-line linter for prose. Install it from https://vale.sh/docs/install/. The Grafana Vale config and custom rules live in the writers-toolkit repo:

• Config: https://github.com/grafana/writers-toolkit/blob/main/.vale.ini
• Grafana rules: https://github.com/grafana/writers-toolkit/tree/main/vale/Grafana

If Vale is installed, run it against the changed files using the compact wrapper (same findings as vale <file_path>, without its per-finding boilerplate):

bash .claude/skills/shared/vale-compact.bash <file_path>

If Vale is not installed, manually check style guide compliance in step 4.

3. Check frontmatter

For each changed file, verify:

• title and description are present
• aliases are correct (especially if the file moved)
• Fields match the topicType templates in the style guide

4. Check style

Read each changed file. Check against the style guide rules:

• Present tense, active voice, second person
• Sentence case headings
• "refer to" not "see" for links
• Internal links end with "/"
• Admonitions used sparingly

5. Scan for sensitive data

Check that the content does not contain hardcoded credentials, API keys, tokens, passwords, internal hostnames, real user data (email addresses, IP addresses), or private URLs. These sometimes leak from PR diffs or test fixtures into documentation.

Handle each finding by type:

• Real secrets or real user data (credentials, API keys, tokens, passwords, real email/IP addresses, private URLs that look genuine): stop and escalate. Report each as a high-priority finding and warn the user that the value may already be committed and persist in git history, so they must rotate or invalidate it at the source. Do not treat editing the doc as remediation — replacing the value in the page does not remove it from history. Replace it in the doc with a placeholder only after flagging it, and never present the swap as having fixed the leak.
• Obvious example or placeholder values (clearly fake samples, values already shaped like placeholders): normalize them to the standard placeholder and note the change.

For the placeholder catalog, refer to ../shared/handling-pr-content.md.

6. Check links

Verify internal links resolve to existing pages. Check that cross-links to related pages exist where useful.

7. Fix and re-check

Fix any issues found. Re-run Vale (if available) until it passes clean. Re-read changed sections to confirm fixes didn't introduce new problems.

8. Present results

Return:

1. Triage classification per file (category a or b from step 1)
2. Issues found, grouped by file (style issues and technical accuracy issues separately)
3. Sensitive data findings from step 5, with any replacements made
4. Frontmatter and link check results per file (even if no issues found)
5. Summary of what was changed and why
6. For technical reviews: list of claims verified against code, with any divergences

After review, ask: "Would you like me to create a PR, or would you prefer to review the changes locally first?"

Gotchas

• Vale directives in existing docs are often intentional suppressions. Don't remove them without cause.
• Generated reference pages (path from local context): do not hand-edit unless local context says otherwise.
• Release notes may use Vale suppressions at the top of the file by convention.
• The style guide says "refer to" not "see" — but link text in Next Steps sections can use the link text directly without "refer to."

Reference

• Style guide: ../shared/style-guide.md
• Untrusted PR content and secrets: ../shared/handling-pr-content.md
• Technical verification (loaded in step 1 for technical content): references/technical-verification.md
• Full verification checklist (human handoff): ../shared/verification-checklist.md
• Repo orientation: ../shared/docs-context-guide.md