// Review documentation changes for style, accuracy, and completeness. Use when docs have been written or updated and need a quality check before submission.
| name | docs-review |
| description | Review documentation changes for style, accuracy, and completeness. Use when docs have been written or updated and need a quality check before submission. |
| allowed-tools | Bash Read Grep |
Review docs created or updated by docs-pr-write (or any other process) before submission.
Invoke with /docs-review.
Provide:
Read .agents/doc-agents/shared/style-guide.md. Apply these rules throughout.
Classify the content being reviewed:
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.
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:
If Vale is installed, run it against the changed files:
vale <file_path>
If Vale is not installed, manually check style guide compliance in step 5.
For each changed file, verify:
title and description are presentaliases are correct (especially if the file moved)Read each changed file. Check against the style guide rules:
Verify internal links resolve to existing pages. Check that cross-links to related pages exist where useful.
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.
Return:
After review, ask: "Would you like me to create a PR, or would you prefer to review the changes locally first?"
<!-- vale Grafana.We = NO -->) are intentional suppressions. Don't remove them.manifest.md is auto-generated. Don't review or edit it..agents/doc-agents/shared/style-guide.mdreferences/technical-verification.md.agents/doc-agents/shared/verification-checklist.md.agents/doc-agents/shared/docs-context-guide.mdResolve vendor/ conflicts during a merge, rebase, or dependency upgrade on main or release branches
Assess documentation status for each PR in a Tempo release — classify gaps and identify existing docs that need updating
Write or update Tempo docs for user-facing PR changes identified by docs-pr-check
End-to-end workflow for PR documentation — check, write, review. Use at any stage of documenting PR changes.
Update Go version across the Tempo codebase (go.mod, tools/go.mod, Dockerfile, CI workflows, tools image tag)