PR Review Workflow

---
id: "a7c3e1f4-8b2d-4e6a-9f1c-3d5b7a9e2c4f"
name: "PR Review Workflow"
type: workflow
category: coding
version: "1.0.0"
author: "markeddown"
license: MIT
min_context_tokens: 4096
target_frameworks:
  - markeddown
  - cursor
  - claude
  - generic
tags:
  - code-review
  - pull-request
  - quality
  - security
---

# PR Review Workflow

A structured code review process that produces consistent, constructive, and actionable feedback.

## Step 1 — Read the Diff

- Fetch the full diff (files changed, lines added/removed).
- Note the scope: how many files, which directories, what subsystems.
- If the diff is too large to hold in context, split by file and process in batches.

## Step 2 — Understand Intent

- Read the PR title, description, and linked issues.
- Identify the goal: feature, bugfix, refactor, config change, or dependency update.
- If intent is unclear, flag it immediately — a PR without a clear "why" cannot be reviewed properly.

## Step 3 — Check for Bugs and Security Issues

- Walk through the logic change line by line.
- Look for: null/undefined access, off-by-one errors, race conditions, missing error handling.
- Security checklist: input validation, SQL injection, XSS, secrets in code, permission checks, auth bypass.
- For each finding, record the exact file and line number.

> **Decision point:** If a critical security issue is found, stop the review and flag it immediately. Do not wait until the end.

## Step 4 — Evaluate Test Coverage

- Check if new/changed code paths have corresponding tests.
- Look for: missing edge cases, tests that only cover the happy path, mocked dependencies that hide real behavior.
- If no tests exist and the change is non-trivial, note this as a blocking concern.

## Step 5 — Assess Readability and Maintainability

- Are variable and function names descriptive?
- Is the code structured so the next developer can understand it without the PR description?
- Are there comments where the logic is genuinely non-obvious (not redundant comments)?
- Flag any premature abstraction or unnecessary complexity.

## Step 6 — Write the Review

Structure your review as follows:

### Summary
One paragraph: what the PR does, whether it achieves its goal, and overall quality assessment.

### Findings
List each finding with:
- **File and line reference** (e.g., `src/auth.ts:42`)
- **Severity:** Critical / High / Medium / Low / Nit
- **Description:** What the problem is and why it matters
- **Suggestion:** A concrete fix or direction (not vague advice)

Order findings by severity, critical first.

### Verdict

> **Decision gate — choose exactly one:**
>
> - **Approve** — No blocking issues. Merge-ready, optionally with nit fixes.
> - **Request Changes** — At least one Critical or High finding that must be addressed before merge.
> - **Comment Only** — Questions or discussion points that need author input before a verdict is possible.

## Constraints

- Never approve a PR with known Critical or High severity issues.
- Never leave a review that only says "LGTM" — always cite at least one specific observation.
- If you are uncertain about a finding, state your uncertainty explicitly rather than guessing.
- Keep tone professional and constructive. Critique the code, not the author.