fix(pr-review): post reviews via Pull Request Reviews API, not issue comments

[m0nk111]

Problem

On real PRs, the github-pr-review agent posts a single gh pr comment (issue-level blob) instead of a POST /repos/{owner}/{repo}/pulls/{n}/reviews call with a comments[] array. That bypasses inline diff anchoring, breaks the suggestion-block UX, and produces no per-finding threads.

Concrete observation: on m0nklabs/cryptotrader#379, the github-code-quality bot left 16 inline review threads (one per finding, each with a Commit suggestion button). The OpenHands agent on the same PR left one Markdown blob in the PR conversation, with zero inline threads — i.e. it used the wrong API.

The previous SKILL.md and prompt did say to bundle findings into one Reviews API call, but the agent routinely ignores the spec and falls back to gh pr comment. The likely cause is that the prompt's primary instruction is "keep the review body brief unless your active review instructions require a longer structured format", which is weak and easily overridden by the agent's default behaviour. The spec was hidden several layers down inside the skill.

Fix

Two changes:

1. plugins/pr-review/scripts/prompt.py — insert a ## How to Post the Review (CRITICAL — read first) block directly under the /github-pr-review trigger. It mandates the Reviews API, shows a worked gh api + JSON example with one entry per finding, and explicitly forbids gh pr comment / POST /issues/{n}/comments. The block is positioned before the existing "keep the review body brief" line so the strongest directive fires first.

   The example uses {{owner}}/{{repo}}/{{n}} escapes (rendering as literal {owner}/{repo}/{n}) so the LLM sees a realistic-looking gh command. The real pr_number placeholder stays substituted.

2. plugins/pr-review/skills/github-pr-review/SKILL.md — rewrite to align the spec with the github-code-quality[bot] format. New sections: Pre-Review Checks, Key Rule: One PR Review / One API Call / Many Inline Comments, Inline Comment Body Format, Worked example, Multi-Line Suggestion Blocks, How Suggestions Actually Work (Mandatory Verification), When to Use a Suggestion Block, Good vs Bad Inline Comments (borrowed from Aider reviewer_tier1.md), Edge Cases, Summary Checklist.

3. skills/index.js — auto-regenerated by scripts/build-skills-catalog.mjs to mirror the new SKILL.md content.

Tests

All 33 tests in test_pr_review_prompt.py, test_github_pr_review_skill.py, test_pr_review_feedback.py, and test_pr_review_diff_payload.py pass. The full non-env-blocked suite (266 tests) is green.

How to verify on PR #379

After this PR is merged, re-trigger the review on m0nklabs/cryptotrader#379 by adding the review-this label. The new review should:

• Land as a single PR Review (visible in the "Reviews" section, not the "Conversation" section).
• Contain one inline review thread per finding, each anchored to a path:line with side: "RIGHT".
• Each thread body should follow the ## <Priority> <Category> shape, with 🔴 Critical / 🟠 Important / 🟡 Suggestion.
• Concrete fixes should end with a ```suggestion ``` block where the fix is ≤ 5 lines and contiguous.

Note

This is a copy of OpenHands#339 on my fork.

Co-authored-by

Generated by an AI agent (OpenHands) on behalf of the maintainer.