Review a Pull Request
Review PR $ARGUMENTS and produce a confidence score for merge readiness.
Phase 1: Gather PR Context
# PR metadata
gh pr view $ARGUMENTS --json title,body,author,labels,files,additions,deletions,baseRefName,headRefName,state,isDraft,number
# Changed files list
gh pr diff $ARGUMENTS --name-only
# Full diff
gh pr diff $ARGUMENTS
# CI status
gh pr checks $ARGUMENTS
Phase 2: Classify PR Type
Determine the PR type from changed files and metadata:
| Type |
Detection |
Check scope |
| docs-only |
All files are *.md, docs/**, **/stories/**, **/.storybook/** |
Change file only |
| test-only |
All files are *.test.*, *.spec.*, **/testing/** |
Change file + test quality |
| bug-fix |
Branch starts with fix/ or title contains "fix" |
All checks, extra weight on tests |
| feature |
Branch starts with feat/ or adds new exports |
All checks, extra weight on API + patterns |
| refactor |
No new exports, restructures existing code |
All checks, extra weight on no behavior change |
| config/infra |
Changes to CI, configs, scripts only |
Change file + no regressions |
For v8 packages (packages/react/): skip V9 pattern checks — those are maintenance-only with different patterns.
For web-components (packages/web-components/): skip React-specific checks.
Phase 3: Run Checks
Run each check category. For each finding, assign a severity:
- BLOCKER — must fix before merge
- WARNING — should address
- INFO — consider
A. Beachball Change File
Required if any published package source code changed (not just tests/stories/docs).
- Check
change/ directory in the diff for new .json files
- Verify change type:
patch for fixes, minor for features, never major without explicit approval
- Not required for changes that only affect tests, stories, docs, or snapshots
BLOCKER if missing for published source changes.
B. V9 Component Pattern Compliance
Only for files in packages/react-components/react-*/library/src/:
| Check |
Look for |
Severity |
No React.FC |
React.FC, : FC<, React.FunctionComponent in added lines |
BLOCKER |
| No hardcoded styles |
Hex colors #[0-9a-fA-F]{3,8}, hardcoded px values for spacing/radius/font in .styles.ts files |
WARNING |
| Griffel usage |
Style files must use makeStyles from @griffel/react, not inline styles |
WARNING |
| mergeClasses order |
User className must be the LAST argument in mergeClasses() |
WARNING |
| Slot system |
New components must use slot.always/slot.optional and assertSlots |
WARNING |
Reference: docs/architecture/component-patterns.md
C. Dependency Layer Violations
For changes to package.json files or new imports in Tier 3 component packages:
- BLOCKER if a Tier 3 package (
react-button, react-menu, etc.) adds a dependency on another Tier 3 package
- Allowed Tier 2 deps:
react-utilities, react-theme, react-shared-contexts, react-tabster, react-positioning, react-portal
- Allowed Tier 1 deps:
@griffel/react, @fluentui/tokens, @fluentui/react-jsx-runtime
Reference: docs/architecture/layers.md
D. SSR Safety
Grep added lines for unguarded browser API access:
| Pattern |
Severity |
window. without canUseDOM or typeof window guard nearby |
BLOCKER |
document. without guard |
BLOCKER |
navigator. without guard |
BLOCKER |
localStorage / sessionStorage without guard |
BLOCKER |
instanceof HTMLElement |
WARNING |
Check 3 lines above each match for a guard (canUseDOM, typeof window !== 'undefined').
E. Testing
| Check |
Severity |
Source files changed but no corresponding .test.tsx changes |
WARNING |
New component missing testing/isConformant.ts |
WARNING |
Snapshot files need updating (render/style changes without .snap updates) |
INFO |
F. API Surface
| Check |
Severity |
Public API changed but etc/*.api.md not updated |
WARNING |
| Existing exports removed (breaking change) |
BLOCKER |
| New exports added (flag for human review) |
INFO |
G. Accessibility
| Check |
Severity |
Existing aria-* attributes removed |
BLOCKER |
onClick without onKeyDown/onKeyUp handler |
WARNING |
Interactive elements missing role or aria-* |
WARNING |
Images/icons without aria-label or aria-hidden |
WARNING |
H. Security and Quality
| Check |
Severity |
eval() or new Function() |
BLOCKER |
dangerouslySetInnerHTML |
WARNING |
console.log / debugger in production code |
WARNING |
// @ts-ignore without explanation |
WARNING |
any type in new code |
INFO |
I. Documentation coverage
A code change frequently lands something that someone downstream needs to learn about. The "someone" splits into two audiences with very different reading habits, so this check actually walks two passes:
- Pass 1 — user-facing docs. Component consumers (storybook stories, migration guides, docsite, MDX, change-file comments).
- Pass 2 — harness / agent-facing docs. Future agent sessions reading the skills,
AGENTS.md, docs/workflows/*, and docs/architecture/*. When a PR changes a build target, a script, a CI step, a label taxonomy, a project-board field, or an assumption that a skill makes, the skill or harness doc has to be updated in the same PR — otherwise every fresh /triage-issues, /visual-test, /review-pr, etc. invocation pays the discovery cost over again.
Both passes ask the same two questions: should this PR have updated docs, and if so, did it? Bug fixes that restore documented behavior, internal refactors, and test-only PRs default to PASS in both passes — the interesting cases are below.
Pass 1 — user-facing docs
| Source change |
Expected doc surface |
New prop on a public component (added in *.types.ts) |
A Storybook story or MDX entry under packages/react-components/react-<name>/stories/ that exercises the prop |
New public export added to a library/src/index.ts barrel |
A story or MDX entry covering it (or a justified note in the PR body) |
New component package (new directory under packages/react-components/react-*) |
Stories package, library/docs/Spec.md, and an entry on the docsite (apps/public-docsite-v9) |
Behavior change to a public API's defaults (e.g. a new conditional in use*_unstable that changes observable output) |
Mention in library/docs/MIGRATION.md or a "BREAKING CHANGE / behavior change" section in the PR body |
| Removal or deprecation of a public export |
library/docs/MIGRATION.md entry and/or a @deprecated JSDoc on the symbol |
| New design token, classname constant, or CSS custom property |
A line in the relevant docs (often the component's stories MDX) explaining how to use/override it |
Pass 2 — harness engineering / agent-facing docs
This pass exists because skills are part of the contract, not just convenience. When the skills are stale, the agents are wrong — quietly. Symptoms: a /visual-test invocation that points at a nonexistent project name, a /triage-issues flow that recommends a label the repo no longer has, a /triage-board skill that misses a new view filter the maintainers added.
Walk the diff for any of these and check whether the matching agent-facing doc was updated:
| Source change |
Expected harness update |
New / renamed nx target (project.json, nx.json, generators) |
Any skill that invokes that target — visual-test, lint-check, package-info, v9-component. The skill literally types the target name; it's not auto-discovered. |
New / renamed top-level package.json script |
Same. Plus docs/workflows/contributing.md if it's contributor-facing. |
New label, label rename, or label taxonomy change in the repo (gh api repos/.../labels) |
triage-issues/references/triage-labels.md — the skill uses an allow-list and gh issue edit rejects unknown labels. |
| New / changed project-board field, view filter, or option ID |
triage-board/references/team-mapping.md (option IDs) and the view-filter mirror in triage-board/SKILL.md. |
| New convention contributors are expected to follow (file layout, naming, "always do X") |
AGENTS.md / CLAUDE.md (they're symlinked) — the rules section is the agent's first read. |
| New layered dependency rule, package-tier reshuffle, or CODEOWNERS rewrite |
docs/architecture/layers.md, docs/team-routing.md, plus triage-board/references/team-mapping.md if a CODEOWNERS handle gained or lost a confident mapping. |
New first-time-setup requirement (e.g. a workspace package whose lib-commonjs/ must be pre-built) |
docs/workflows/contributing.md "First-time setup" section AND the troubleshooting block of any skill that hits the failure mode (visual-test already does this for the unstable-deps case). |
New skill, agent hook, or .claude/-level configuration |
AGENTS.md skills table + the .claude/skills/<name>/SKILL.md bridge file. |
| Removal or move of a path that any skill greps for or hard-codes |
The skill that referenced it. Search the skills (grep -rn "<old-path>" .agents/skills/) before merging. |
Authentication / token-scope / permission changes that affect gh calls |
The skill's preflight section. Concrete past examples: the EMU vs non-EMU active-account gotcha and the read:project vs project scope distinction now baked into triage-board's preflight. |
| New external-tool name or behavior change (e.g. assignee identity for an automated agent) |
The relevant skill. Concrete past example: assigning to Copilot literally fails with "Bot does not have access" — only copilot-swe-agent works. That belongs in any skill that assigns to Copilot. |
When docs are NOT expected (default to PASS)
- Pure bug fix that restores documented behavior
- Internal refactor with no exported-symbol or behavior change
- Build / CI changes that have no contributor-facing or skill-facing impact
- Test-only PRs
- Style-only PRs (typo, formatting) on internal code
Severity
| Situation |
Severity |
Public export removed or behavior-changed without MIGRATION.md entry |
BLOCKER |
| Skill references a renamed or removed path / target / label that this PR changes (skill will literally fail next run) |
BLOCKER |
| New public component / new public hook with no story or MDX |
WARNING |
| New public prop with no story exercising it |
WARNING |
| New design token / className constant with no usage example |
WARNING |
| Behavior change to public defaults with no PR-body callout |
WARNING |
New label / project field / nx target / convention without the matching skill or AGENTS.md / docs/workflows/ update |
WARNING |
New first-time-setup requirement without contributing.md mention |
WARNING |
| PR description explicitly defers docs to a follow-up (link cited) |
INFO |
| Docs / harness change exists but feels minimal — could be more thorough |
INFO |
How to actually run this check
The model should walk the diff, not guess.
- Group changed files into surfaces. Code surfaces (
library/src/**, index.ts barrels, *.types.ts); user-doc surfaces (stories/**, library/docs/**, apps/public-docsite-v9/**); harness surfaces (.agents/skills/**, .claude/**, AGENTS.md, CLAUDE.md, docs/workflows/**, docs/architecture/**, docs/team-routing.md, project.json, nx.json, root package.json scripts, .github/CODEOWNERS, .github/labeler.yml).
- If the PR is purely a doc/harness surface, the check is PASS — it's documentation already.
- For each row in the user-facing table that matches a code change in the diff, verify the corresponding doc surface was also touched. If not, raise the matching severity.
- For each row in the harness-engineering table that matches, verify the corresponding skill or harness doc was also touched. Be specific: name the skill that needs updating, not just "a skill."
- Cross-search: when a PR renames a path, target, or label, run
grep -rn "<old-name>" .agents/skills/ docs/ AGENTS.md to find references that will break. Anything that turns up is a BLOCKER unless this PR also updates it.
- Read the PR body before reporting. Authors often pre-empt with "docs follow-up tracked in #NNNN" or "harness skills updated in commit X" — those move findings from WARNING to INFO when the deferral is explicit and reasonable.
Phase 4: Calculate Confidence Score
Start at 100
For each BLOCKER: -25 points
For each WARNING: -5 points
For each INFO: -1 point
Bonuses:
+5 if tests added/updated alongside source changes
+3 if change file present and well-described
+2 if PR description is thorough
Floor at 0, cap at 100.
Score interpretation:
- 90–100: High confidence — safe to merge
- 70–89: Moderate confidence — minor concerns
- 50–69: Low confidence — needs attention
- 0–49: Not safe to merge — blockers present
Phase 5: Produce Output
Use this exact format (also used verbatim as the PR-comment body in Phase 6 — don't duplicate work).
Start directly with the score. Skip a header title, author, type, packages-affected, and CI-status preamble — when this is posted as a PR comment, all of that is already visible in the GitHub UI immediately above the comment, so repeating it just pushes the actually-useful content (score + findings) below the fold. The classification work from Phase 2 still happens; it just isn't echoed back at the reader.
### Confidence Score: <score>/100
<one-sentence summary>
### Findings
#### Blockers (must fix before merge)
- [ ] <finding with file:line reference>
#### Warnings (should address)
- [ ] <finding with file:line reference>
#### Info (consider)
- <finding>
### Category Breakdown
| Category | Status | Notes |
|----------|--------|-------|
| Change file | PASS/FAIL | ... |
| V9 patterns | PASS/WARN | ... |
| Dep layers | PASS/FAIL | ... |
| SSR safety | PASS/WARN | ... |
| Testing | PASS/WARN | ... |
| API surface | PASS/WARN | ... |
| Accessibility | PASS/WARN | ... |
| Security/Quality | PASS/WARN | ... |
| Docs coverage | PASS/WARN/FAIL | ... |
### Recommendation
APPROVE / REQUEST_CHANGES / COMMENT
<brief rationale>
Phase 6: Post the review back to the PR
After presenting the output in the chat, post the same text as a comment on the PR so the review is visible to maintainers and to Copilot (when the PR author is copilot-swe-agent, the comment becomes actionable feedback).
Save the output from Phase 5 to a temp file so the markdown isn't mangled by shell quoting, then:
gh pr comment $ARGUMENTS --repo microsoft/fluentui --body-file /tmp/pr-review-$ARGUMENTS.md
Append a single trailer line to the body so the post is identifiable:
---
*Posted via the `/review-pr` skill.*
The posted comment should be identical to what you rendered in chat — don't paraphrase or summarize. The chat output and the PR comment must match so the user can trust that what they saw is what the maintainers see.
Pre-checks before posting:
- Confirm the active
gh account has write access to the PR's repo (EMU accounts read fine but silently fail on writes):gh api graphql -f query='{ viewer { login } repository(owner:"microsoft", name:"fluentui") { viewerPermission } }'
If viewerPermission is NONE, stop and ask the user to gh auth switch --user <non-emu-account>.
- Don't post on PRs from your own branches unless explicitly asked — self-review comments are noise.
- If
REQUEST_CHANGES is the recommendation, still post the comment but note to the user that only a formal review (gh pr review --request-changes) actually blocks merge; a comment is advisory.
When to skip posting:
- The user explicitly asks for a review without posting ("review but don't post").
- The PR has an existing comment from this skill within the last day on the same head SHA — avoid duplicate noise. Look for the
*Posted via the \/review-pr` skill.*` trailer.
- Draft PRs where the user is clearly still iterating (state=OPEN, isDraft=true, recent force-push) — offer to post but don't do it by default.
Notes
- For large PRs (50+ files), prioritize: published source files > test files > config. Note reduced confidence due to review scope.
- Draft PRs: still review but note WIP status.
- Merge conflicts: flag as BLOCKER if detected.
- The
### Confidence Score: NN/100 line must always appear on its own line for machine parsing.
1---2name: review-pr3description: Review a PR for correctness, pattern compliance, testing, accessibility, and safety. Produces a confidence score for merge readiness.4argument-hint: <PR-number-or-branch>5allowed-tools: Bash Read Grep Glob6metadata:7 source: https://skillmd.com/skills/microsoft/review-pr8---910# Review a Pull Request1112Review PR **$ARGUMENTS** and produce a confidence score for merge readiness.1314## Phase 1: Gather PR Context1516```bash17# PR metadata18gh pr view $ARGUMENTS --json title,body,author,labels,files,additions,deletions,baseRefName,headRefName,state,isDraft,number1920# Changed files list21gh pr diff $ARGUMENTS --name-only2223# Full diff24gh pr diff $ARGUMENTS2526# CI status27gh pr checks $ARGUMENTS28```2930## Phase 2: Classify PR Type3132Determine the PR type from changed files and metadata:3334| Type | Detection | Check scope |35| ---------------- | -------------------------------------------------------------------- | ---------------------------------------------- |36| **docs-only** | All files are `*.md`, `docs/**`, `**/stories/**`, `**/.storybook/**` | Change file only |37| **test-only** | All files are `*.test.*`, `*.spec.*`, `**/testing/**` | Change file + test quality |38| **bug-fix** | Branch starts with `fix/` or title contains "fix" | All checks, extra weight on tests |39| **feature** | Branch starts with `feat/` or adds new exports | All checks, extra weight on API + patterns |40| **refactor** | No new exports, restructures existing code | All checks, extra weight on no behavior change |41| **config/infra** | Changes to CI, configs, scripts only | Change file + no regressions |4243For **v8 packages** (`packages/react/`): skip V9 pattern checks — those are maintenance-only with different patterns.44For **web-components** (`packages/web-components/`): skip React-specific checks.4546## Phase 3: Run Checks4748Run each check category. For each finding, assign a severity:4950- **BLOCKER** — must fix before merge51- **WARNING** — should address52- **INFO** — consider5354### A. Beachball Change File5556Required if any published package source code changed (not just tests/stories/docs).5758- Check `change/` directory in the diff for new `.json` files59- Verify change type: `patch` for fixes, `minor` for features, never `major` without explicit approval60- Not required for changes that only affect tests, stories, docs, or snapshots6162**BLOCKER** if missing for published source changes.6364### B. V9 Component Pattern Compliance6566Only for files in `packages/react-components/react-*/library/src/`:6768| Check | Look for | Severity |69| ------------------- | --------------------------------------------------------------------------------------------------- | -------- |70| No `React.FC` | `React.FC`, `: FC<`, `React.FunctionComponent` in added lines | BLOCKER |71| No hardcoded styles | Hex colors `#[0-9a-fA-F]{3,8}`, hardcoded `px` values for spacing/radius/font in `.styles.ts` files | WARNING |72| Griffel usage | Style files must use `makeStyles` from `@griffel/react`, not inline styles | WARNING |73| mergeClasses order | User `className` must be the LAST argument in `mergeClasses()` | WARNING |74| Slot system | New components must use `slot.always`/`slot.optional` and `assertSlots` | WARNING |7576Reference: [docs/architecture/component-patterns.md](../../../docs/architecture/component-patterns.md)7778### C. Dependency Layer Violations7980For changes to `package.json` files or new imports in Tier 3 component packages:8182- **BLOCKER** if a Tier 3 package (`react-button`, `react-menu`, etc.) adds a dependency on another Tier 3 package83- Allowed Tier 2 deps: `react-utilities`, `react-theme`, `react-shared-contexts`, `react-tabster`, `react-positioning`, `react-portal`84- Allowed Tier 1 deps: `@griffel/react`, `@fluentui/tokens`, `@fluentui/react-jsx-runtime`8586Reference: [docs/architecture/layers.md](../../../docs/architecture/layers.md)8788### D. SSR Safety8990Grep added lines for unguarded browser API access:9192| Pattern | Severity |93| ------------------------------------------------------------- | -------- |94| `window.` without `canUseDOM` or `typeof window` guard nearby | BLOCKER |95| `document.` without guard | BLOCKER |96| `navigator.` without guard | BLOCKER |97| `localStorage` / `sessionStorage` without guard | BLOCKER |98| `instanceof HTMLElement` | WARNING |99100Check 3 lines above each match for a guard (`canUseDOM`, `typeof window !== 'undefined'`).101102### E. Testing103104| Check | Severity |105| --------------------------------------------------------------------------- | -------- |106| Source files changed but no corresponding `.test.tsx` changes | WARNING |107| New component missing `testing/isConformant.ts` | WARNING |108| Snapshot files need updating (render/style changes without `.snap` updates) | INFO |109110### F. API Surface111112| Check | Severity |113| ------------------------------------------------- | -------- |114| Public API changed but `etc/*.api.md` not updated | WARNING |115| Existing exports removed (breaking change) | BLOCKER |116| New exports added (flag for human review) | INFO |117118### G. Accessibility119120| Check | Severity |121| -------------------------------------------------- | -------- |122| Existing `aria-*` attributes removed | BLOCKER |123| `onClick` without `onKeyDown`/`onKeyUp` handler | WARNING |124| Interactive elements missing `role` or `aria-*` | WARNING |125| Images/icons without `aria-label` or `aria-hidden` | WARNING |126127### H. Security and Quality128129| Check | Severity |130| --------------------------------------------- | -------- |131| `eval()` or `new Function()` | BLOCKER |132| `dangerouslySetInnerHTML` | WARNING |133| `console.log` / `debugger` in production code | WARNING |134| `// @ts-ignore` without explanation | WARNING |135| `any` type in new code | INFO |136137### I. Documentation coverage138139A code change frequently lands something that **someone downstream** needs to learn about. The "someone" splits into two audiences with very different reading habits, so this check actually walks two passes:140141- **Pass 1 — user-facing docs.** Component consumers (storybook stories, migration guides, docsite, MDX, change-file comments).142- **Pass 2 — harness / agent-facing docs.** Future agent sessions reading the skills, `AGENTS.md`, `docs/workflows/*`, and `docs/architecture/*`. When a PR changes a build target, a script, a CI step, a label taxonomy, a project-board field, or an assumption that a skill makes, the skill or harness doc has to be updated **in the same PR** — otherwise every fresh `/triage-issues`, `/visual-test`, `/review-pr`, etc. invocation pays the discovery cost over again.143144Both passes ask the same two questions: should this PR have updated docs, and if so, did it? Bug fixes that restore documented behavior, internal refactors, and test-only PRs default to PASS in both passes — the interesting cases are below.145146#### Pass 1 — user-facing docs147148| Source change | Expected doc surface |149| --------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |150| New prop on a public component (added in `*.types.ts`) | A Storybook story or MDX entry under `packages/react-components/react-<name>/stories/` that exercises the prop |151| New public export added to a `library/src/index.ts` barrel | A story or MDX entry covering it (or a justified note in the PR body) |152| New component package (new directory under `packages/react-components/react-*`) | Stories package, `library/docs/Spec.md`, and an entry on the docsite (`apps/public-docsite-v9`) |153| Behavior change to a public API's defaults (e.g. a new conditional in `use*_unstable` that changes observable output) | Mention in `library/docs/MIGRATION.md` or a "BREAKING CHANGE / behavior change" section in the PR body |154| Removal or deprecation of a public export | `library/docs/MIGRATION.md` entry and/or a `@deprecated` JSDoc on the symbol |155| New design token, classname constant, or CSS custom property | A line in the relevant docs (often the component's stories MDX) explaining how to use/override it |156157#### Pass 2 — harness engineering / agent-facing docs158159This pass exists because skills are part of the contract, not just convenience. When the skills are stale, the agents are wrong — quietly. Symptoms: a `/visual-test` invocation that points at a nonexistent project name, a `/triage-issues` flow that recommends a label the repo no longer has, a `/triage-board` skill that misses a new view filter the maintainers added.160161Walk the diff for any of these and check whether the matching agent-facing doc was updated:162163| Source change | Expected harness update |164| --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |165| New / renamed nx target (`project.json`, `nx.json`, generators) | Any skill that invokes that target — `visual-test`, `lint-check`, `package-info`, `v9-component`. The skill literally types the target name; it's not auto-discovered. |166| New / renamed top-level `package.json` script | Same. Plus `docs/workflows/contributing.md` if it's contributor-facing. |167| New label, label rename, or label taxonomy change in the repo (`gh api repos/.../labels`) | `triage-issues/references/triage-labels.md` — the skill uses an allow-list and `gh issue edit` rejects unknown labels. |168| New / changed project-board field, view filter, or option ID | `triage-board/references/team-mapping.md` (option IDs) and the view-filter mirror in `triage-board/SKILL.md`. |169| New convention contributors are expected to follow (file layout, naming, "always do X") | `AGENTS.md` / `CLAUDE.md` (they're symlinked) — the rules section is the agent's first read. |170| New layered dependency rule, package-tier reshuffle, or CODEOWNERS rewrite | `docs/architecture/layers.md`, `docs/team-routing.md`, plus `triage-board/references/team-mapping.md` if a CODEOWNERS handle gained or lost a confident mapping. |171| New first-time-setup requirement (e.g. a workspace package whose `lib-commonjs/` must be pre-built) | `docs/workflows/contributing.md` "First-time setup" section AND the troubleshooting block of any skill that hits the failure mode (`visual-test` already does this for the unstable-deps case). |172| New skill, agent hook, or `.claude/`-level configuration | `AGENTS.md` skills table + the `.claude/skills/<name>/SKILL.md` bridge file. |173| Removal or move of a path that any skill greps for or hard-codes | The skill that referenced it. Search the skills (`grep -rn "<old-path>" .agents/skills/`) before merging. |174| Authentication / token-scope / permission changes that affect `gh` calls | The skill's preflight section. Concrete past examples: the EMU vs non-EMU active-account gotcha and the `read:project` vs `project` scope distinction now baked into `triage-board`'s preflight. |175| New external-tool name or behavior change (e.g. assignee identity for an automated agent) | The relevant skill. Concrete past example: assigning to `Copilot` literally fails with "Bot does not have access" — only `copilot-swe-agent` works. That belongs in any skill that assigns to Copilot. |176177#### When docs are NOT expected (default to PASS)178179- Pure bug fix that restores documented behavior180- Internal refactor with no exported-symbol or behavior change181- Build / CI changes that have no contributor-facing or skill-facing impact182- Test-only PRs183- Style-only PRs (typo, formatting) on internal code184185#### Severity186187| Situation | Severity |188| ----------------------------------------------------------------------------------------------------------------------- | -------- |189| Public export removed or behavior-changed without `MIGRATION.md` entry | BLOCKER |190| Skill references a renamed or removed path / target / label that this PR changes (skill will literally fail next run) | BLOCKER |191| New public component / new public hook with no story or MDX | WARNING |192| New public prop with no story exercising it | WARNING |193| New design token / className constant with no usage example | WARNING |194| Behavior change to public defaults with no PR-body callout | WARNING |195| New label / project field / nx target / convention without the matching skill or `AGENTS.md` / `docs/workflows/` update | WARNING |196| New first-time-setup requirement without `contributing.md` mention | WARNING |197| PR description explicitly defers docs to a follow-up (link cited) | INFO |198| Docs / harness change exists but feels minimal — could be more thorough | INFO |199200#### How to actually run this check201202The model should walk the diff, not guess.2032041. **Group changed files into surfaces.** Code surfaces (`library/src/**`, `index.ts` barrels, `*.types.ts`); user-doc surfaces (`stories/**`, `library/docs/**`, `apps/public-docsite-v9/**`); harness surfaces (`.agents/skills/**`, `.claude/**`, `AGENTS.md`, `CLAUDE.md`, `docs/workflows/**`, `docs/architecture/**`, `docs/team-routing.md`, `project.json`, `nx.json`, root `package.json` scripts, `.github/CODEOWNERS`, `.github/labeler.yml`).2052. **If the PR is purely a doc/harness surface**, the check is PASS — it's documentation already.2063. **For each row in the user-facing table that matches a code change in the diff**, verify the corresponding doc surface was also touched. If not, raise the matching severity.2074. **For each row in the harness-engineering table that matches**, verify the corresponding skill or harness doc was also touched. Be specific: name the skill that needs updating, not just "a skill."2085. **Cross-search**: when a PR renames a path, target, or label, run `grep -rn "<old-name>" .agents/skills/ docs/ AGENTS.md` to find references that will break. Anything that turns up is a BLOCKER unless this PR also updates it.2096. **Read the PR body** before reporting. Authors often pre-empt with "docs follow-up tracked in #NNNN" or "harness skills updated in commit X" — those move findings from WARNING to INFO when the deferral is explicit and reasonable.210211## Phase 4: Calculate Confidence Score212213```214Start at 100215216For each BLOCKER: -25 points217For each WARNING: -5 points218For each INFO: -1 point219220Bonuses:221 +5 if tests added/updated alongside source changes222 +3 if change file present and well-described223 +2 if PR description is thorough224225Floor at 0, cap at 100.226```227228Score interpretation:229230- **90–100**: High confidence — safe to merge231- **70–89**: Moderate confidence — minor concerns232- **50–69**: Low confidence — needs attention233- **0–49**: Not safe to merge — blockers present234235## Phase 5: Produce Output236237Use this exact format (also used verbatim as the PR-comment body in Phase 6 — don't duplicate work).238239Start directly with the score. Skip a header title, author, type, packages-affected, and CI-status preamble — when this is posted as a PR comment, all of that is already visible in the GitHub UI immediately above the comment, so repeating it just pushes the actually-useful content (score + findings) below the fold. The classification work from Phase 2 still happens; it just isn't echoed back at the reader.240241```242### Confidence Score: <score>/100243244<one-sentence summary>245246### Findings247248#### Blockers (must fix before merge)249- [ ] <finding with file:line reference>250251#### Warnings (should address)252- [ ] <finding with file:line reference>253254#### Info (consider)255- <finding>256257### Category Breakdown258259| Category | Status | Notes |260|----------|--------|-------|261| Change file | PASS/FAIL | ... |262| V9 patterns | PASS/WARN | ... |263| Dep layers | PASS/FAIL | ... |264| SSR safety | PASS/WARN | ... |265| Testing | PASS/WARN | ... |266| API surface | PASS/WARN | ... |267| Accessibility | PASS/WARN | ... |268| Security/Quality | PASS/WARN | ... |269| Docs coverage | PASS/WARN/FAIL | ... |270271### Recommendation272273APPROVE / REQUEST_CHANGES / COMMENT274275<brief rationale>276```277278## Phase 6: Post the review back to the PR279280After presenting the output in the chat, post the same text as a comment on the PR so the review is visible to maintainers and to Copilot (when the PR author is `copilot-swe-agent`, the comment becomes actionable feedback).281282Save the output from Phase 5 to a temp file so the markdown isn't mangled by shell quoting, then:283284```bash285gh pr comment $ARGUMENTS --repo microsoft/fluentui --body-file /tmp/pr-review-$ARGUMENTS.md286```287288Append a single trailer line to the body so the post is identifiable:289290```291---292*Posted via the `/review-pr` skill.*293```294295The posted comment should be **identical** to what you rendered in chat — don't paraphrase or summarize. The chat output and the PR comment must match so the user can trust that what they saw is what the maintainers see.296297**Pre-checks before posting:**2982991. Confirm the active `gh` account has write access to the PR's repo (EMU accounts read fine but silently fail on writes):300 ```bash301 gh api graphql -f query='{ viewer { login } repository(owner:"microsoft", name:"fluentui") { viewerPermission } }'302 ```303 If `viewerPermission` is `NONE`, stop and ask the user to `gh auth switch --user <non-emu-account>`.3042. Don't post on PRs from your own branches unless explicitly asked — self-review comments are noise.3053. If `REQUEST_CHANGES` is the recommendation, still post the comment but note to the user that only a formal review (`gh pr review --request-changes`) actually blocks merge; a comment is advisory.306307**When to skip posting:**308309- The user explicitly asks for a review without posting ("review but don't post").310- The PR has an existing comment from this skill within the last day on the same head SHA — avoid duplicate noise. Look for the `*Posted via the \`/review-pr\` skill.\*` trailer.311- Draft PRs where the user is clearly still iterating (state=OPEN, isDraft=true, recent force-push) — offer to post but don't do it by default.312313## Notes314315- For large PRs (50+ files), prioritize: published source files > test files > config. Note reduced confidence due to review scope.316- Draft PRs: still review but note WIP status.317- Merge conflicts: flag as BLOCKER if detected.318- The `### Confidence Score: NN/100` line must always appear on its own line for machine parsing.