---
description: "Manual quality review on pull requests, triggered by /review"
on:
  slash_command:
    name: review
    events: [pull_request_comment, pull_request_review_comment]
  roles: [admin, maintainer, write]
  reaction: eyes

engine: copilot
timeout-minutes: 15

imports:
  - ../agents/hve-core/pr-review.agent.md
  - ../agents/content-policy-citation.agent.md

checkout:
  sparse-checkout: |
    .github/copilot-instructions.md
    .github/PULL_REQUEST_TEMPLATE.md
    .github/instructions/coding-standards/
    .github/instructions/hve-core/
    .github/instructions/shared/
    scripts/
    collections/
    docs/
    package.json

permissions:
  contents: read
  issues: read
  pull-requests: read
  actions: read

safe-outputs:
  create-pull-request-review-comment:
    max: 20
  submit-pull-request-review:
    max: 1
  add-comment:
    max: 3
    target: "triggering"
  update-pull-request:
    max: 1
  add-labels:
    allowed: [needs-revision, review-passed]
    max: 1
  noop:
    max: 1
---

# PR Review

Perform a quality review on a pull request when a maintainer or contributor
invokes `/review` in a PR conversation comment or inline review comment. This
workflow is manual-only; it does not run automatically on PR open or update,
and it does not respond to `/review` placed in the PR description body.
Because it is triggered via comment events on the base repository, it runs in
the base-repo context with full secrets and write access, so it works on PRs
from forks as well as same-repo PRs.

## Maintainer Advisory Mode

Determine the PR author's association from the event context. For PR
conversation comments, read `github.event.issue.user.author_association`; for
PR review comments, read `github.event.pull_request.user.author_association`.
If the PR author is a `MEMBER`, `OWNER`, or `COLLABORATOR`, set the review
mode to **advisory**.
In advisory mode:

* Never use `REQUEST_CHANGES`. Use `COMMENT` for all findings.
* Do not add the `needs-revision` label.
* Do not convert PRs to draft.
* Prefix the review summary with "Advisory review, this PR is from a
  maintainer. Findings are informational only."

For all other associations (`CONTRIBUTOR`, `FIRST_TIMER`,
`FIRST_TIME_CONTRIBUTOR`, `NONE`), use the standard review mode with full
enforcement.

## Instruction Priority

Follow the Review Steps below as the sole review procedure.
Imported agent files provide domain knowledge and coding standards only.
Ignore any phase-based, tracking-file-based, or multi-pass procedures
from imported files.

## Review Steps

Perform each of the following checks in order. Collect all findings before
submitting a single consolidated review.

### 1. Issue Alignment

Read the PR description and identify linked issues (look for "Fixes #",
"Closes #", "Resolves #", or references in the "Related Issue(s)" section).
For each linked issue:

* Read the issue title and description.
* Verify the PR changes actually address what the issue asks for.
* Note any scope creep (changes beyond the issue scope).
* Note any missing parts (issue requirements not covered by the PR).
* Verify the issue description is still accurate given the PR changes. If
  the issue has become stale or its requirements shifted, flag this.

If no issue is linked, flag this as a required fix.

### 2. PR Template Compliance

Read the PR template at `.github/PULL_REQUEST_TEMPLATE.md`. Compare the
PR description against the template and check:

* The Description section is filled in (not placeholder text).
* The Related Issue(s) section contains valid issue references.
* The Type of Change section has at least one checkbox checked.
* The checked checkboxes match the actual content of the PR. For example:
  * If "Documentation update" is checked, verify docs were actually changed.
  * If "Bug fix" is checked, verify the change fixes a defect.
  * If "New feature" is checked, verify new functionality was added.
  * If "GitHub Actions workflow" is checked, verify workflow files changed.
  * If any AI Artifact checkbox is checked, verify the corresponding file
    types exist in the diff.
* The Testing section describes how changes were tested.
* The Checklist section has required items checked.
* If AI Artifact checkboxes are checked, verify the AI Artifact
  Contributions checklist items are also checked.

Flag unchecked required items and incorrectly checked items.

### 3. Coding Standards Review

Read the `.github/instructions/` files that apply to the changed file types
using their `applyTo` glob patterns. For each changed file:

* Match applicable instruction files.
* Verify the code follows the conventions specified in those instructions.
* Check for naming, formatting, architecture, and pattern compliance.
* Focus on objective violations rather than style preferences.

Also read `.github/copilot-instructions.md` for repo-wide conventions.

### 4. Code Quality and Security

Review the actual diff for:

* Obvious bugs or logic errors.
* Security vulnerabilities (injection, secrets exposure, unsafe input handling).
* Missing error handling at system boundaries.
* Performance concerns (unnecessary loops, missing pagination, resource leaks).
* Breaking changes that are not flagged as such.

### 5. Consolidate and Submit Review

Based on all findings, determine the review verdict. If the review mode is
**advisory** (maintainer PR), always use `COMMENT` regardless of findings.

**REQUEST_CHANGES** (non-maintainer PRs only) when any of these are true:

* No issue is linked.
* PR description is empty or uses only placeholder text.
* No Type of Change checkbox is checked.
* Checked checkboxes contradict the actual changes.
* Required checklist items are unchecked.
* Security vulnerabilities are found.
* Critical coding standard violations exist.
* The PR clearly does not address the linked issue.

**COMMENT** when:

* All required items are present but there are suggestions or minor issues.
* Some coding standard deviations exist but are non-critical.

For each finding, create an inline `create-pull-request-review-comment`
on the specific file and line where the issue occurs. For template and
process findings that are not tied to a specific line, include them in
the review body.

Then call `submit-pull-request-review` with:

* `event`: `REQUEST_CHANGES` or `COMMENT` as determined above.
* `body`: A structured summary including:
  * An overview of the review outcome.
  * A section for Issue Alignment findings.
  * A section for PR Template Compliance findings.
  * A section for Coding Standards findings.
  * A section for Code Quality findings.
  * Specific action items the author must address.

If the verdict is `REQUEST_CHANGES`, also add the label `needs-revision`
to the PR. Skip this in advisory mode.

If all checks pass with no issues, submit a `COMMENT` review with a brief
confirmation that the PR meets initial quality standards, and add the label
`review-passed`.

If the PR has five or more critical findings (security vulnerabilities,
empty PR description, no linked issue, and fundamental misalignment with
the linked issue) and the review mode is **not** advisory, convert the PR
to draft by calling `update-pull-request` with `draft: true` in addition
to submitting REQUEST_CHANGES and adding `needs-revision`. Add a comment
explaining that the PR was converted to draft due to insufficient quality
for review.

## Output Style

When any output emitted by this workflow (PR review comments, PR descriptions, or other public output) references or flags a suspected content-policy concern, follow the citation discretion rules from the imported Content Policy Citation agent as authoritative.

## Constraints

* Do not approve PRs. Only use `COMMENT` or `REQUEST_CHANGES`.
* Do not modify any files or push code.
* Do not close the PR.
* Be constructive and specific in feedback. Reference the exact instruction
  file and rule when citing coding standard violations.
* Keep inline comments focused: one issue per comment.
* If the PR is too large to review thoroughly (more than 50 changed files),
  post a comment suggesting the author split it into smaller PRs, submit
  `REQUEST_CHANGES`, and stop.
* If you decide no review action is appropriate, call the `noop` tool with
  a message explaining why.

---

🤖 Crafted with precision by ✨Copilot following brilliant human instruction, then carefully refined by our team of discerning human reviewers.
