pr-review-output-format

PR Review Output Format

JSON Schema

Return your analysis as a JSON code block. Do not include any text before or after the JSON block — the orchestrator will parse this output directly.

{
  "lens": "<lens-identifier>",
  "summary": "2-3 sentence assessment from this lens perspective.",
  "strengths": [
    "Positive observation about what the PR gets right from this lens perspective"
  ],
  "comments": [
    {
      "path": "src/example.ts",
      "line": 42,
      "end_line": null,
      "side": "RIGHT",
      "severity": "critical",
      "confidence": "high",
      "lens": "<lens-identifier>",
      "title": "Brief finding title",
      "body": "🔴 **<Lens Name>**\n\n[Issue description — 1-2 sentences with enough context to understand standalone].\n\n**Impact**: [Why this matters — 1 sentence].\n\n**Suggestion**: [Concrete fix — 1-2 sentences, optionally with a code snippet]."
    }
  ],
  "general_findings": [
    {
      "severity": "minor",
      "lens": "<lens-identifier>",
      "title": "Cross-cutting finding title",
      "body": "Description of the finding that cannot be anchored to a specific diff line."
    }
  ]
}

Field Reference

• lens: Agent lens identifier (e.g., "architecture", "security", "test-coverage", "code-quality", "standards", "usability", "performance", "documentation", "database", "correctness", "compatibility", "portability", "safety")
• summary: 2-3 sentence assessment from this lens perspective
• strengths: Positive observations (fed into the review summary — never posted as inline comments)
• comments: Line-anchored findings for inline PR comments
  • path: File path relative to repository root (as shown in the diff header, e.g., src/auth/handler.ts)
  • line: Line number in the file where the comment should appear. For "RIGHT" side, this is the line number in the new version of the file. For "LEFT" side, this is the line number in the old version. The line MUST be visible in the diff (within a hunk).
  • end_line: Last line number for multi-line comments, or null for single-line. Must be in the same diff hunk as line.
  • side: "RIGHT" for commenting on added, modified, or context lines in the new file (the vast majority of comments). "LEFT" only for commenting on deleted lines.
  • severity: One of "critical", "major", "minor", "suggestion"
  • confidence: One of "high", "medium", "low"
  • lens: The lens identifier (same value as the top-level lens field). Included on each comment so the orchestrator can attribute findings after merging outputs from multiple agents.
  • title: Brief title for the finding (used in the summary index)
  • body: Self-contained comment body formatted for a GitHub PR inline comment. See "Comment Body Format" below.
• general_findings: Findings that cannot be anchored to specific diff lines (cross-cutting concerns, missing functionality, architectural observations)
  • severity, lens, title, body: Same semantics as in comments

Multi-Line Comment API Mapping

The agent schema uses line (start of range) and end_line (end of range). The GitHub API inverts this: start_line is the beginning and line is the end. The orchestrator handles this mapping when constructing the API payload.

Example — agent output:

{ "line": 10, "end_line": 15, "side": "RIGHT" }

Becomes API payload:

{ "start_line": 10, "start_side": "RIGHT", "line": 15, "side": "RIGHT" }

For single-line comments (end_line is null), the API payload uses only line and side — start_line and start_side are omitted entirely (not set to null).

Severity Emoji Prefixes

Use these actual Unicode emoji characters at the start of each comment body:

• 🔴 for "critical" severity
• 🟡 for "major" severity
• 🔵 for "minor" and "suggestion" severity

IMPORTANT: Use the actual Unicode emoji characters shown above (🔴 🟡 🔵), NOT text shortcodes like :red_circle:, :yellow_circle:, or :blue_circle:. The output is rendered as markdown, not Slack/Discord, so shortcodes will appear as literal text.

Comment Body Format

Each comment body should follow this structure:

[emoji] **[Lens Name]**

[Issue description — 1-2 sentences, standalone context].

**Impact**: [Why this matters].

**Suggestion**: [Concrete fix, optionally with a short code snippet].

Example:

🔴 **Architecture**

This module directly imports from the data layer, bypassing the service
boundary. This couples the API handler to the database schema.

**Impact**: Changes to the database schema will ripple into the API layer.

**Suggestion**: Introduce a service interface to mediate between the API and
data layers.

Diff Anchoring Guidelines

• Every finding in comments must reference a line number that is visible in the diff (within a hunk). Lines outside diff hunks will cause API errors.
• For findings about added or modified code, use the line number in the new file version and set side to "RIGHT".
• For findings about deleted code, use the line number in the old file version and set side to "LEFT".
• For findings spanning multiple lines, identify both the start line (line) and end line (end_line) within the same diff hunk.
• For findings that cannot be anchored to a specific diff line, classify them as general findings.
• When in doubt, use general_findings rather than risking an invalid line reference.

Output only the JSON block — do not include additional prose, narrative analysis, or markdown outside the JSON code fence. The orchestrator parses your output as JSON.