nicolas-codemate/review-pr

Review PR

Comprehensive review of any PR by number. Combines product review (ticket alignment) and technical review (code quality), then optionally posts findings to GitHub as inline comments.

<constraints> - Do not review the code yourself in the current context — confirmation bias is exactly what we're guarding against. - Delegate the actual review to an Agent (`subagent_type: "code-reviewer"`). - The agent prompt must be fully self-contained (all text inline, no file paths to read). - Display the agent's review report verbatim — do not filter or soften findings. - Do not post to GitHub without explicit user confirmation. - All user communication in French, technical output in English. </constraints>

Process

Phase 1: Fetch PR Data

1. Parse PR number from arguments
2. Parse optional language flag for GitHub-published content:
   • Default: REVIEW_LANG = "fr" (French) — applies to inline comments and the global review summary posted on GitHub
   • Override if user passes --lang en / --lang fr, or signals it naturally ("in english", "en anglais", "review in english")
   • This flag controls only the language of GitHub-published content (inline comments + summary). The internal review report and conversation with the user follow the standard rules in the Language section
3. Auto-detect repo:

   REPO=$(gh repo view --json nameWithOwner -q .nameWithOwner)
   

4. Fetch PR overview:

   gh pr view <PR_NUMBER> --json title,state,author,baseRefName,headRefName,body,url,isDraft,labels
   

5. Fetch PR diff:

   gh pr diff <PR_NUMBER>
   

6. Store: PR_TITLE, PR_STATE, PR_BODY, PR_DIFF, PR_BASE, PR_HEAD, PR_URL, REVIEW_LANG

Phase 2: Extract Ticket Context

From the PR body and title, detect linked ticket/issue references.

Detection patterns (scan both PR_BODY and PR_TITLE):

• YouTrack: /\b[A-Z]+-\d+\b/ (e.g., PROJ-123, ABC-1)
• GitHub issue: /\b(?:closes?|fixes?|resolves?)\s+#(\d+)\b/i, or standalone #(\d+)

Resolution — when a reference is found, delegate retrieval to the fetch-ticket skill:

• Apply skill: ~/.claude/skills/fetch-ticket/SKILL.md with the detected ID
• It auto-detects the source (YouTrack via mcp__youtrack__get_issue + get_issue_comments, GitHub via gh issue view) and returns normalized markdown with description, status, and comments
• If multiple references are found, prefer the YouTrack one (more authoritative for product context); attach the GitHub reference as supplementary context

Fallback chain:

• YouTrack pattern detected but MCP unavailable / fetch fails: note the reference, fall back to PR body + title
• GitHub issue not found (404): fall back to PR body + title
• No reference detected at all: use PR body + title as the only product context

Store the result as TICKET_CONTENT (fetched ticket markdown when available, PR body + title otherwise).

Phase 3: Delegate Review to Fresh Agent

The code-reviewer agent must receive all context inline — it should not need to read any files.

