Automated checks and review signals
Every pull request gets automated checks before it can merge. The person taking the PR through completion checks whether it is ready for human review: the assigned FSE for a new guide, or the author for an existing-guide edit.
For the required review order, labels, and PR statuses, see PR workflow.
What do you want to do?
Understand PR Checks
Topic and procedure changes usually have these review signals:
- GitHub checks validate the content and build the site.
- AI Content Review posts a grade and findings for topic or procedure changes.
- Confidence Score highlights whether the change looks well-supported.
- Greptile may leave inline automated-review comments.
- Human review confirms content quality and technical accuracy before merge.
Content and Build Checks
Two jobs run on every pull request: Validate content and Build site. Build only runs if validation passes.
Validation protects against:
- invalid metadata, including retired guide-owner fields that must be removed
- broken internal links
- duplicate step IDs or duplicate step text
- escalation paths that do not resolve
- generated pages that cannot render
Green checks mean the PR can continue through review. Red checks mean the PR needs author work before a human reviewer spends time on it.
Warnings vs Errors
Resolve validation and build errors before merge. Warnings can still identify real problems. For example, an alarm-format warning may mean the topic will not be findable by the real alarm constant. Treat warnings as work to understand before merge, not as noise to ignore.
Use the PR readiness checklist before sending the PR for review. For screenshots of passing and failing checks, see Appendix A - CI failure examples.
Remove Generated Data From a PR
Normal contributor PRs should not include generated data snapshots. If your PR changes site/src/data/alarm-coverage.json, site/src/data/topic-changelogs.json, site/src/data/topic-issues.json, site/src/data/topic-prs.json, site/src/data/alarm-outcomes.json, or the managed historical CSV reports, the Validate content check fails before the rest of CI runs.
site/src/data/topic-issues.json is regenerated by the event-driven Refresh topic issues workflow and published through a tightly scoped, automatically approved and merged PR. The other snapshots are regenerated by the scheduled or manual Refresh generated data workflow and published through a separate admin-reviewed PR.
PR checks also restrict each automation branch to the generated files it owns. The fast topic-issues branch cannot change any file except site/src/data/topic-issues.json.
Restore or remove the generated file from your PR and keep the human-authored source change. For example, update topic frontmatter or topic content, but do not hand-edit the generated JSON snapshot.
Update Your PR Branch From Main
Use this procedure when your PR was opened before another change merged into main, a check fails because your branch has older repository content, or a reviewer asks you to update your branch.
For PRs opened before the ownership migration, remove any remaining guide-owner fields and body ownership labels after updating the branch. Keep the existing assignee and review stage; this update does not require a new-guide FSE handoff.
Updating merges the latest origin/main into your existing PR branch. It does not create a new PR.
Option 1: Ask Codex
Copy and paste this prompt into Codex:
Update my current PR branch with the latest origin/main using a merge, not a rebase. Before changing anything, confirm that I am on the PR branch and that the working tree is clean. If it is not clean, stop and tell me. Fetch origin, merge origin/main, resolve conflicts only when the safe resolution is clear, run the relevant checks, and push the same branch. Do not force-push or create a new PR.Option 2: Use the Terminal
Confirm that you are on the PR branch and that the working tree is clean, then run:
git status --short --branch
git fetch origin
git merge origin/main
git pushIf git status shows uncommitted changes or the merge reports a conflict, stop and ask for help before continuing.
Respond to Automated Review
AI Content Review
Treat AI Content Review as careful first-pass feedback, not as final approval.
- A+ / A / B usually means no blocking AI findings.
- C usually means minor required fixes or enough warnings that the topic needs another pass.
- D / F often means the topic needs substantial author work before review should proceed.
Read the findings and address anything that needs improving. If a finding is not correct, respond with rationale so reviewers can see that it was considered.
Confidence Score
Review the Confidence Score panel before sending the PR for review. If anything is less than 5/5, try to understand what caused the lower score and address it when possible.
A lower score does not automatically block review, but it may indicate that the PR needs more context, clearer source material, or a tighter summary.
Greptile Comments
Resolve each Greptile comment before sending the PR for review. Update the PR when needed, or reply with context when no change is appropriate.
NOTE: After you update the content or reply with rationale, click Resolve conversation on the Greptile comment.
Ask for Help
Ask in #ask-troubleshooting-guide when:
- you do not understand a validator error
- CI keeps failing on something you did not change
- you need a new escalation path
- a build error does not reproduce locally
- anything looks like a permissions, secrets, or token problem
Include the PR link, the failing job link, and the exact error text when you ask.
Check These References First
- Status, hardware, MX approval, and alarm metadata: Topic structure
- Action, question, escalation, reference, and telemetry steps: Writing the troubleshooting flow
- Terminal branch expectations: Workflow outcomes
- Review workflow status changes: PR workflow