Skip to main content
rule CX Codex

review-artifacts — Claude Code rule: what it does, how to install

review-artifacts is a Claude Code rule that stores code review results in a defined folder layout. It applies to files under .copilot-tracking/reviews/code-reviews/.

MIT ★ 1,627 updated 2026-10-25

Install into GitHub Copilot · Manually: put the files in place All methods and platforms ↓
.github/instructions/review-artifacts.instructions.md
Open on GitHub

What review-artifacts does

The rule defines where review outputs go and how their metadata is shaped. Each branch gets review.md, metadata.json, diff-state.json, and dispatch-manifest.json; slashes in the branch name become hyphens in the folder path.

Review verdicts are stored as approve, approve_with_comments, or request_changes. Interactive orientation-first runs can also produce a dispatch board, walkthrough, and supporting artifacts. Those extras are omitted in non-interactive workflows. Shared risk and review-depth data is written before work is dispatched to subagents.

Before writing artifacts, the rule calls for a fresh HEAD SHA from git rev-parse HEAD and the current UTC timestamp. Existing review.md and metadata.json files for the branch are overwritten, leaving only its latest review.

What it helps with

  • store a code review report and metadata by branch
  • normalize review verdicts for downstream use
  • share diff state and review depth with subagents
  • separate interactive review artifacts from workflow outputs

Example prompts for the agent

  • Save the code review for this branch under .copilot-tracking/reviews/code-reviews/.
  • Write review metadata with a normalized verdict and the changed file paths.
  • Create the interactive review artifacts and link them from review.md.

How to install review-artifacts

Manually: put the files in place

.github/instructions/review-artifacts.instructions.md

The applyTo field sets which files it applies to

Step by step, with commands for each platform: AGENTS.md vs CLAUDE.md: what they are and which one to use

Questions about review-artifacts

How do I install review-artifacts in Claude Code?

Add the rule file at .claude/rules/review-artifacts.md.

What does review-artifacts do?

It sets the folder layout and metadata format for code review results, including normalized verdict values. It also defines shared diff and review-depth state.

Which files are produced only in interactive mode?

Interactive orientation-first reviews can produce dispatch-board.md, walkthrough.md, explanations, research notes, and emission-record.json. Non-interactive runs omit those artifacts.

Source text

review-artifacts.instructions.md · MIT
---
description: "Code review artifact persistence: folder structure, metadata schema, verdict normalization, and writing rules"
applyTo: "**/.copilot-tracking/reviews/code-reviews/**"
---

<!-- markdownlint-disable-file -->

# Review Artifacts Persistence Protocol

Any code review agent that produces a structured verdict follows this protocol to enable CI integration and cross-agent artifact compatibility.

## Folder Structure

```text
.copilot-tracking/
  reviews/
    code-reviews/
      <sanitized-branch>/
        review.md              # full markdown review output
        metadata.json          # machine-readable summary (see schema below)
        diff-state.json         # shared subagent input (branch, base, files, depth)
        dispatch-manifest.json  # canonical loop state (phase gates, next actions, board items)
        dispatch-board.md       # human-readable enumerated dispatch board
        walkthrough.md          # factual Register 1 orientation narrative
        emission-record.json    # selected emission mode, target, status, outcome
        explanations/
          <board-item>-<symbol>.md   # per-item Register 1 explanation artifacts
        walkback/
          <board-item>-research.md   # per-item Register 2 investigation artifacts
```

Sanitize the branch name by replacing every `/` with `-`
(e.g. `feat/my-feature` → `feat-my-feature`).

The `review.md`, `metadata.json`, `diff-state.json`, and `dispatch-manifest.json`
artifacts are always produced. The orientation-first artifacts
(`dispatch-board.md`, `walkthrough.md`, `explanations/`, `walkback/`, and
`emission-record.json`) are produced only when the review runs in interactive
orientation-first mode; omit them in non-interactive workflow runs.

## metadata.json Schema

