# How we keep code review from stalling

The pull-request review agent we run on Kortix — it flags PRs stuck past a review SLA, gone stale, or sitting on unaddressed change requests, then nudges the author or reviewer in Slack with exactly what's blocking.

Canonical page: https://openchatly.com/use-cases/pr-review-nudge

A PR that sits unreviewed for three days doesn't announce itself. It just sits,
under a growing pile of newer PRs, until the author pings someone directly or
gives up and context-switches to something else. Multiply that across a team
and a review SLA becomes a suggestion nobody enforces, and "requested changes"
becomes a state a PR can live in indefinitely.

We run a PR review nudge agent on Kortix that reads every open pull request
across our repos once a day and posts a Slack nudge for anything stuck: past
the review SLA, gone stale, or sitting on unaddressed change requests. It only
reads GitHub; the single output is the Slack nudge. It never merges, closes, or
approves anything.

- **Team:** Kortix
- **Runs on:** Daily cron
- **Connected systems:** GitHub · Slack
- **Mode:** Read-only on GitHub · nudge + summarize only

## The problem

A review SLA is easy to write down and hard to enforce. Nobody is watching the
review queue full-time, so a PR opened Monday morning and still unreviewed
Wednesday afternoon looks the same in the repo list as one opened five minutes
ago — until someone happens to scroll far enough to notice. Stale PRs are worse:
a branch with no commits, no comments, and no reviews in a week has usually just
been forgotten, and it silently rots until a rebase conflict forces someone to
deal with it. And "requested changes" is a state, not an alert — a reviewer asks
for changes, the author sees it, life happens, and the PR sits there looking
open while actually being blocked.

The common approaches don't close this loop. GitHub's own notifications are
easy to mute and don't distinguish a PR that's five minutes old from one that's
five days old. A weekly standup catches the loudest blockers, not the quiet
ones. Manually skimming the PR list is thorough the first time and skipped the
second.

## What we built

On Kortix, a daily cron triggers an agent. It spawns a fresh session with
read-only access to GitHub through the `gh` CLI, pulls every open PR across our
repos, and classifies each one against three rules: awaiting review past the
SLA, stale with no activity in N days, or carrying requested changes the author
hasn't addressed. For each PR that trips a rule, it posts a Slack nudge to the
person who owns the next move — the requested reviewer if it's overdue for
review, the author if it's stale or has unaddressed feedback — with a one-line
summary of what's actually blocking it.

## How it works

### Copy the setup prompt into a new session

Open your Kortix workspace, start a new session, paste this prompt and send it.
The agent writes the agent file, the pr-review-sla skill and the daily trigger,
and opens a change request for you to review. Prefer clicks? Choose **Use this
template** instead.

**Setup prompt**

```
Set up a daily PR review nudge agent in this workspace.

1. Create the agent agents/pr-review-nudge.md. Its job is to find stuck pull requests on owner/repo and nudge the person who owns the next move. It reads GitHub with the gh CLI and the GH_TOKEN secret, and it may use the Slack connector.

2. Create the skill skills/pr-review-sla/SKILL.md with these rules:
   - A PR is overdue for review when a requested reviewer has not reviewed it 24 hours after the request. Nudge the reviewer.
   - A PR is stale when it has no commit, comment or review in 3 days. Nudge the author.
   - A PR has unaddressed changes when its latest review requests changes and the author has not pushed or replied since. Nudge the author.
   - A PR that trips more than one rule gets one entry that lists every rule it trips.
   - Post exactly one summary to #eng-reviews per sweep, grouped by rule, and tag each person you nudge.
   - Every GitHub call is a read. Never merge, close, approve or comment on a PR, and never dismiss a review.

3. Add a cron trigger daily-pr-review-sweep to kortix.yaml. It runs the pr-review-nudge agent every day at 08:00 with the prompt "Load the pr-review-sla skill and run one complete review sweep on owner/repo."

4. Tell me which of these connectors are not connected yet. Tell me if the GH_TOKEN secret is missing.

5. Open a change request with all of it. Do not merge it.
```

### Connect your tools

