.agents/commands/comet/review-github-pr.md
Command: cursor review-github-pr
Given a PR number/URL (or auto-detected from the current branch), fetch the PR diff from comet-ml/opik, perform a thorough code review, present findings to the user, and post approved review comments directly on the PR. This is the complement of /address-github-pr-comments — that command responds to reviewer feedback, this command generates it.
This workflow will:
gh CLI is available and authenticated (stop if not)gh CLI alone is sufficient)gh api with AI watermark5395), full URL (e.g., https://github.com/comet-ml/opik/pull/5395), or omitted to auto-detect from current branchgh CLI: Verify gh is installed and authenticated (required for both reading and posting)
gh auth status
If not authenticated, respond with: "Please run
gh auth loginfirst." Stop here.
gh CLI for everything — no setup instructions needed.5395): Use as PR number directlyhttps://github.com/comet-ml/opik/pull/5395): Extract PR number from URLcomet-ml/opik:
gh pr list --repo comet-ml/opik --head <branch-name> --state open --json number,title,url
gh pr listgh pr view {pr_number} --repo comet-ml/opik --json title,body,author,baseRefName,state,headRefOid
Fetch existing review comments: Before analyzing, collect any comments already posted by this command on this PR
gh api repos/comet-ml/opik/pulls/{pr_number}/comments --paginate
🤖 *Review posted via /review-github-pr* markerpath + start_line + line for deduplication in step 6 (for single-line comments, start_line equals line)Get changed files: List all files changed in the PR
gh pr diff {pr_number} --repo comet-ml/opik --name-only
Get full diff:
gh pr diff {pr_number} --repo comet-ml/opik
If GitHub MCP is available: Use get_pull_request_files for structured file data (additions, deletions, patch)
Categorize files by domain:
apps/opik-backend/** → Java, API, services, DAOs, migrationsapps/opik-frontend/** → React, TypeScript, components, hookssdks/python/** → Python SDK patternssdks/opik-typescript/** → TypeScript SDK patternstests_end_to_end/** → Playwright tests*.md, docs/** → DocumentationSkip binary files and lock files from review
Flag sensitive files: Files matching patterns like .env, .pem, .key, credentials.*, *.secret should be flagged. Do not include raw content from these files in posted comments — instead, post a high-level note referencing the file without quoting secret values
Review the diff using Opik domain knowledge from .agents/skills/ and .agents/rules/. For each domain touched by the PR, apply the relevant review criteria:
apps/opik-backend/**)apps/opik-frontend/**)anysdks/**)Organize findings into categories with severity levels:
For each finding, prepare:
path + start_line + line as an existing /review-github-pr comment, mark it as "already posted" and exclude it from the list. If all findings are duplicates, print: "All findings were already posted in a previous run." and stop.Post approved comments as a single batched review to minimize notifications to the PR author. All inline comments are grouped into one review submission.
Collect all approved inline comments into a JSON payload and submit as one review:
gh api repos/comet-ml/opik/pulls/{pr_number}/reviews \
--input - <<'EOF'
{
"commit_id": "<head_sha>",
"event": "COMMENT",
"comments": [
{
"path": "<file_path>",
"line": <line_number>,
"side": "RIGHT",
"body": "<comment text with AI marker>"
},
{
"path": "<file_path>",
"start_line": <start_line>,
"line": <end_line>,
"start_side": "RIGHT",
"side": "RIGHT",
"body": "<multi-line comment text with AI marker>"
}
]
}
EOF
This sends one notification to the PR author regardless of how many comments are included.
If the batched review fails (e.g., a comment references a line not in the diff), fall back to posting comments individually. Identify which comments caused the failure and post the valid ones one by one:
gh api repos/comet-ml/opik/pulls/{pr_number}/comments \
-f body="<comment text>" \
-f path="<file_path>" \
-f commit_id="<head_sha>" \
-F line=<line_number> \
-f side="RIGHT"
Log any comments that still fail individually (e.g., line not in diff) and fall back to posting them as general PR comments instead.
When suggesting specific code changes, use GitHub suggestion syntax in the comment body:
<description of the suggestion>
```suggestion
<replacement code>
```
For comments not tied to a specific line (overall architecture, missing tests, etc.), post as issue comments. These cannot be included in the batched review and are posted separately:
gh api repos/comet-ml/opik/issues/{pr_number}/comments \
-f body="<comment text>"
Before posting any comment, scan the comment body for common secret patterns (API keys, bearer tokens, private key blocks, long hex/base64 strings, export VAR=value assignments). Replace any detected values with [REDACTED]. For files flagged as sensitive in Step 3, never include raw file content in comment bodies — reference the file and line range without quoting the actual values.
All posted comments must include a footer marker to distinguish them from human-written comments:
🤖 *Review posted via /review-github-pr*
🚫 **blocker** | Security
This query concatenates user input directly. Use parameterized queries instead.
```suggestion
String query = "SELECT * FROM traces WHERE id = ?";
jdbi.withHandle(h -> h.createQuery(query).bind(0, traceId).mapTo(Trace.class).one());
```
🤖 *Review posted via /review-github-pr*
💡 **suggestion** | Performance
Consider using batch insert here to avoid N+1 queries.
🤖 *Review posted via /review-github-pr*
🧹 **nit** | Style
This variable name could be more descriptive.
🤖 *Review posted via /review-github-pr*
❓ **question** | Architecture
Is this intentionally bypassing the service layer? The other endpoints go through SpanService first.
🤖 *Review posted via /review-github-pr*
After inline comments are handled, generate a general PR summary comment that gives the author a high-level view of the review.
👋 **Review summary**
**What looks good**
- <specific positive observation>
- <another positive observation>
**Overall**
<1–3 sentences on the PR as a solution>
**Inline comments**: <count by severity, e.g., "2 suggestions, 1 nit"> (or "None — looks clean!" if no findings were posted)
🤖 *Review posted via /review-github-pr*
Before generating, check if a summary comment from a previous run already exists (look for comments containing both 👋 **Review summary** and the AI marker). If found, inform the user: "A summary comment was already posted in a previous run." and skip this step.
gh api repos/comet-ml/opik/issues/{pr_number}/comments \
-f body="<summary comment>"
After all posting is complete, display to the user (not on GitHub):
gh not installed: Stop and provide installation instructionsgh not authenticated: Stop and instruct to run gh auth logingh authThe command is successful when:
gh CLI is available and authenticatedcomet-ml/opikgh CLI is the only hard requirement: GitHub MCP is optional and used for richer reading when available. All operations can be performed with gh CLI alone.COMMENT only — NEVER with "approve" or "request changes". Human reviewers must still formally approve./address-github-pr-comments: That command responds to existing review feedback. This command generates review feedback. Both post comments via gh api with AI markers.🤖 *Review posted via /review-github-pr* footer — never omit it.agents/skills/ and .agents/rules/ to provide relevant, project-specific feedback rather than generic code review/review-github-pr comments on the PR (matched by path + start_line + line). Safe to run multiple times — only new findings are posted.End Command