Code Review

title: Code Review Output Formats description: Report structure, findings schema, and persistence rules for review orchestrators and skill-backed subagents. ms.date: 2026-10-30

Output contract

Review findings should be expressed as structured data first, then rendered into a merged markdown report. The structured data format enables deterministic merging without re-parsing the narrative report.

Do not assign or propagate reviewer confidence or certainty ratings: numeric scores, percentages, qualitative labels, renamed fields, or prose badges. Use citations and specific evidence gaps instead. Apply this rule to inline and delegated work, resumed artifacts, JSON, Markdown, summaries, recovery output, and actual publication payloads. Preserve supported findings, severity, counts, verdicts, and attributed source excerpts or measured statistics. Remove prohibited metadata without dropping findings; if valid repair is unavailable, disclose the incomplete result and block publication. For human-edited drafts, request revision rather than silently rewriting the text.

{
  "summary": "<executive summary text>",
  "verdict": "approve | approve_with_comments | request_changes",
  "severity_counts": { "critical": 0, "high": 0, "medium": 0, "low": 0 },
  "changed_files": [
    { "file": "<path>", "lines_changed": "<description>", "risk": "High|Medium|Low", "issue_count": 0 }
  ],
  "findings": [
    {
      "number": 1,
      "title": "<brief title>",
      "severity": "Critical|High|Medium|Low",
      "category": "<category name>",
      "skill": "<skill name or null>",
      "file": "<path>",
      "lines": "<line range, e.g. 45-52>",
      "problem": "<description>",
      "current_code": "<code snippet or null>",
      "suggested_fix": "<code snippet or null>"
    }
  ],
  "positive_changes": ["<observation>"],
  "testing_recommendations": ["<recommendation>"],
  "recommended_actions": ["<action>"],
  "pr_comment_draft": {
    "applies": true,
    "event": "REQUEST_CHANGES | COMMENT | APPROVE",
    "body": "<pre-filled general PR or MR comment text>",
    "approved_for_posting": false
  },
  "out_of_scope_observations": [
    { "file": "<path>", "observation": "<text>" }
  ],
  "recommended_specialist_reviews": [
    {
      "concern": "<concern>",
      "signals_matched": ["<signal>"],
      "backing": "<agent/skill/doc>",
      "availability": "available|unavailable|manual",
      "action": "<handoff or guidance note>"
    }
  ],
  "security_plan_drift": {
    "baseline": {
      "state_file": "<path>",
      "plan_file": "<path>",
      "status": "complete|incomplete"
    },
    "filtered_findings": 0,
    "control_drift": [],
    "residual_planned_risks": [],
    "newly_introduced_threats": [],
    "insufficient_evidence": {
      "validated_controls": "diff-scoped evidence",
      "obsolete_plan_items": "diff-scoped evidence"
    }
  },
  "business_alignment": {
    "sources": [
      { "id": "<document id>", "type": "brd|prd|adr", "path": "<path>", "status": "<status>", "owner": "<owners or deciders>", "cited_as": "<original citation when a successor replaced it, else null>", "baseline": "base-ref|diff|head|unavailable" }
    ],
    "results": [
      {
        "source_id": "<document id>",
        "kind": "drift|stale-source|source-gap|possible-drift",
        "requirement_ids": ["<id>"],
        "stake": "MUST|SHOULD|COULD|WONT|untraced",
        "awareness": "unrecorded|developer-confirmed|owner-acknowledged",
        "owner_acknowledgment": "none|claimed-unverified|human-confirmed",
        "owner_acknowledgment_confirmed_by": "<reviewer who confirmed, or null>",
        "owner_acknowledgment_confirmed_at": "<ISO 8601 timestamp, or null>",
        "severity": "Critical|High|Medium|Low|null",
        "outcome_changed": true,
        "finding_number": "<merged finding number or null>",
        "evidence": "<path and lines or reason>"
      }
    ],
    "unresolved": [ { "citation": "<citation>", "reason": "<reason>" } ],
    "architecture_review_recommended": false
  },
  "risk_assessment": "<risk level and explanation>",
  "acceptance_criteria_coverage": [
    { "ac": "<AC text>", "status": "Implemented|Partial|Not found", "notes": "<explanation>" }
  ]
}

