---
title: AI Reviewer Output Contract (Reviewer)
status: draft
---

# AI Reviewer Output Contract (Reviewer)

This document standardizes the payloads exchanged between the orchestrator and
domain reviewer subagents.

## Diff Payload (Input)

All reviewers receive a normalized diff payload from the orchestrator.

```
{
  "mode": "working-tree | branch-compare | pr-compare",
  "repo_root": "/path/to/repo",
  "base_ref": "release/2026.01",
  "head_ref": "feature/my-branch",
  "changed_files": ["src/foo.ts", "src/bar.php"],
  "code_files": ["src/foo.ts", "src/bar.php"],
  "task_files": ["includes/builder-5/.et/tasks/47600/47608/implementation-plan.md"],
  "patch": "... unified diff ...",
  "code_patch": "... unified diff without task files ...",
  "task_context": {
    "issue_numbers": ["47608"],
    "primary_issue_number": "47608",
    "implementation_plan_path": "includes/builder-5/.et/tasks/47600/47608/implementation-plan.md",
    "implementation_plan_excerpt": "## Problem Analysis ..."
  },
  "metadata": {
    "pr_url": "https://github.com/org/repo/pull/123",
    "pr_number": 123,
    "commit_count": 5
  }
}
```

Notes:
- `base_ref` and `head_ref` are optional for `working-tree`.
- `patch` may be a unified diff string or a list of file diffs.
- `code_patch` excludes task workflow files under `includes/builder-5/.et/tasks/**`.
- `task_context` is optional and used for scope alignment in change-intent review.

## Reviewer Output (Subagents)

Each reviewer must return structured JSON. Silence is allowed and preferred
when no findings exist.

```
{
  "reviewer": "security-reviewer",
  "findings": [
    {
      "title": "Missing capability check on admin action",
      "severity": "Blocker | Concern | Nit",
      "comment_label": "issue | suggestion | question | note | ... (optional)",
      "comment_decorations": ["blocking", "non-blocking", "..."],
      "confidence": 0.0,
      "locations": [
        {
          "path": "includes/admin.php",
          "lines": "L120-L145",
          "snippet": "if ( $action === 'delete' ) { ... }"
        }
      ],
      "rationale": "Action is gated only by a UI check.",
      "suggested_fix": "Add current_user_can() check before deletion.",
      "tags": ["auth", "privilege"]
    }
  ],
  "notes": "Optional short context or caveats."
}
```

Rules:
- `findings` can be empty.
- `confidence` is 0.0 to 1.0.
- Aggregate locations by theme instead of per-line spam.
- `comment_label` and `comment_decorations` optionally override default formatting.
- Default to **blocking issues**. Suggestions are allowed only when high-confidence and truly high-value.
- Avoid `note`-level feedback unless it changes how the author should interpret a blocking issue.

### Conventional Comments Guidance

Reviewers may choose `comment_label` and `comment_decorations` to control the
rendered PR comment. Use these labels and intent rules:

- `issue` + `blocking`: the default and expected label for merge-blocking problems.
- `suggestion` + `non-blocking`: allowed only when the suggestion materially improves correctness, safety, or maintainability, something that the author would really be thankful for and not annoyed by you raising it.

If `comment_label` is omitted, the orchestrator falls back to severity-based
labels. Use `comment_decorations` for qualifiers like `blocking`.
