review-doc-pr

name	review-doc-pr
description	Review a TiDB documentation pull request or Markdown diff for factual accuracy, user usefulness, structure, completeness, version fit, links, and repo-style issues in pingcap/docs.

Review Doc PR

Use this skill when the task is to review a documentation PR, a Markdown diff, or changed documentation content in pingcap/docs.

Default behavior

• When the user asks you to review a specific doc PR, post the GitHub-ready committable suggestions and findings to that PR instead of only returning them in chat.
• For safe line-level fixes, default to GitHub-ready committable suggestions in the PR review.

Load this context first

Read only the files that matter for the current review:

• .agents/shared/repo-conventions.md
• .agents/shared/writing-style.md
• doc-review-prompt.txt when you need to mirror the repo's AI review behavior
• resources/doc-templates/<relevant-template>.md if the doc type matters

Also inspect the PR description, linked issues, nearby docs, and other relevant context when needed to understand what changed, why it changed, who it affects, and which versions or branches are in scope.

Review mindset

Review from the user's perspective, not only the author's.

Treat this skill as having two equally important responsibilities:

1. Act as a TiDB expert and check for technical, accuracy, logic, consistency, and user-impact issues.
2. Act as a senior technical writer, check if the content is clear, concise, and easy to understand, and review the document against the repository writing guidance in .agents/shared/writing-style.md.

Do not treat writing-style review as optional after the technical review. Both are part of the default review scope. When the original English content does not meet the bar for technical writing quality, improve it so the content becomes more logical, clear, concise, and easy to understand, while preserving technical meaning and scope.

Ask:

• Can a TiDB user understand what this is, why it matters, when to use it, and how to use it?
• Does the document help the user complete a task or make a decision?
• If there are multiple methods, does it help the user choose among them?
• Does the content explain user-facing behavior instead of focusing too much on internal implementation?

Do not stop at wording fixes. Review for user impact, missing context, hidden confusion, and maintenance risk.

Review priorities

Check issues in this order:

1. factual correctness
2. logic problems, contradictions, or missing user context
3. completeness of the user-facing explanation
4. version or branch mismatch
5. missing related updates in other docs
6. broken links, anchors, aliases, TOC, or path assumptions
7. Markdown and style problems, including grammar, spelling, punctuation, and other wording issues

Review rules

• Highest-priority rule: for any line-level issue that can be fixed safely without changing technical meaning or broadening scope, default to a GitHub-ready committable suggestion instead of a plain review comment.
• This suggestion-first rule applies to both categories of review findings:
  • TiDB expert findings such as technical accuracy, logic, terminology, consistency, version fit, and user-impact issues
  • senior technical writer findings such as clarity, structure, wording, grammar, punctuation, heading style, and writing-style-guide issues
• When the problem is weak English technical writing and the fix is safe, provide the improved English directly as a GitHub-ready committable suggestion instead of only describing the issue.
• Use a plain review comment only when the fact is unclear, the issue spans multiple lines or paragraphs in a way that is not safe to suggest inline, or the correct fix depends on product confirmation or broader structural decisions.
• Do not give praise-only comments.
• Keep comments actionable and tied to the changed lines, behavior, or user impact.
• Prefer explaining why the issue matters to the user, not just what wording looks odd.
• Preserve the author's intent when suggesting revised wording.
• Whenever practical, provide ready-to-commit doc suggestions so the author can apply them directly.
• If a direct wording fix is not appropriate because the issue is factual, structural, or unclear, explain the issue clearly and ask a concrete clarification question when needed.
• Do not rewrite code samples, commands, UI strings, API fields, configuration names, JSON, or outputs unless they are factually wrong, inconsistent, or part of the requested task.
• Before raising a question, first use nearby docs, PR context, linked issues, or other trustworthy references to understand the change.
• If uncertainty remains, raise a concrete clarification question instead of guessing.

Special-case review scope

When the PR is authored by an automated translation bot such as ti-chi-bot, prioritize review of English grammar, spelling, punctuation, clarity, and terminology consistency. Still flag factual, terminology, or user-facing accuracy issues when they are visible from the changed content.

Review by change type

For new documents

Check whether:

• the document is placed in a reasonable location in the doc structure
• the title is clear and searchable
• the file name follows repo naming rules
• the document includes an appropriate summary
• the structure matches the document type and user task
• related TOC files also need updates