Agent:
  subagent_type: code-reviewer
  description: "PR review #{pr_number}"
  prompt: |
    You are reviewing PR #{pr_number}: "{PR_TITLE}".
    PR state: {PR_STATE}. Branch: {PR_HEAD} -> {PR_BASE}.
    You have NO prior knowledge of this code. Review with fresh eyes.

    <ticket_context>
    {TICKET_CONTENT}
    </ticket_context>

    <pr_description>
    {PR_BODY}
    </pr_description>

    <project_conventions>
    {PROJECT_RULES from CLAUDE.md}
    </project_conventions>

    <diff>
    {PR_DIFF}
    </diff>

    Perform a complete code review following your review process.
    Return the full review report in markdown format (in English, as usual).

    IMPORTANT — budget discipline:
    - The diff above is your primary source. Avoid exhaustive codebase exploration;
      use Grep/Read only when a specific finding truly requires it.
    - The final report (including the JSON block below) is MANDATORY.
      Do not run out of turns mid-exploration — finalize the report first,
      add supporting exploration only if budget allows.

    IMPORTANT: At the end of your review, add a section:
    ## Inline Comments (for GitHub)
    Output a fenced JSON block with this exact structure:
    ```json
    {
      "status": "APPROVED" | "COMMENT" | "REQUEST_CHANGES",
      "summary": "Multi-section markdown summary (see formatting rules below)",
      "comments": [
        {
          "path": "relative/file/path.ext",
          "line": <line_number_in_new_file>,
          "body": "Structured markdown comment (see formatting rules below)"
        }
      ]
    }
    ```
    Rules for inline comments:
    - **Language**: write `summary` and every `body` in {REVIEW_LANG_FULL} (REVIEW_LANG = "{REVIEW_LANG}"). Keep code identifiers, file paths, and technical terms in their original form. Use proper accents when writing in French (é, è, ê, à, ù, ç).
    - Only include Critical and Important issues (not Minor/suggestions)
    - `line` is the line number in the NEW version of the file (right side of diff)
    - `path` is relative to repo root
    - If no inline comments needed, use an empty array
    - `status` maps your review verdict: APPROVED/NEEDS_CHANGES -> REQUEST_CHANGES/neutral -> COMMENT

    **Formatting rules — keep GitHub comments readable, not a wall of text:**

    `summary` structure (use real `\n\n` blank lines between sections in the JSON string):
    ```
    **Verdict** : <one-line verdict with emoji-free tag like [APPROVED] / [CHANGES REQUESTED] / [COMMENT]>

    ### Points forts
    - <bullet>
    - <bullet>

    ### Points d'attention
    - <bullet with file:line reference when relevant>
    - <bullet>

    ### Recommandation
    <1-2 sentences on next steps>
    ```
    - Keep each bullet to one line when possible
    - Skip a section entirely if it has no content (don't write "N/A")
    - Adapt section titles to `REVIEW_LANG` (e.g. "Strengths" / "Concerns" / "Recommendation" in English)

    `body` structure for each inline comment (use real `\n\n` blank lines in the JSON string):
    ```
    **<Severity tag>** : <one-line problem statement>

    <1-2 sentences explaining the impact or root cause>

    **Suggestion** : <concrete fix, can include a short code snippet in a fenced block>
    ```
    - Severity tag is `Critical` or `Important` (translated: `Critique` / `Important` in French)
    - Always separate the three parts with a blank line — never cram them into a single paragraph
    - Use inline code (`` `like_this` ``) for identifiers and short fenced blocks for multi-line suggestions
    - Keep the whole body under ~8 lines of rendered markdown; split into multiple comments if needed

Where {REVIEW_LANG_FULL} expands to "French" if REVIEW_LANG = "fr", "English" if REVIEW_LANG = "en".

Phase 4: Present Review Locally

1. Display the agent's review report verbatim
2. Parse the JSON block from the ## Inline Comments section
3. Show a summary:

   Review terminee: {status}
   - {N} commentaires inline prets a publier (langue: {REVIEW_LANG})
   - Fichiers concernes: {list}
   

Phase 5: Optional GitHub Push

Ask the user (mention the publication language so they can override before posting):

Publier cette review sur GitHub ? (Commentaires inline + summary seront postes en {REVIEW_LANG_FULL})
- Oui : publier telle quelle
- Modifier : editer avant publication (utile pour changer la langue, ex: "regenere en anglais")
- Non : garder en local uniquement

If the user asks to switch language at this stage, re-run Phase 3 with the new REVIEW_LANG (the rest of the review is unchanged, only the agent re-translates summary + body fields).

If "Oui" or "Modifier":

1. Construct the review payload. Preserve the multi-line markdown formatting from the agent's summary and each body — they contain real blank lines (\n\n) that must survive as JSON string escapes, otherwise GitHub renders them as a single wall of text.

   Prefer jq -n for safe escaping rather than hand-written JSON:

   REPO=$(gh repo view --json nameWithOwner -q .nameWithOwner)
   
   # Build payload with jq so multi-line strings are escaped correctly.
   # Replace the placeholders with the values from the agent's JSON block.
   jq -n \
     --arg body    "$SUMMARY_MARKDOWN" \
     --arg event   "$STATUS" \
     --argjson comments "$COMMENTS_JSON_ARRAY" \
     '{body: $body, event: $event, comments: $comments}' \
     > /tmp/pr-review.json
   
   # Post the review
   gh api "repos/$REPO/pulls/<PR_NUMBER>/reviews" --input /tmp/pr-review.json
   
   # Cleanup
   rm -f /tmp/pr-review.json
   

   If you build the JSON by hand instead, each newline inside summary or body must be written as the two-character escape \n in the JSON string — never as a raw line break, which would produce invalid JSON.

2. Confirm success:

   Review publiee sur {PR_URL}
   

If "Non": End. The review stays in the conversation only.

Edge Cases

Large Diffs

If the diff exceeds ~50,000 characters, truncate with a note:

(diff tronque a 50000 caracteres, {total} au total - focus sur les fichiers les plus importants)

Merged/Closed PRs

Review works identically - gh pr diff returns the diff regardless of state. When posting review comments on merged PRs, GitHub may reject inline comments if the commit SHA no longer matches. In that case, post as a single conversation comment instead:

gh api "repos/$REPO/issues/<PR_NUMBER>/comments" -f body="{full review text}"

No Linked Ticket

Review in "code quality only" mode - the product review section focuses on the PR description and whether the changes are self-explanatory.

Language

• User communication (in this Claude Code session): French
• Technical output (git commands, code snippets, internal review report from the agent): English
• GitHub-published content (inline comments + global review summary): controlled by REVIEW_LANG
  • Default: French (REVIEW_LANG = "fr")
  • Override: pass --lang en (or --lang fr) when invoking the skill, or signal naturally ("review in english", "en anglais")
  • Code identifiers, file paths, and technical terms always stay in their original form, regardless of language
  • When writing in French, use proper accents (é, è, ê, à, ù, ç) — never drop them