PR Review

AI Pull Request Review Agent SOP (Azure DevOps + Python)

Purpose-built standard operating procedures and minimal workspace structure for an AI-assisted PR review workflow targeting Azure DevOps Git repositories using Python as the cross-platform scripting language.

For script invocation guidance, see references/tool-instructions.md.

1. Objectives

   • Provide a reproducible, minimal workspace for offline PR review artifacts.
   • Fetch and normalize diffs and changed files against a base branch.
   • Drive a consistent, checklist-led review that is easy to audit.
   • Keep authentication safe and avoid leaking PATs or secrets into logs.
   • Always confirm the existence of pr-review.json by first calling list_files on the workspace directory before using read_file or asking follow-up questions. This prevents assumptions about its presence.

2. Workspace layout

   The repository is organized into the following structure:

   .
   ├── pr-review.json                      Read-only user configuration (NEVER modified)
   ├── .ai/
   │   └── skills/
   │       └── pr-review/
   │           ├── SKILL.md                         This SOP file
   │           ├── scripts/                         Python workflow scripts
   │           │   ├── review_config.py             Helper module for merged configuration
   │           │   ├── invoke_build.py              Cross-platform build wrapper (dotnet msbuild / MSBuild)
   │           │   ├── Setup_Util_TrustedRootCertificates_Save.ps1  Windows corporate cert helper
   │           │   ├── s01_reset_workspace.py       Clean previous review artifacts
   │           │   ├── s02_get_azure_devops_info.py Fetch PR and work item metadata
   │           │   ├── s03_extract_attachments.py   Download images from PR/work-item comments + descriptions
   │           │   ├── s04_fetch_repository.py      Prepare BranchFolder and fetch branches when PullBranch is true
   │           │   ├── s05_reset_templates.py       Create review templates with actual PR data
   │           │   ├── s06_export_diff_artifacts.py Export per-file diffs and changed files
   │           │   ├── s07_consolidate_diffs_and_content.py Consolidate patches and snapshots
   │           │   ├── s08_rasterize_images.py      Render ```mermaid blocks to PNG (offline, no upload)
   │           │   ├── s09_upsert_review_attachments.py Upload diagrams + local images to PR attachments
   │           │   ├── s10_upsert_review_comment.py Post review comment to Pull Request
   │           │   ├── s11_upsert_pr_description.py Upsert PR description (guarded; refuses to overwrite real content)
   │           │   └── s12_upsert_suggestion_threads.py Post suggestion threads to Pull Request
   │           ├── assets/                          Templates (SSOT)
   │           │   ├── review.template.md           Template for review.md
   │           │   ├── checklist.template.md        Template for checklist.md
   │           │   └── config.template.json         Template for pr-review.json
   │           └── references/
   │               └── tool-instructions.md         Python invocation rules
   └── {WorkFolder}/                    Configurable via WorkFolder in pr-review.json
       ├── review.md                    Consolidated findings and verdict (generated)
       ├── checklist.md                 Checklist and scoring rubric (generated)
       ├── pr-description.md            Brief PR description (generated; posted only when original PR description is empty)
       ├── diagrams/                    Optional generated images (when GenerateImages: true)
       ├── attachments/                 Screenshots from PR + work items (written by s02b; see manifest.json)
       ├── context.json                 Dynamic Azure DevOps data (written by scripts)
       ├── meta.json                    Git repository metadata (written by scripts)
       ├── changes/                     Working tree copies of changed files
       ├── diffs/                       Per-file unified diff patches (path.patch)
       ├── base/                        Optional base versions of changed files
       └── branch/                      Default local PR branch folder when BranchFolder is not `.`

3. PR configuration and file structure

   The configuration system uses three separate files to maintain clean separation between user input, fetched data, and Git metadata:

   pr-review.json - Read-only user configuration (root of workspace)

   • This file is NEVER modified by scripts
   • Can be version controlled without dynamic data
   • Should contain as little as possible. Scripts derive Azure DevOps values from the current Git checkout first, then ask the user only for values that cannot be derived.
   • Default derived values:
     • BaseUrl, OrganizationName, ProjectName, and RepoName are parsed from git remote get-url origin for Azure DevOps HTTPS or SSH remotes.
     • BranchName is derived from the current Git branch.
     • TargetBranchName is derived from origin/HEAD and falls back to master.
     • PullRequestId is optional. If omitted, s02_get_azure_devops_info.py finds the active PR whose source branch is the current branch. If none or multiple active PRs are found, the workflow stops with a clear message and asks for PullRequestId.
     • WorkItemIds is optional. If omitted, s02_get_azure_devops_info.py reads linked work items from the PR.
     • AzureApiVersion defaults to 7.1.
     • WorkFolder defaults to .tmp/pr-review.
     • PullBranch defaults to false and BranchFolder defaults to . so reviewing the current branch is the default workflow.
   • Optional override fields:
     • BaseUrl, OrganizationName, ProjectName, RepoName - only set these when the Git remote cannot be parsed.
     • PullRequestId - only set this when multiple/no active PRs are found for the current branch.
     • WorkItemIds - only set this when PR work item links are absent or incomplete.
     • BranchName, TargetBranchName - only set these when Git branch/default-branch detection is wrong.
     • PullBranch - set to true only when the scripts should clone/fetch the PR branch into a disposable checkout.
     • BranchFolder - local repository folder for the PR branch; use . to review the current workspace branch, or .tmp/pr-review/branch for a disposable checkout.
     • BranchPath - legacy alias for BranchFolder; prefer BranchFolder for new configurations.
     • GenerateImages - set to true to allow ai-image-generation to produce at most one image per PR when the AI judges a real picture (mockup, before/after, conceptual sketch) would meaningfully help. Default: false. Mermaid diagrams are always allowed regardless of this flag.
     • ReviewAgentUrl - URL of the review agent's home (typically a .ai/skills/pr-review link on the repository hosting the skill); used to expand {review_agent_url} inside ReviewCommentHeader.
     • ReviewCommentHeader - Markdown line(s) prepended below the mandatory [AI Review] tag when n8n posts the review as a PR comment. Supports the {review_agent_url} placeholder.

   All artifact paths below (context.json, meta.json, review.md, diffs/, etc.) are relative to the configured WorkFolder. BranchFolder is resolved relative to the repository root unless it is absolute.

   {WorkFolder}/context.json - Dynamic Azure DevOps data (written by s02_get_azure_devops_info.py)

   • Created/updated by s02_get_azure_devops_info.py
   • Cleaned by s01_reset_workspace.py
   • Contains fetched PR and work item details:
     • BranchName, TargetBranchName - Branch names from PR or Git-derived defaults
     • PullRequestId, PullRequestTitle, PullRequestDescription, PullRequestStatus
     • PullRequestCreatedBy, PullRequestCreatedDate
     • WorkItemTitle, WorkItemType, WorkItemState, WorkItemAssignedTo (based on first Work Item)
     • PullRequest - Full PR API response object
     • WorkItems - Full work item API response objects
     • WorkItem - First work item object (for backward compatibility)

   {WorkFolder}/meta.json - Git repository metadata (written by s04_fetch_repository.py)

   • Created/updated by s04_fetch_repository.py
   • Cleaned by s01_reset_workspace.py
   • Contains Git-specific information for the prepared branch folder:
     • baseCommit, featureCommit - Commit SHAs
     • timestamp - When repository was fetched
     • workDir - Local repository path resolved from BranchFolder
     • baseRef, featureRef - Git refs used for diff export (featureRef is HEAD when PullBranch is false)
     • pullBranch - Effective branch-pulling mode used by s04_fetch_repository.py
   • Note: Branch names originate from {WorkFolder}/context.json (single source of truth from Azure DevOps API) and are copied into metadata with the effective Git refs.

   Configuration Merging: Scripts automatically derive Git/Azure DevOps defaults, then merge pr-review.json + {WorkFolder}/context.json using the review_config.py helper module. Context values take precedence over config values, allowing runtime overrides.

4. Prerequisites

   • Python 3.9 or newer
   • Git 2.35 or newer with Git Credential Manager enabled
   • .NET SDK (for building solutions via invoke_build.py)
   • Access to Azure DevOps repositories
   • Install dependencies: pip install -r .ai/skills/pr-review/scripts/requirements.txt
   • Current Python dependencies include requests and requests-ntlm because the Windows Integrated Authentication fallback uses NTLM helpers when no PAT or Azure CLI token is available

   Authentication methods (scripts try in this order):

   1. Personal Access Token (PAT) - Set AZDO_PAT environment variable with a PAT that has Code (Read) scope. Works on all platforms.
   2. Azure CLI - Uses az account get-access-token if Azure CLI is installed and authenticated. Cross-platform.
   3. Windows Integrated Authentication - Final fallback for domain-joined Windows machines.

5. Quick start using scripts

   Use the Python scripts in the .ai/skills/pr-review/scripts/ directory to prepare the workspace and export diffs and changed files. Scripts are prefixed with execution order (s01, s02, etc.). Run them in the following order:

   Run each script as a separate command and wait for it to finish before invoking the next script. Do not chain multiple scripts together on a single command line.

   • python .ai/skills/pr-review/scripts/s01_reset_workspace.py - Clean previous review artifacts
   • python .ai/skills/pr-review/scripts/s02_get_azure_devops_info.py - Fetch PR and work item metadata
   • python .ai/skills/pr-review/scripts/s03_extract_attachments.py - Download attached images from PR + linked work items into {WorkFolder}/attachments/
   • python .ai/skills/pr-review/scripts/s04_fetch_repository.py - Prepare the local branch folder; clones/fetches only when PullBranch is true
   • python .ai/skills/pr-review/scripts/s05_reset_templates.py - Create review templates with actual data
   • python .ai/skills/pr-review/scripts/s06_export_diff_artifacts.py - Export diffs and changed files
   • python .ai/skills/pr-review/scripts/s07_consolidate_diffs_and_content.py - Consolidate patches and generate before-and-after content snapshots
   • AI writes {WorkFolder}/review.md with findings
   • python .ai/skills/pr-review/scripts/s08_rasterize_images.py - Render ```mermaid blocks in review.md to PNGs (offline, always safe)
   • python .ai/skills/pr-review/scripts/s09_upsert_review_attachments.py - Upload diagrams + local images to PR; rewrite review.md (skipped when SKIP_POST_COMMENT=1)
   • python .ai/skills/pr-review/scripts/s10_upsert_review_comment.py - Upsert review comment to Pull Request

   Attachments

   If {WorkFolder}/attachments/manifest.json exists with totalCount > 0, the PR (or a linked work item) carries screenshots. For each entry: open imagePath (multimodal), read contextPath (why it was attached). Treat any ai-vision-summary.md inside a workitem-*/ folder as authoritative unless the image contradicts it. Cite findings with the attachment path (e.g. Source: attachments/workitem-238853/img-001-image.png). A screenshot that documents a bug the diff doesn't fix is a Blocker.

   Analysis Preparation

   After running the scripts above, decide what to load based on your available context window.

   • If you do not know your context limit, assume a conservative budget of ~300KB total input.
   • Check the output of python .ai/skills/pr-review/scripts/s07_consolidate_diffs_and_content.py — it prints:
     • consolidated artifact sizes, and
     • the split part files (names + sizes) when an artifact was too large.

   Recommended loading strategy:

   1. If it fits, load {WorkFolder}/all-pre-content.txt (before) then {WorkFolder}/all-post-content.txt (after).
   2. If pre/post does not fit, load part files in order and summarize incrementally:
      • {WorkFolder}/all-pre-content.txt.part001 → summarize → ...part002 → summarize → ...
      • then {WorkFolder}/all-post-content.txt.part001 → summarize → ...
   3. For a diff-centric overview, load {WorkFolder}/all-diffs.txt or its parts instead of pre/post.

   Use per-file patches under {WorkFolder}/diffs/** or files under {WorkFolder}/changes/** only when you need to zoom into specific files.

   Refer to each script's --help for usage details.

6. Review flow

   • Think through upcoming steps deliberately and verify instructions (e.g., consult .github/copilot-instructions.md) before executing commands.

   • Prepare workspace using the quick start scripts. The s01_reset_workspace.py script cleans artifacts, then s02_get_azure_devops_info.py fetches PR data, then s03_extract_attachments.py downloads PR + work-item attachments into {WorkFolder}/attachments/, then s04_fetch_repository.py prepares BranchFolder and writes Git metadata, then s05_reset_templates.py creates {WorkFolder}/review.md and {WorkFolder}/checklist.md from their respective template files with actual PR data.

   • When PullBranch is false, BranchFolder is treated as the already checked-out PR branch and the head ref is HEAD; set BranchFolder to . to review the current workspace branch.

   • If present, read .github/copilot-instructions.md from the target repository (BranchFolder) and incorporate any guidance it contains into the review process, such as which projects to test.

   • Load {WorkFolder}/all-pre-content.txt – full "before" state of all changed files

   • Load {WorkFolder}/all-post-content.txt – full "after" state of all changed files

   • Use {WorkFolder}/all-diffs.txt – concise summary of changed lines and statuses

   • Skim {WorkFolder}/diffs/changed-files.tsv to understand scope.

   • Read per-file patches under {WorkFolder}/diffs and the corresponding working files under {WorkFolder}/changes.

   • Restore/build the solution as a best-effort sanity check, not a gate:

     • Pick the build target deterministically:
       • When both .slnx (modern XML format) and .sln (legacy INI format) exist with the same stem, always use the .slnx — it is the source of truth in repositories that have started migrating. invoke_build.py enforces this automatically when given a .sln with a sibling .slnx.
       • When only one of .slnx / .sln exists at the repo root, use it.
       • When no solution exists, build the most relevant changed project (.csproj/.vbproj/.fsproj).
     • Always invoke builds through invoke_build.py rather than bare dotnet restore / dotnet build. The wrapper rewrites the recorded project paths in the local clone so they match on-disk casing — necessary for Windows-authored solutions on case-sensitive Linux filesystems (e.g. .sln says Web.Core/Web.Core.csproj but git wrote Web.Core/web.core.csproj). Bare dotnet commands skip that pass and fail with "project not found" on those repos. The rewrites live in the disposable clone and never travel back to origin.
     • Restore first (prevents NETSDK1004 missing project.assets.json during MSBuild):
       • python .ai/skills/pr-review/scripts/invoke_build.py {solution|project} /t:Restore
     • Then build:
       • python .ai/skills/pr-review/scripts/invoke_build.py {solution|project} /v:minimal /clp:Summary
       • The build wrapper resolves the first argument to an absolute path before invoking MSBuild so the command works reliably when launched from the repository root on Windows
     • Note: invoke_build.py uses dotnet msbuild cross-platform, with full MSBuild via vswhere on Windows as an optimization for multi-targeting solutions

   • Build/test is a best-effort sanity check, NOT a review gate. A code review is still valuable when the local build can't be reproduced. If restore / build / test fails because of any of the following, record exactly what failed in the ## Testing section of review.md (one or two lines, no apology, no retries past three attempts) and continue with the diff-level analysis:

     • Private package feeds the container can't reach or authenticate against (pkgs.dev.azure.com/... without AZDO_PAT wired, npmjs.org/@scope packages, Artifactory, etc.). When AZDO_PAT is set, the container auto-wires Azure DevOps Artifacts auth at clone time via VSS_NUGET_EXTERNAL_FEED_ENDPOINTS + PAT-injected .npmrc; if that didn't happen the env var is missing or the cloned repo references a non-Azure-DevOps feed.
     • Network blocks on public registries (api.nuget.org, registry.npmjs.org) — proxy / firewall / TLS-inspection issues. The container's smoke tests at install time validate these endpoints; if they passed at install but fail now, the proxy state changed.
     • SDK / toolchain extras the project assumes are installed globally (NSwag CLI, EF Core tools, Angular CLI, etc.). The agent container ships .NET / Python / Node / pwsh / Codex CLI / Claude Code CLI / Playwright Chromium and nothing else.
     • Write-blocked default paths (e.g. ~/.dotnet, ~/.nuget, ~/.npm). The container pre-creates these under the agent user's home in container-init.sh and exports DOTNET_CLI_HOME, NUGET_PACKAGES, npm_config_cache so most tools land in writable dirs without configuration. If a tool still hits a write block, redirecting it to /tmp is acceptable for this review run. Do not pursue project-specific build fixes (renaming a file, editing the slnx, removing a ProjectReference) just to make the build pass — the PR is the source of truth, and a "review" that depends on edits the author hasn't approved is unverifiable.

   • Based on guidance (e.g., copilot-instructions or changed projects), find and run the most directly related automated tests you can identify; widen scope only as risk requires.

     • Prefer repository-specific conventions first (existing test projects, test roots, framework config, and naming patterns).
     • Use one canonical mirror pattern as the first guess for both locating related tests and suggesting new ones when the repo does not expose a stronger convention:
       • Code: {repo_path}/{project_name_path}/{code_path}/{source_name}.{source_ext}
       • Test: {repo_path}/Tests/{project_name_path}.Tests/{code_path}/{source_name}{test_suffix}
       • Mirror {code_path} exactly under the test project.
       • Keep {project_name_path} stable and append .Tests.
       • Choose {test_suffix} from the source language or the repo's dominant test framework convention.
       • If the repo has a generic source container such as src, Source, app, or lib, treat that container as outside {project_name_path} and do not mirror it under Tests.
       • Default {test_suffix} values:
         • C#: Tests.cs
         • TypeScript/JavaScript: .test.ts, .test.tsx, .test.js, or .test.jsx
         • Python: _test.py
         • Go: _test.go
         • Java/Kotlin: Test.java or Test.kt
       • Example: Repo/src/Payments/Calculations/VatCalculator.cs -> Repo/Tests/Payments.Tests/Calculations/VatCalculatorTests.cs
       • Example: Repo/web/components/Button.tsx -> Repo/Tests/web.Tests/components/Button.test.tsx
     • Existing codebases often contain older tests that do not follow the canonical pattern. Use the canonical pattern as the first guess, then search for nearby deviations before concluding that no related tests exist:
       • mirror-path candidates in existing test locations
       • test files or projects named after the changed class, component, module, route, or feature
       • broader integration or UI tests only when the change crosses boundaries that unit or component tests cannot cover confidently
     • Record the exact test commands you ran and whether they passed, failed, or were blocked.
     • If no suitable automated tests exist, say so explicitly and recommend the smallest durable set of new tests that covers stable behaviour rather than the PR diff itself.
       • For each recommendation, specify the test type (for example unit, integration, UI, data, calculation), the behaviour to cover, and the most likely file or project path where it should be created, using the canonical mirror pattern unless the repo clearly uses another established layout.
       • Prefer broad, reusable regression tests over narrow temporary tests.

   • Capture findings into {WorkFolder}/review.md by copying the exact structure of assets/review.template.md — do NOT invent sections, rename headings, or reorder. The template is the contract.

     MANDATORY section order (top → bottom):

     1. # AI Review report (title, only once)
     2. Risk and Confidence on separate lines, each with its own colored badge and a brief one-line reason: {RISK_BADGE} **Risk: {RISK_LEVEL}** — {RISK_REASON} {CONFIDENCE_BADGE} **Confidence: {CONFIDENCE_LEVEL}** — {CONFIDENCE_REASON} The two badges use inverted color mappings so 🟢 always means "good": Low Risk = 🟢, High Risk = 🔴; High Confidence = 🟢, Low Confidence = 🔴. Medium on either is 🟡.
     3. ## Decision — symbol + label + one-line "Why:"
     4. ## Related — bullets from context.json.WorkItems[] (or - (no linked items))
     5. ## Blockers — must-fix items, or - (None.)
     6. ## Suggestions — concrete code blocks, each with severity tag
     7. ## How it works — plain-English explanation (ALWAYS present; if sparse source material, end with (Inferred from diff; verify intent.))
     8. ## How to test — copy-pasteable steps (ALWAYS present)
     9. ## Files to review first — top 3 highest-risk paths
     10. <details><summary>Audit details</summary> … </details> — Context, Scope, Strengths, Issues and risks, Testing, Security, Performance, Operations, Documentation, Diff overview

     Anti-duplication rule (CRITICAL):

     The visible block (sections 2–9) and the audit block (section 10) serve DIFFERENT audiences and must not repeat the same information:

     • Suggestions (visible) ≠ Issues and risks (audit). Suggestions are actionable code changes the author can apply. Issues and risks are potential problems that don't have a concrete fix yet (open questions, design concerns). If you've written the fix, it's a Suggestion — do not also write it in Issues and risks.
     • How it works (visible) ≠ Scope (audit). How it works explains intent and behaviour. Scope is the file inventory (count, paths, types of change). Do not narrate the file list in How it works.
     • Why (in Decision) ≠ Strengths (audit). Why is the one-line rationale for the verdict. Strengths is the audit-level list of what the PR does well. Do not restate the verdict in Strengths.
     • Related (visible) ≠ Context (audit) Work Item line. Related is the at-a-glance evidence the AI fetched + read each linked item. Context's Work Item line is the bare URL for the audit record. The audit Context section does NOT repeat the comment count.

     Required content rules:

     • [AI Review] tag lives in the template's H1 (# [AI Review]). The n8n workflow's marker detection accepts the tag whether it appears alone on a line or inside an H1. Do NOT add a separate [AI Review] line above the H1 — that would render twice in the posted comment.

     • Fill {RISK_BADGE}, {RISK_LEVEL}, {RISK_REASON}, {CONFIDENCE_BADGE}, {CONFIDENCE_LEVEL}, {CONFIDENCE_REASON}, {DECISION_SYMBOL}, {DECISION_LABEL} using the rubrics under heading 8. Never leave or delete placeholders — the badge emoji MUST be the first character on its line, before the bold label. If you omit the badge the rendered comment is missing its colour-coded severity cue. The two _REASON values are short one-line justifications (≤ ~12 words each) — e.g. Risk: "touches auth and adds a DB migration"; Confidence: "diff understood, tests reviewed, build verified".

     • ## Related lists linked references using each platform's NATIVE auto-link syntax. Do not wrap in markdown links and do not append state, comment counts, or "(title unavailable)" placeholders — those add noise without information, and the platform already shows that data beneath the PR. Native syntax:

       • Azure DevOps work items: #<ItemId> (e.g. #196182)
       • Azure DevOps pull requests: !<PullRequestId> (e.g. !32147)
       • GitHub issues / pull requests: #<Number> (e.g. #123)

       Optionally append — <Title> only when the title genuinely helps a scanner. If the title is unavailable in context.json, write just the bare reference — never invent one, never write (title unavailable). For external references the platform does NOT auto-link (wiki page, ticket in another system, public docs URL), use a markdown link: [Title](URL). If there are no references, write - (no linked items). Quote a specific comment in "How it works" or audit "Issues and risks" only when it materially shapes the verdict — do not paste full threads.

     • ## How it works and ## How to test are MANDATORY — never omit, even for tiny PRs. For a one-line doc change, How it works = "User-facing wiki text was clarified to define X and Y" (one sentence) and How to test = "Re-render the wiki page; confirm the new sentence appears and renders cleanly" (one step).

     • Suggestions carry severity tags: 🔴 Blocking / 🟡 Recommended / ⚪ Optional. Reference Suggestion N from Blockers when a concrete fix is offered. Each suggestion's code body must not contain bare triple-backtick fences (they would close the outer \``suggestionblock). If the body needs to show markdown code with backticks, replace the inner fences with~~~` or 4-backtick fences.

     • Cite sources. Whenever a finding (Suggestion, Blocker, Issues-and-risks bullet, or How-it-works claim) relies on external material — project documentation (e.g., .github/copilot-instructions.md, README.md, SKILL files, wiki pages), an inline source comment, a linked work item, or a public docs URL — include a Source: reference with the path (and line range when applicable) or URL. Findings derived purely from the diff itself need no Source:. This lets the author resolve conflicts by updating either the code or the obsolete reference (e.g., if a developer added a clarifying comment that contradicts the AI suggestion, the citation makes it obvious whether the suggestion or the comment is out of date). Examples: Source: .github/copilot-instructions.md; Source: src/Foo.cs:42-48 (comment); Source: #196182 (work item).

     • Prefer Mermaid for diagrams. Only invoke ai-image-generation (at most one image per PR) when GenerateImages: true in pr-review.json AND a real picture would meaningfully help.

     • Audit ## Testing: list related tests found, tests actually run, build / validation evidence, coverage adequacy. If no suitable automated test exists, add a Recommended durable tests: sub-list in the same block.

   • Also fill in {WorkFolder}/pr-description.md with a brief PR description (Changes / Why). The file starts with a <!-- pr-description:unfilled --> sentinel — you MUST delete that line when you write real content; the n8n workflow's Build Review Comment skips pushing the file to the PR description if the sentinel is still present. Do NOT add a Related section — Azure DevOps and GitHub already render linked work items / issues natively beneath the PR; only mention external references (wiki page, ticket in another system) when they exist. The n8n workflow updates the PR description from this file only when the original PR description is effectively empty (literally empty, whitespace-only, or a documented placeholder like "Please describe your change").

   • Complete {WorkFolder}/checklist.md following the structure in assets/checklist.template.md and compute the score.

   • Record verdict and any required follow-ups.

   • Ask user to review {WorkFolder}/review.md content before posting.

   • Run python .ai/skills/pr-review/scripts/s08_rasterize_images.py to render Mermaid diagrams in review.md to PNGs (offline, safe to always run).

   • Run python .ai/skills/pr-review/scripts/s09_upsert_review_attachments.py to upload the PNGs (and any local images the AI embedded) to the PR and rewrite review.md to embed the returned URLs.

   • Upon user confirmation, run python .ai/skills/pr-review/scripts/s10_upsert_review_comment.py to post review comment to the Pull Request (automatically marked as resolved if approved).

   • Run python .ai/skills/pr-review/scripts/s11_upsert_pr_description.py to update the PR description from pr-description.md. Refuses to overwrite if the PR already has a real description.

   • If the review contains suggestions, run python .ai/skills/pr-review/scripts/s12_upsert_suggestion_threads.py to post each suggestion as a dedicated inline PR comment thread with file/line context. Suppressed in n8n/scheduled mode via SKIP_POST_COMMENT=1.

     • To remove previously posted suggestion threads: python .ai/skills/pr-review/scripts/s12_upsert_suggestion_threads.py --remove-posted
     • Threads are identified by an agent marker so only threads created by this script are affected.

7. Review checklist

   The review checklist template is maintained in assets/checklist.template.md. This is the single source of truth for the checklist structure.

   The s05_reset_templates.py script creates {WorkFolder}/checklist.md from the template, replacing placeholders with actual values from the configuration and fetched data.

   Template placeholders:

   • {PR_LINK} - Pull request URL
   • {BASE_BRANCH} - Base branch name
   • {FEATURE_BRANCH} - Feature branch name
   • {REPO_NAME} - Repository name
   • {PROJECT_NAME} - Project name
   • {WORK_ITEM_LINK} - Link(s) to associated work item(s)

   The checklist includes sections for:

   • Preparation - workspace setup verification
   • Scope - change description and dependencies
   • Code quality - readability, maintainability, structure
   • Correctness - logic, edge cases, error handling
   • Security - credentials, validation, authorization
   • Performance - efficiency, algorithms, data access
   • Testing - unit tests, integration tests, coverage
   • Operations - migrations, configs, observability
   • Documentation - README, changelog, comments
   • Scoring rubric (0-5 per dimension)
   • Decision and follow-ups

8. Review report

   The review report template is maintained in assets/review.template.md. This is the single source of truth for the report structure.

   s05_reset_templates.py creates {WorkFolder}/review.md from the template, replacing static placeholders with values from configuration and fetched data. AI-judged placeholders are filled in by the agent during review.

   Template placeholders (static, replaced by s05_reset_templates.py):

   • {PR_LINK} — Pull request URL
   • {REPO_NAME} — Repository name
   • {PROJECT_NAME} — Project name
   • {BASE_BRANCH} — Base branch name
   • {FEATURE_BRANCH} — Feature branch name
   • {WORK_ITEM_LINK} — Link(s) to associated work item(s)

   Template placeholders (AI-judged, filled in by the agent):

   • {RISK_BADGE} — Low ⇒ 🟢, Medium ⇒ 🟡, High ⇒ 🔴
   • {RISK_LEVEL} — Low / Medium / High
   • {RISK_REASON} — short one-line justification (≤ ~12 words)
   • {CONFIDENCE_BADGE} — High ⇒ 🟢, Medium ⇒ 🟡, Low ⇒ 🔴 (inverted vs. Risk so 🟢 always means "good")
   • {CONFIDENCE_LEVEL} — High / Medium / Low
   • {CONFIDENCE_REASON} — short one-line justification (≤ ~12 words)
   • {DECISION_SYMBOL} — ✅ or ❌
   • {DECISION_LABEL} — Approve / Approve with comments / Request changes

   Visible block (above the collapsible audit):

   • Risk header line: {RISK_BADGE} **Risk: {RISK_LEVEL}** — {RISK_REASON}
   • Confidence header line: {CONFIDENCE_BADGE} **Confidence: {CONFIDENCE_LEVEL}** — {CONFIDENCE_REASON}
   • Decision (symbol + label + one-line rationale)
   • Related — one bullet per linked reference, using each platform's native auto-link syntax (Azure DevOps work item #<ItemId>, Azure DevOps pull request !<PullRequestId>, GitHub issue/PR #<Number>). No markdown wrapping, no state, no comment count, no (title unavailable) placeholder — those add noise and the platform already shows that data. Optionally append — <Title> only when the title is in context.json and genuinely helps the scanner. External references that the platform does not auto-link use [Title](URL). Empty list → - (no linked items).
   • Blockers (must-fix bullets; reference Suggestion N for the fix)
   • Suggestions (concrete code blocks, each tagged 🔴 Blocking / 🟡 Recommended / ⚪ Optional)
   • How it works (always present; flag with (Inferred from diff; verify intent.) when source material is sparse)
   • How to test (copy-pasteable steps + commands)
   • Files to review first (3 highest-risk changed files)

   Audit details (inside <details> block at the bottom):

   • Context, Scope, Strengths, Issues and risks, Testing, Security, Performance, Operations, Documentation, Diff overview

   Decision symbols (canonical, used verbatim — downstream tooling matches on these labels):

   Symbol	Unicode	Label	Meaning
   ✅	U+2705 WHITE HEAVY CHECK MARK	Approve	No blocking issues; merge when ready
   ✅	U+2705 WHITE HEAVY CHECK MARK	Approve with comments	No blockers; non-blocking suggestions present
   ❌	U+274C CROSS MARK	Request changes	One or more blockers; do not merge until addressed

   The label string is exact and case-sensitive.

   Risk-level rubric (AI-judged): badge tracks severity — green is low risk (safe), red is high risk (dangerous).

   Badge	Level	Triggers
   🟢	Low	Touches non-critical paths, has tests, no security/perf/data implications
   🟡	Medium	Touches business logic, missing some test coverage, or moderate refactor
   🔴	High	Security, auth, payments, data migrations, breaking changes

   Confidence-level rubric (AI self-assessment): badge tracks certainty — green is high confidence (sure), red is low confidence (unsure). Note the inverted mapping vs. Risk: 🟢 means "good" on both scales but corresponds to different levels (Low Risk ↔ High Confidence).

   Badge	Level	Meaning
   🟢	High	Full context available, diff understood, tests reviewed
   🟡	Medium	Some context missing — sparse work item, build failed, etc.
   🔴	Low	Significant unknowns flagged in audit section

   Image generation: off by default. The skill reads GenerateImages from pr-review.json; when true, the AI may invoke the ai-image-generation skill at most once per PR, only when it judges a real picture (mockup, before/after, conceptual sketch) would meaningfully help. Output goes to {WorkFolder}/diagrams/ and is embedded via a Markdown image link inside the "How it works" section. Mermaid is always allowed and is the preferred path for flow / sequence / architecture diagrams.