AI-assisted documentation review for Kagenti PRs — structure, accuracy, links, conciseness
flowchart TD
START([docs:review]) --> GATHER["Phase 1: Gather changed docs"]
GATHER --> ANALYZE["Phase 2: Analyze each file"]
ANALYZE --> REPORT["Phase 3: Report findings"]
REPORT --> SUBMIT["Phase 4: Post review"]
Follow this diagram as the workflow.
AI-assisted review of documentation changes in Kagenti PRs. Checks structure,
accuracy, links, conciseness, and consistency against the meta:write-docs (planned)
standards. Use alongside the automated Docs CI workflow (markdownlint, lychee)
for comprehensive coverage.
docs/** or *.md files/docs:review <PR-number> or /docs:review (auto-detects current PR)export LOG_DIR=/tmp/kagenti/docs-review/$PR_NUMBER
mkdir -p $LOG_DIR
# Get list of changed markdown files
gh pr diff <PR-number> --name-only | grep '\.md$' > $LOG_DIR/changed-files.txt
# Save the full diff for context
gh pr diff <PR-number> > $LOG_DIR/pr.diff 2>&1
If no .md files are changed, report "No documentation changes found" and stop.
For each changed markdown file, read the full file and check against these categories. Use subagents for large PRs (>5 files changed).
# title at the top of the file--- horizontal rules between major sections## to ####)gh release list output)ls or find to verify)[text](../path.md)) point to existing files[text](#heading)) resolve to actual headings in the target file[descriptive text](url) formatbash, yaml, text)> **Note:**, > **Warning:**, > **Tip:**)meta:write-docs (planned) are followedProduce a structured summary grouped by severity:
## Documentation Review: PR #<number>
### Files reviewed
- `docs/install.md` (modified)
- `docs/releasing.md` (new)
### Issues found
#### Must fix
- **docs/install.md:42** — Broken anchor link `#choosing-a-version` (heading was renamed)
- **docs/releasing.md:15** — YAML snippet has incorrect indentation
#### Suggestions
- **docs/releasing.md:78** — This paragraph could be condensed to a bullet list
- **docs/install.md:130** — Consider adding `git checkout` step to the OpenShift clone block
#### Looks good
- Structure follows `meta:write-docs` (planned) template
- All shell commands are syntactically valid
- Version numbers match current releases
| Severity | Meaning | Action |
|---|---|---|
| Must fix | Broken links, invalid commands, incorrect information | Block merge |
| Suggestion | Style improvements, conciseness, missing context | Optional |
| Looks good | Positive observations worth noting | Informational |
Present the review to the user. If the user approves, post as a GitHub PR review:
# Post as a review comment (not inline, to avoid noise on large PRs)
gh pr review <PR-number> --comment --body "$(cat $LOG_DIR/review-summary.md)"
For critical issues, use --request-changes instead of --comment.
Quick reference for the complete review criteria:
---) between major sectionsmeta:write-docs (planned) conventionsmeta:write-docs (planned) — Documentation writing standards and templatesgithub:pr-review — General PR review workflow (code + docs)repo:pr — PR creation conventions