jocyscom/focuslogger/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.

1. Workspace layout

The repository is organized into the following structure:

``text . ├── 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 . ``

1. 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.

1. 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.

1. 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