```json
{
  "schema_version": "1",
  "branch": "<original branch name, e.g. feat/my-feature>",
  "head_commit": "<full SHA of HEAD at time of review>",
  "reviewed_at": "<ISO 8601 UTC timestamp, e.g. 2026-02-27T10:00:00Z>",
  "verdict": "<normalized verdict - see table below>",
  "files_changed": ["<workspace-relative paths of source files in the diff>"],
  "findings_count": {
    "critical": 0,
    "high": 0,
    "medium": 0,
    "low": 0
  },
  "reviewer": "<agent or prompt name, e.g. code-review>",
  "artifacts": {
    "dispatch_manifest": "dispatch-manifest.json",
    "dispatch_board": "dispatch-board.md",
    "walkthrough": "walkthrough.md",
    "emission_record": "emission-record.json",
    "explanations": ["explanations/<board-item>-<symbol>.md"],
    "walkbacks": ["walkback/<board-item>-research.md"]
  }
}
```

The `artifacts` object records the orientation-first artifacts produced during
the review. Omit any key whose artifact was not produced (for example, omit
`artifacts` entirely for a non-interactive workflow run, or omit `explanations`
when no per-item explanation was requested). The `explanations` and `walkbacks`
values are arrays of review-folder-relative paths, one entry per board item
that was explained or investigated.

## Verdict Normalization

| Agent Output Verdict     | `verdict` value         |
|--------------------------|-------------------------|
| ✅ Approve                | `approve`               |
| 💬 Approve with comments | `approve_with_comments` |
| ❌ Request changes        | `request_changes`       |

## Orientation-First Artifacts

Interactive orientation-first reviews persist the following artifacts alongside
`review.md` and `metadata.json`. Each is referenced from `review.md` so the
markdown report links to the supporting evidence.

* `dispatch-manifest.json` — the canonical loop state: `phaseGates`,
  `currentPhase`, `nextActions`, and `boardItems`. This is the machine-readable
  source of truth for the human-steered walk-back loop.
* `dispatch-board.md` — the human-readable enumerated board rendered from the
  manifest `boardItems`: id, area, status, register, summary, openable links,
  and selectable symbols.
* `walkthrough.md` — the factual Register 1 orientation narrative (diff summary,
  runway summary, and appendices) presented before any findings register. It
  contains no severity grades or verdicts.
* `explanations/<board-item>-<symbol>.md` — per-item Register 1 explanation
  artifacts written by the explainer when a human asks a shallow factual
  question about a symbol. Each includes the answer, source file reference,
  relevant code excerpt, and follow-on symbols.
* `walkback/<board-item>-research.md` — per-item Register 2 investigation
  artifacts written by the walk-back researcher when a human asks a deep
  investigative question. Each is anchored to its board item.
* `emission-record.json` — the selected emission `mode` (native or canonical),
  `target` (PR, MR, ADO, or review artifact), `status` (completed or skipped),
  and a short outcome `summary`.

## Change-Risk Decision State

`diff-state.json` is the canonical owner of the evidence and depth decision used by every review lane:

* `reviewStateProvenance` records `human-confirmed` or `automation-derived` origins for `scope`, `changeRiskEvidence`, `recommendedDepth`, `depthTier`, and `depthRationale`. It describes origin, not confidence.
* `changeRiskEvidence` contains exactly one entry for each of `change-scope`, `path-criticality`, `history`, `test-presence`, `coverage`, and `rollback`.
* Each entry contains `signal`, `availability`, and `evidence`. The `availability` field records the evidence state, not confidence in a claim. Its value is `observed`, `unavailable`, or `qualitative`; unavailable inputs remain explicit and are never fabricated.
* `recommendedDepth` records the advisory `basic`, `standard`, or `comprehensive` recommendation. Use `standard` when evidence is incomplete or inconclusive unless observed evidence supports comprehensive review.
* In interactive mode, existing `depthTier` remains the human-selected verification depth, and `depthRationale` explains that selection and any difference from `recommendedDepth`. Mark scope, evidence, depth, and rationale as `human-confirmed`; keep the advisory recommendation `automation-derived`.
* In workflow mode, mark all five provenance values `automation-derived`. Host-supplied or default values are not represented as human-confirmed.