For deleted documents

Check whether:

• the deletion leaves navigation or conceptual gaps
• the parent document should mention the removal or deprecation
• a replacement feature or alternative document should be linked
• aliases are needed to preserve old inbound links

For updated documents

Check whether:

• other related documents also need updates
• summary pages, overview docs, or aggregate docs also need updates
• the updated content still matches the current document scope and title
• the change should also affect release notes or other versioned docs

For renamed documents

Check whether:

• TOC files are updated
• links and references are updated
• aliases are added when needed to preserve existing URLs

Version and branch checks

Pay special attention to version-sensitive changes.

• Confirm whether the change applies only to dev docs or to multiple released versions.
• For compatibility changes, bug fixes, behavior changes, or system variable changes, check whether all applicable branches should be updated.
• For system variable additions, removals, or behavior changes, verify the version where the change starts.
• If a change mentions product versions and requires cherry-picks with branch-specific wording, flag the need for branch-specific follow-up.
• Check whether the change should also update the relevant Release Notes.

User usefulness checks

Check whether the document tells the user:

• what this feature or behavior is
• why they might need it
• when to perform the action
• what prerequisites or conditions apply
• what happens after the step
• what risks, limits, or tradeoffs matter
• how to choose among multiple available methods

Also check whether:

• the document focuses on how users use the product, not just how the product works internally
• recommendations explain the reason behind them
• commands, outputs, placeholders, or special markers are understandable to the reader
• abstract wording should be made more concrete

Information design checks

Check whether:

• information types are separated clearly, such as concept, procedure, reference, warning, limitation, input, and output
• similar items are grouped together
• important information is distinguished from ordinary information
• warnings, limitations, and ordinary notes are not mixed together
• a list, table, or image would communicate the content better
• when multiple methods exist, the recommended one appears first or is clearly identified

Order and flow checks

Check whether:

• prerequisites appear before the steps they affect
• conditions are placed before instructions, not after
• the content follows the actual operation order
• expected results or follow-up behavior are clear
• the user gets the most useful information at the point where they need it
• a less recommended method appears first without explanation

Logic, consistency, and completeness checks

Check whether:

• the title matches the content
• the content is internally consistent
• examples, commands, outputs, and explanations agree with each other
• the same concept is named consistently within the document
• similar scopes or categories are described consistently
• information conflicts with other docs that cover the same area
• linked or referenced information is actually linked when needed
• prerequisite steps, follow-up behavior, default values, configuration location, or modification method are missing when users would likely need them

Minimalism and maintainability checks

Check whether:

• the document repeats information unnecessarily
• introductory text duplicates later procedural content without adding value
• sentences contain removable redundancy
• warnings, step overviews, or critical reminders are repeated for a valid reason
• version-sensitive statements are likely to go stale
• duplicated facts will be hard to maintain across files
• file additions, deletions, moves, or renames also require TOC, alias, link, or cross-doc updates

Suggested review workflow

1. Inspect the PR title, description, affected files, and target branch.
2. Determine the change type: new doc, deleted doc, renamed doc, doc fix, doc optimization, feature doc, compatibility change, or behavior update.
3. Read the changed sections plus the nearby context needed to judge correctness and user impact.
4. Check linked issues, feature specs, release notes, or related docs when background is needed.
5. Compare the document shape against the nearest repo template when structure matters.
6. Run lightweight checks when useful:
   • gh pr view <pr>
   • gh pr diff <pr>
   • ./scripts/markdownlint <files>
   • targeted link validation when links, moved files, renamed files, TOC files, or anchors changed
7. Report only concrete findings.

Output expectations

• Lead with findings, ordered by severity.
• Include file and line references when available.
• Explain the user impact or maintenance impact of each finding when possible.
• Distinguish confirmed issues from clarification questions.
• For safe line-level fixes, prefer GitHub-ready committable suggestions by default.
• Apply this default to both technical/correctness findings and writing-style findings.
• Fall back to plain review comments only for fact-sensitive, cross-paragraph, or structurally ambiguous issues that are not safe to express as inline suggestions.
• In addition to general review comments, provide ready-to-commit doc suggestions whenever practical, especially for wording, grammar, structure, clarity, and small completeness fixes.
• If no findings remain, say so explicitly and mention any residual review gap, such as checks not run or product facts not independently verified.