Fields that do not apply may be omitted or set to null or an empty array. The recommended_specialist_reviews field is present only when specialist signals fired. The security_plan_drift field is present only when a confirmed Security Planner baseline was correlated through the security-planning skill's drift capability; an executed drift result is not also added to recommended_specialist_reviews. The business_alignment field is present only when confirmed business-source context was compared through the rpi-review skill's alignment reference; an executed comparison is not added to recommended_specialist_reviews. In business_alignment.results, stake: "untraced" records a cited requirement whose stake depends on a missing goal link; rate it as SHOULD with a traceability gap, as the alignment reference defines. A BRD business rule or non-negotiable constraint retains its explicit MUST stake when its goal link is missing, and its evidence also records that traceability gap. kind separates rubric-rated drift from the fixed-severity stale-source (Medium) and source-gap (Low) alerts and the unassessed possible-drift result. Alerts set stake and awareness to null. A possible-drift result uses evidence for the evidence-gap reason and omits or sets to null both severity and finding_number; it never affects severity counts or the verdict. baseline records how a source was compared: base-ref at the base branch; diff against the diff's removed (pre-change) lines when the base revision was unreadable; head at the current revision for a new source or for demonstrably unchanged metadata or passages read through the bounded unreadable-base fallback; or unavailable when some modified passage had no recoverable pre-change text, such as an added-only passage. cited_as keeps a superseded citation that a successor replaced. owner_acknowledgment is claimed-unverified when the change or its PR only claims approval, and human-confirmed only after the reviewer confirms the owner's acknowledgment, in which case owner_acknowledgment_confirmed_by and owner_acknowledgment_confirmed_at record who confirmed it and when; both are null otherwise. The acceptance_criteria_coverage field is present only when the review had story or acceptance-criteria context. The pr_comment_draft object is present only when the review scope targets a pull request or merge request; its approved_for_posting flag stays false until the human checks the posting box in review.md.

Report skeleton

Structure the merged report in this order:

1. Metadata header with reviewer name, branch, date, aggregate severity counts, and a concise description.

2. Changed Files Overview with a unified table of reviewed files, risk levels, and issue counts.

3. Merged Findings with all issues renumbered and tagged by source perspective.

4. Security Plan Drift when confirmed plan context was correlated after the findings merge.

5. Business Alignment when confirmed business-source context was compared.

6. Acceptance Criteria Coverage when story context was provided.

7. Positive Changes and Testing Recommendations.

8. Recommended Actions and Out-of-scope Observations.

9. Recommended specialist follow-up reviews when specialist signals fired, with Sustainability pointing to https://learn.microsoft.com/azure/well-architected/sustainability/sustainability-get-started and the dated directional caveat from the Cross-Skill Forks registry.

10. Risk Assessment and the final verdict.

11. Stakeholder Note Draft, present only when the human accepted a note offer for a business-alignment finding.

12. PR Comment Draft, present only when the review scope targets a pull request or merge request (see the PR comment draft section below).

13. Disclaimer and human-review sign-off, always present as the final section (see the disclaimer and human-review sign-off section below).

Omit sections that only apply to perspectives or optional extensions that were skipped. The disclaimer and human-review sign-off section (item 13) is never omitted.

Security plan drift section

Render this section only when Code Review resolved and confirmed a Security Planner baseline, ran the security perspective, and correlated the merged security findings through the security-planning skill's drift capability.

• Include the baseline status, filtered-finding count, non-empty control drift, residual planned risk, and newly introduced threat entries.

• State that validated controls and obsolete plan items have insufficient evidence because Code Review findings are diff-scoped.

• Include a one-line pointer to the skill's Security Planning CAUTION disclaimer and default exclusions.

• Carry the same data in security_plan_drift; do not require downstream consumers to parse the rendered prose.

• Do not add the executed extension to recommended_specialist_reviews.

Business alignment section

Render this section only when Code Review confirmed business-source context and compared the change against it through the shared core of the rpi-review skill's alignment reference.

• List each source with its identifier, type, path, status, owner or deciders, and baseline, and name any superseded citation it replaced.

• List each result with its requirement identifiers, business stake, owner awareness, severity, whether an outcome changed, and the merged finding number when the result produced a finding. Show an untraced stake as "No goal link (rated as SHOULD)" so readers see the missing traceability, not a bare SHOULD. Label a claimed acknowledgment "Owner acknowledgment claimed, not verified" and a confirmed one with who confirmed it.