In interactive mode, write these values after human scope and depth confirmation. In workflow mode, write them after automated context preparation. Complete either write before perspective dispatch. Subagents consume the values and provenance as shared context but do not recalculate or overwrite them.

## Writing Rules

* Always overwrite any existing `review.md` and `metadata.json` for the branch: only the latest review per branch is retained.
* Obtain the HEAD commit SHA with `git rev-parse HEAD` immediately before writing artifacts.
* Obtain the current UTC timestamp immediately before writing artifacts:
  * In POSIX-compatible shells, use `date -u +%Y-%m-%dT%H:%M:%SZ`.
  * In PowerShell, use `Get-Date -AsUtc -Format "yyyy-MM-ddTHH:mm:ssZ"`.
* `files_changed` must list only source files present in the diff (additions, modifications, or deletions). Filter by relevance - e.g. `.py`, `.sh`, `.ts`, `.tf` - excluding lock files, binaries, and build output.
* Do not write artifacts if the diff was empty and the review was aborted.
* The `reviewer` field must use the kebab-case form of the agent's or prompt's `name` from its frontmatter (e.g. `Code Review` → `code-review`).
* Write orientation-first artifacts only when the review runs in interactive orientation-first mode; record each produced artifact under the `artifacts` key in `metadata.json` and link it from `review.md`.
* Keep `walkthrough.md` and `explanations/` artifacts factual (Register 1): no severity grades or verdicts. Keep `walkback/` artifacts in the structured investigation register (Register 2).
* Create the `explanations/` and `walkback/` subfolders only when at least one explanation or investigation artifact is written.
* Every `review.md` ends with a **Disclaimer and Human Review** section: the verbatim `## Code-Review` CAUTION disclaimer from `disclaimer-language.instructions.md` followed by an unchecked `- [ ] Reviewed and validated by a qualified human reviewer` checkbox. This section is always present, is always the final section, and the agent never checks the checkbox; only a human may convert `[ ]` to `[x]`.
* When the review scope targets a pull request or merge request, `review.md` includes a mandatory human-editable **PR Comment Draft** section with an unchecked posting checkbox. This section is the only place the general PR or MR comment is authored; the agent never reproduces the full drafted comment body in the conversational summary. The agent never checks the posting box; only the human may convert `[ ]` to `[x]`, and that check is the gate that authorizes posting the general PR or MR comment.

© microsoft · MIT · microsoft/hve-core

Similar IDE rules

All IDE rules for Code review and refactoring →

From the same set148

The whole set →
git-setup git-setup audits Git configuration with a single command, finds gaps, and proposes safe fixes for identity, editor, diff and merge tooling. CX Codex +1 ★ 1,627repo stars feasibility Structures and validates durable data and ML feasibility studies using constrained YAML and UUID-tracked provenance. CX Codex +1 ★ 1,627repo stars GitHub Backlog Executor The GitHub Backlog Executor subagent applies a prepared set of operations to GitHub issues and sub-issues in one confirmed repository. Use it to carry out backlog changes through GitHub. CX Codex +1 ★ 1,627repo stars backlog-plan backlog-plan plans backlog work in Azure DevOps, GitHub, and Jira without modifying remote trackers. Generates local plan files for sprints, triage, and task handoffs. CX Codex +1 ★ 1,627repo stars customer-card-render customer-card-render turns canonical Design Thinking markdown artifacts into PowerPoint slide YAML. The shared powerpoint skill pipeline then assembles the final deck. CX Codex +1 ★ 1,627repo stars evaluation-design evaluation-design designs evaluation datasets and metric guides for conversational agents and retrieval-grounded apps. Structures scoping interviews and validates test pairs. CX Codex +1 ★ 1,627repo stars pester This rule guides Claude Code in writing PowerShell tests with Pester. Use it to keep test files, mocks, and cleanup consistent with the repository. CX Codex +1 ★ 1,627repo stars typescript-doc-comments typescript-doc-comments — a Claude Code rule for writing TypeScript documentation comments following the TSDoc standard. Describes function behavior, constraints, and intent that the type signature alone cannot express. CX Codex +1 ★ 1,627repo stars

Project sponsors

Companies that keep this analytics open