pr-reviewing

Files (1)

• SKILL.md

SKILL.md (first lines)

# HOTL PR Review

## Overview

Review a pull request end-to-end across 4 dimensions (description/ticket, code changes, code scan, unit tests) using parallel subagents. Produces a structured verdict report and optionally posts line-level comments on GitHub.

**Announce:** "Starting PR review. Detecting platform and fetching PR data..."

## Output Contract

This skill produces a structured review report. The canonical schema is defined in
`docs/contracts/pr-review-output.md`. All platforms must emit every section in that
contract. Platform-specific rendering (tables, inline comments, etc.) is handled by
platform docs, not this skill.

Key rules from the contract:
- All 9 sections always present, even on BLOCK
- Dimension verdicts summarize sections; individual findings may have mixed severities
- Overall verdict derived from dimension verdicts, not individual findings
- The contract is mandatory even when platform-native findings are emitted before it

## Step 1: Platform Detection & PR Fetching

### Resolve the PR

1. If the user provided a PR URL → parse org/repo and PR number from it
2. If no URL → detect from current branch:
   - Try `gh pr view --json number,title,body,baseRefName,headRefName,url` → if succeeds, use GitHub mode
   - Try `glab mr view` → if succeeds, use GitLab mode
   - If both fail → use **local-only mode** (git diff against base branch)

### Platform Modes

| Platform | CLI | Mode | Capabilities |
|---|---|---|---|
| GitHub (public) | `gh` | full | Local report + post review comments |
| GitLab | `glab` | local-only | Local report only |
| Enterprise/VPN | none | local-only | Local report only (git diff fallback) |

### Fetch PR Data

**Full mode (GitHub):**
```bash
gh pr view <number> --json title,body,baseRefName,headRefName,changedFiles,additions,deletions
gh pr diff <number>
```

**GitLab mode:**
```bash
glab mr view <number>
glab mr diff <number>
```

**Local-only fallback:**
```bash
git log --oneline main..HEAD
git diff main...HEAD
git diff --name-only main...HEAD
```

### Ticket Extraction

1. Scan the PR description for ticket references:
   - Patterns: `JIRA-1234`, `ABC-123`, `#123`, or full URLs (Jira, GitHub Issues, GitLab Issues, Linear)
2. Attempt to fetch ticket content:
   - GitHub Issues: `gh issue view <number> --json title,body`
   - Jira URL: `WebFetch` the ticket page (user must be authenticated/on VPN)
   - GitLab Issues: `glab issue view <number>`
   - Generic URL: `WebFetch` and extract text
3. If fetch fails → skip gracefully, note "Ticket not accessible" in report

## Step 2: Dispatch Parallel Subagents

Dispatch **4 subagents simultaneously** using the Agent tool. Pass each subagent the PR data collected in Step 1.

### Subagent A: Description & Ticket Review

```
Prompt template:
---
You are reviewing a PR's description and ticket alignment.

**PR Title:** {title}
**PR Description:**
{body}

**Linked Ticket (if available):**
{ticket_content or "No ticket linked/accessible"}

## Review Checklist

1. **Description quality:**
   - Does it explain WHY this change is needed?
   - Does it explain WHAT changed?
   - Does it explain HOW it works (if non-obvious)?
   - Is it clear enough for a reviewer unfamiliar with the context?

2. **Ticket alignment (if ticket available):**
   - Does the PR address the ticket's requirements?
   - Are all acceptance criteria covered?
   - Is there scope creep (PR does more than ticket asks)?
   - Is there scope gap (ticket asks for more than PR delivers)?

## Output Format

Return EXACTLY this format (two separate blocks — one for description, one for ticket):
```
DIMENSION: Description
VERDICT: PASS | WARN | BLOCK
FINDINGS:
- [BLOCK|WARN|NOTE]: [finding description]
SUMMARY: [one sentence]

DIMENSION: Ticket Alignment
VERDICT: PASS | WARN | BLOCK | N/A
FINDINGS:
- [BLOCK|WARN|NOTE]: [finding description] (or "No ticket linked" if none found)
SUMMARY: [one sentence]
```

From yimwoo/hotl-plugin, MIT.

More from yimwoo/hotl-plugin