Add a GitHub token with read access as the `GH_TOKEN` secret. It is injected at
runtime and scoped to this agent. Then open **Connectors** and connect Slack.
Credentials are brokered server-side and never enter the agent's machine.

- **GitHub** (Required):
Reads open PRs, review requests and activity, read-only.
- **Slack** (Required):
Nudges the reviewer or author about what blocks each PR.

### Run it once with this prompt

Merge the change request, then start a session with the **pr-review-nudge**
agent and send this prompt. Replace owner/repo with your repository. Check who
it nudges before you let the schedule take over.

**Prompt**

```
Run one review sweep on owner/repo.

1. List every open PR with gh pr list, and read its review requests, reviews, comments and commits.
2. Flag PRs that wait more than 24 hours for a requested review, PRs with no activity in 3 days, and PRs whose latest review requests changes that the author has not addressed.
3. Write one line per flagged PR: title, link, every rule it trips, for how long, and who owns the next move.
4. Post one summary to #eng-reviews, grouped by rule.
5. Do not merge, close, approve or comment on any PR.
```

### Let the daily schedule take over

The change request added this trigger to `kortix.yaml`. From now on the agent
runs every day at 08:00, each run in a new session on its own cloud computer.
To change the time, edit the cron line, or open **Triggers** in the workspace.

**kortix.yaml**

```yaml
triggers:
  - slug: daily-pr-review-sweep
    name: Daily PR review SLA sweep
    on:
      cron: "0 0 8 * * *"
    run:
      agent: pr-review-nudge
      prompt: Load the pr-review-sla skill and run one complete review sweep on owner/repo.
```

### Read GitHub, write only to Slack

Every GitHub call is a read. The agent never merges, closes or approves a PR,
and never dismisses or resolves a review. The Slack summary is its only output.
People decide what happens to each PR.

### Read the morning summary

Each run ends with one summary in the channel. This is what a run looks like in
the session:

> **Daily PR review SLA sweep · 08:00**
>
> Prompt: Load the pr-review-sla skill and run one complete review sweep on owner/repo.
>
> Checked **17** open PRs and flagged **6**. **3** wait on a review past the
> 24-hour SLA, **2** have had no activity for 3 days, and **1** has requested
> changes that the author has not addressed for **4** days.

> **The pattern**
> A daily **cron** spawns a fresh session that reads open PRs through the `gh`
> CLI with a scoped **GH_TOKEN**. The SLA, staleness, and unaddressed-changes
> rules live as a **skill**. The agent reads everything and writes nothing but
> the Slack nudge.

## Make it do more

Once it works, paste any of these into the same session.

**Skip drafts**

```
Ignore draft PRs and PRs labeled wip, and say how many you skipped at the end of the summary.
```

**Weekly review-time trend**

```
Every Friday, post to #eng-reviews the median hours to first review for the PRs merged that week.
```

**Cover more repositories**

```
Also sweep owner/other-repo in the same run, and group the summary by repository.
```

## Guardrails

The agent reads across every repo it's pointed at, so its access is scoped and
strictly one-directional:

- **Isolation.** Every run happens in its own isolated sandbox. The session is granted access only to GitHub (read-only) and Slack; nothing else is written back out.
- **Scoped secret.** The `GH_TOKEN` is encrypted in the Secrets Manager and
  injected into the sandbox at runtime, scoped to the agents you grant them to.
- **Nudge and summarize only.** The agent never merges, closes, or approves a
  PR, and never dismisses or resolves a review. It reports what's blocking and
  leaves the decision to a human.
- **Everything is code.** The SLA thresholds, the staleness window, and the
  agent's GitHub permissions are files in the repo, versioned and changed
  through a reviewed **change request** rather than a dashboard setting.

## The outcome

- **Every day:** Every open PR rechecked against the current GitHub state
- **3 checks:** Overdue for review, stale, and unaddressed changes, in one pass
- **Zero:** Merges, closes, or approvals made by the agent

A review queue that used to require someone remembering to scroll through it
now surfaces its own blockers every morning, in Slack, addressed to whoever
owns the next move. The agent only reads and nudges; the team still decides
what happens to every PR.