• Render alerts in plain words: "Stale document: <source> is <status>; compared against <successor>" or the update needed, and "Consider drafting or revising an ADR, BRD, or PRD: <source> does not cover <behavior>".

• List unresolved citations and possible-drift results that lacked evidence, with the reason and without a severity or finding number.

• State whether an architecture review is recommended.

• Carry the same data in business_alignment; do not require downstream consumers to parse the rendered prose.

• Do not add the executed extension to recommended_specialist_reviews.

Stakeholder note draft

Render a ## Stakeholder Note Draft section only after the human accepts the offer to draft a note for a Critical or High business-alignment drift finding, with one subsection per accepted note in the alignment reference's note format. The note is plain copy-ready text with no checkbox. It stays in the local review.md: never include it in the PR Comment Draft, line comments, or any native emission.

PR comment draft

When the review scope targets a pull request or merge request, review.md includes a human-editable PR Comment Draft section so the human can review and edit the general PR-level comment before any posting. This is the general PR or MR comment (not the inline findings), and it is gated by an explicit posting checkbox.

Render the section in review.md with this shape:

## PR Comment Draft (human review required)

<!-- PR or MR scope only. The agent pre-fills the body below from the verdict and top findings. Edit it freely. It is NOT posted until you check the box. -->

**Proposed event:** REQUEST_CHANGES <!-- one of REQUEST_CHANGES | COMMENT | APPROVE -->

**Comment body (edit before posting):**

> <pre-filled general PR or MR comment derived from the verdict and the highest-severity findings>

- [ ] Reviewed, edited, and approved this comment for posting to the PR

Authoring rules:

• Pre-fill the Proposed event from the normalized verdict: request_changes maps to REQUEST_CHANGES, approve_with_comments to COMMENT, and approve to APPROVE. The human may change it.

• Pre-fill the Comment body with a concise, courteous general comment that acknowledges the work, states whether changes are requested based on the verdict, and summarizes the top findings at a glance. Keep it self-contained so it reads well as a single PR comment.

• Leave the posting checkbox unchecked. The agent never checks it; only the human may convert [ ] to [x].

• Treat this checkbox as the human gate for posting the general PR or MR comment, per the interactive emission guardrails in the Emission Modes reference. Do not post the comment while the box is unchecked.

• Author the draft only in review.md. Do not reproduce the full drafted comment body in the conversational summary; the chat closeout links to this section instead of pasting it inline.

Disclaimer and human-review sign-off

Every review.md ends with a Disclaimer and Human Review section, always rendered last and never omitted. It contains the verbatim ## Code-Review > [!CAUTION] block from the disclaimer-language skill, followed by an unchecked - [ ] Reviewed and validated by a qualified human reviewer checkbox. The agent never checks this box; only a human may convert [ ] to [x]. This section restores the human-review gate as a codified part of the output contract rather than an emergent behavior of path-attached instructions. When that skill content is unavailable, the verbatim block cannot be reproduced: say so, do not paraphrase a substitute disclaimer, and stop before emitting the review. This site stops rather than degrades because the missing content is the deliverable itself, not wording that supports behavior specified elsewhere.

Narrative and board shapes

For orientation-first reviews, emit a factual walkthrough narrative before the detailed findings register. The walkthrough should be stored in the review folder and should be followed by an enumerated dispatch board that lists review items, their status, and the next action.

Use the following lightweight shapes:

• Narrative walkthrough — factual Register 1 prose with a diff summary, runway summary, and appendices.

• Dispatch board — an enumerated list or markdown table of board items with id, area, status, register, summary, links, and selectable symbols.

• Emission record — the selected emission mode, target, status, and a short outcome summary.

Persist and present

Do not present the full report until both review.md and metadata.json have been successfully written to disk.

1. Write the merged report and metadata to disk using the review-artifacts protocol.

2. Confirm both files exist before proceeding.

3. Present a compact summary in the conversation, not the full report.

The summary should include a metadata table, a changed-files table, a compact finding table, the verdict, and a link to the full report on disk. Problem descriptions, code snippets, and suggested fixes stay in review.md rather than the conversational response.

End the compact summary with an explicit Next actions hand-back per the closeout contract in the Emission Modes reference: link the report, instruct the human to open and edit it, and offer the human-gated emission action. When the scope targets a pull request or merge request, link the PR Comment Draft section rather than reproducing the drafted comment body inline. Do not end the run on the verdict and link alone.