---
name: oat-review-receive-remote
version: 1.3.0
description: Use when processing GitHub PR review comments outside project context. Fetches PR comments via agent-reviews and converts them into actionable task lists.
disable-model-invocation: true
user-invocable: true
allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion
---

# Remote Review Receive (Ad-hoc GitHub PR)

Process unresolved GitHub PR review feedback into normalized findings and standalone tasks without requiring an active OAT project.

## Prerequisites

- `npx agent-reviews` is available.
- GitHub authentication is configured (`GITHUB_TOKEN`, `.env.local`, or `gh` auth context).
- User wants ad-hoc triage outside project lifecycle artifact mutation.

## Mode Assertion

**OAT MODE: Review Receive**

**Purpose:** Fetch unresolved PR comments, classify findings into standard severities, triage dispositions, and produce standalone tasks.

**BLOCKED Activities:**

- No `plan.md`, `state.md`, or `implementation.md` lifecycle mutations.
- No auto-replies on GitHub without explicit user confirmation.
- No implementing fixes without explicit user confirmation.

**ALLOWED Activities:**

- Resolve PR scope.
- Fetch unresolved PR comments via `agent-reviews`.
- Normalize and classify findings.
- Interactive triage and task-list generation.
- Implementing fixes, committing, and pushing (only with explicit user confirmation).
- Optional explicit replies to processed comments.

**Self-Correction Protocol:**
If you catch yourself:

- Replying on GitHub without explicit user confirmation -> STOP and present reply content for approval first.
- Editing project lifecycle artifacts (`plan.md`, `state.md`, `implementation.md`) in ad-hoc mode -> STOP and revert to task-list output only.
- Skipping the findings overview before triage prompts -> STOP and show overview first.
- Implementing fixes without user confirmation -> STOP and ask first.

## Progress Indicators (User-Facing)

Print this banner once at start:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
OAT ▸ REMOTE REVIEW RECEIVE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Use step indicators:

- `[1/7] Resolving PR...`
- `[2/7] Fetching comments...`
- `[3/7] Classifying findings...`
- `[4/7] Triaging findings...`
- `[5/7] Generating task list...`
- `[6/7] Applying fixes (optional)...`
- `[7/7] Posting replies (optional)...`

## Findings Model

Normalize every finding to this shape:

```yaml
finding:
  id: "C1" | "I1" | "M1" | "m1"
  severity: critical | important | medium | minor
  title: string
  file: string | null
  line: number | null
  body: string
  fix_guidance: string | null
  source: github_pr
  source_ref: string
  comment_id: string | number
```

Severity conventions:

- `critical`: Broken behavior, security risk, or missing P0 requirement.
- `important`: Missing P1 requirement, major robustness issue.
- `medium`: Meaningful but non-blocking quality/maintainability issue.
- `minor`: Cosmetic/style/documentation issue.

## Process

### Step 1: Resolve PR Number

PR resolution order:

1. `--pr <N>` from `$ARGUMENTS`
2. Auto-detect via `agent-reviews` current-branch resolution

Ask user to confirm resolved PR number before fetching comments.

### Step 2: Fetch Unresolved Comments

Run:

```bash
npx agent-reviews --json --unresolved --pr <N>
```

Expected: JSON payload with unresolved review comments and metadata.

If command fails:

- Capture error details.
- Route user through troubleshooting (auth, network, permissions, invalid PR).

If no unresolved comments are returned:

- Report clean status and stop.

### Step 3: Classify and Normalize Findings

For each item in JSON:

- Capture `type` (`review_comment`, `issue_comment`, `review`).
- Map location fields (`path`, `line`) when present.
- Use comment body + context to assign severity (`critical`, `important`, `medium`, `minor`).
- Treat `CHANGES_REQUESTED` review state as a strong hint toward `important+`, not an automatic override.
- Normalize into the shared findings model.

ID assignment per severity bucket:

- Critical: `C1`, `C2`, ...
- Important: `I1`, `I2`, ...
- Medium: `M1`, `M2`, ...
- Minor: `m1`, `m2`, ...

### Step 4: Present Findings Overview and Triage

Before triage prompts, output:

- Counts per severity
- Compact register: `id`, `title`, `file:line`, `source_ref`

Disposition options per finding:

- `convert` (default for critical/important/medium/minor)
- `defer`
- `dismiss`

Rules:

- Require concrete rationale for `defer`/`dismiss` at any severity, including minor. Small findings are usually cheaper to fix inline than to track as backlog items, so a minor `defer` must be justified just like any other deferral.
- For any deferral (minor included), require a concrete reason (duplicate, dependency, explicit out-of-scope follow-up, risky churn).

### Step 5: Generate Standalone Task List

Task entry format:

```markdown
- [ ] [important] Add null-guard in OAuth callback parser (`packages/auth/src/callback.ts:142`) - Validate provider payload before dereference.
```

Output modes:

- Inline (default)
- File output path (if user requests)

Also output deferred and dismissed lists with reasons.

### Step 6: Optional Fix Implementation

After the task list is confirmed, ask:

`Would you like me to address these fixes, commit, and push the changes? [yes/no]`

If yes:

1. Implement each converted task in the order listed.
2. After all fixes are applied, run verification (lint, type-check, tests as appropriate).
3. Stage and commit with a descriptive message referencing the PR:

   ```bash
   git add {changed-files}
   git commit -m "fix: address PR #<N> review feedback

   Resolved findings: {list of finding IDs and titles}"
   ```

4. Push to the current branch:
   ```bash
   git push
   ```
5. Capture the commit hash for use in Step 7 replies:
   ```bash
   FIX_COMMIT=$(git rev-parse --short HEAD)
   ```

If no: skip to Step 7.

### Step 7: Optional GitHub Reply Posting

After fix implementation (or after task generation if fixes were skipped), ask:

`Reply to processed comments on GitHub? [yes/no]`

If yes, reply per finding disposition:

**When fixes were applied (Step 6 completed):**

- Convert: `npx agent-reviews --reply <id> "Fixed in <FIX_COMMIT>"`
- Defer: `npx agent-reviews --reply <id> "Deferred: <reason>"`
- Dismiss: `npx agent-reviews --reply <id> "Won't fix: <reason>"`

**When fixes were not applied:**

- Convert: `npx agent-reviews --reply <id> "Acknowledged - tracking as task"`
- Defer: `npx agent-reviews --reply <id> "Deferred: <reason>"`
- Dismiss: `npx agent-reviews --reply <id> "Won't fix: <reason>"`

Never send replies without explicit user approval.

## Troubleshooting

- Auth failure: verify `GITHUB_TOKEN` and repository access.
- No PR detected: pass explicit `--pr <N>`.
- No unresolved comments found: confirm you are targeting the correct PR and unresolved filter.
- Network/rate limit errors: retry after backoff and report blocked state if persistent.

## Output Contract

At completion, report:

- PR number
- Severity counts
- Converted/deferred/dismissed counts
- Task list output location (`inline` or file path)
- Whether fixes were applied (and commit hash if so)
- Whether replies were posted

## Success Criteria

- PR scope resolved and confirmed.
- Unresolved comments fetched from GitHub.
- Findings normalized with consistent 4-tier severities.
- Triage completed with explicit rationale capture for deferred/dismissed findings.
- Standalone task list generated.
- Fixes applied, committed, and pushed only with user approval.
- Optional replies posted only with user approval (with commit hash when fixes were applied).
