Component

Documentation

Bug Description

docs/architecture/agentic-workflows.md describes the PR Review workflow in a way that no longer accurately reflects the implementation after #1293, which added a maintainer-only skip-review label guard and maintainer advisory mode.

What the documentation currently says:

• Workflow Inventory table: "Review correctness, conventions, security; label review-passed or needs-revision" — implies all PRs receive the same review outcome options
• Label-Driven Handoffs diagram: pr_opened --> needs_revision: Review agent requests changes — implies all PRs can receive needs-revision
• PR Review Workflow subgraph: shows "Add needs-revision label with inline comments" as a general outcome

What the implementation now does (after #1293):

• Maintainer Advisory Mode: When the PR author is a MEMBER, OWNER, or COLLABORATOR, the agent uses COMMENT review type (never REQUEST_CHANGES), does not add the needs-revision label, and does not convert the PR to draft. The review summary is prefixed with "Advisory review…"
• skip-review label guard: The skip-review label now only skips the review when the PR author is a maintainer (MEMBER, OWNER, or COLLABORATOR). Non-maintainer PRs are not skipped even if the label is present.

Expected Behavior

docs/architecture/agentic-workflows.md should be updated to:

1. Add a note to the PR Review Workflow description distinguishing maintainer advisory mode from the standard enforcement mode
2. Update the Workflow Inventory table description to reflect that needs-revision is not applied to maintainer PRs
3. Add documentation for the skip-review label and its maintainer-only guard in the Label-Driven Handoffs section
4. Update the PR Review Workflow subgraph in the diagram to reflect the advisory path

Steps to Reproduce

• View the merged PR: #1293
• Read .github/workflows/pr-review.md (Activation Guard and Maintainer Advisory Mode sections)
• Compare against docs/architecture/agentic-workflows.md (Workflow Inventory table, Label-Driven Handoffs diagram, PR Review Workflow subgraph)

Additional Context

Documentation file: docs/architecture/agentic-workflows.md

• Lines ~52–59: PR Review Workflow subgraph in the End-to-End Process Flow diagram
• Line ~99: PR Review row in Workflow Inventory table
• Lines ~136–138: Label-Driven Handoffs state diagram

Code files changed in #1293:

• .github/workflows/pr-review.md — source workflow definition with Activation Guard and Maintainer Advisory Mode sections
• .github/workflows/pr-review.lock.yml — compiled workflow

Generated by Documentation Update Check · ◷