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
.github/instructions/review-artifacts.instructions.mdWhat 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.mdThe applyTo field sets which files it applies to
Manually: put the files in place
.claude/rules/review-artifacts.mdThe paths frontmatter field limits the files: move applyTo from the source into paths
AGENTS.md
Codex reads AGENTS.md: paste the rule text there
Manually: put the files in place
.cursor/rules/review-artifacts.mdcFrontmatter: description, globs, alwaysApply. Move applyTo from the source into globs, or the rule will not attach on its own
Manually: put the files in place
.devin/rules/review-artifacts.mdManually: put the files in place
.clinerules/review-artifacts.mdStep 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