Skip to main content
rule CX Codex

diff-computation — Claude Code rule: what it does, how to install

The diff-computation rule sets the order for code review: build the diff before reading files. Findings stay on changed lines, and large patches are read in chunks.

MIT ★ 1,627 updated 2026-10-25

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

What diff-computation does

The rule fixes the order of work: build the diff, then open source files. The agent runs git branch --show-current and git status --short and matches the first applicable case: a branch or PR, uncommitted edits on main, a code selection, a single commit, or nothing to review. Branch work goes through the pr-reference skill, which writes the patch to .copilot-tracking/pr/pr-reference.xml, lists changed files, and reads the diff in chunks with read-diff.sh --chunk N.

Findings stay inside the lines the diff adds or changes. Whole files are read for context only, and problems in untouched code go into a separate out-of-scope table that stays out of the verdict. Volume is handled in tiers: under 20 files analysed whole, 20 to 50 grouped by directory, above 50 in batches of 5-10 files. Past 2000 changed lines, or 500 in one file, commits get reviewed one at a time.

Lock files, minified bundles, source maps, binaries and build directories never enter the diff. All of it leans on the pr-reference scripts; when those are missing or fail, the rule falls back to git merge-base and git diff. A copy in .claude/rules/ does nothing by itself: code-review.agent.md has to pull the rule in with a #file: import, otherwise the agent never sees it.

What it helps with

  • compute a branch diff before the agent reads any source file
  • split a 2000-line diff into analysable chunks
  • keep lock files and minified bundles out of the review
  • separate feature-branch commits from uncommitted work on main
  • hold findings to changed lines only

Example prompts for the agent

  • Review the feature/login branch — compute the diff first, then read files.
  • Review my uncommitted changes on main, untracked files included.
  • This diff is huge; walk it chunk by chunk with read-diff.sh --chunk N and skip lock files.

How to install diff-computation

Manually: put the files in place

.github/instructions/diff-computation.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 diff-computation

How do I install diff-computation in Claude Code?

Place the file at .claude/rules/diff-computation.md in your project. For the review agent to pick it up, add a #file: import to code-review.agent.md.

What does diff-computation do?

It sets how a review agent obtains its diff: branch or commit detection, a scope locked to changed lines, chunked handling of large patches, and skipping of non-source files.

Does diff-computation need the pr-reference skill?

Branch reviews call its generate.sh and list-changed-files.sh scripts. If those are missing or fail, the rule computes the diff by hand with git merge-base and git diff.

Source text

diff-computation.instructions.md · MIT
---
description: "Code review diff computation: branch detection, scope locking, large-diff handling, and non-source filtering"
---

# Diff Computation Protocol

> Delivery: this file is delivered via the explicit `#file:` import in code-review.agent.md, not via `applyTo`. Plugin and extension distributions omit the repository artifact-root prefix, so a source-tree-qualified `applyTo` glob would match nothing once distributed. Future coding-standards agents or prompts that need this guidance must import it with `#file:` rather than relying on `applyTo`.

Obtain the diff before reading any source files. Use the decision tree below to determine the appropriate method, then apply scope rules and large diff handling.

## Decision Tree

Run `git branch --show-current` and `git status --short` to determine context. Match the first applicable case:

1. **Branch review** (user explicitly requests a specific branch or PR, or is on a feature branch that is not `main` and not detached HEAD): follow the Feature Branch Diff section. The pr-reference skill captures committed changes; a working-tree supplement captures staged, unstaged, and untracked changes. If the user says "review the PR" while on `main` or detached HEAD without naming a branch, PR, or commit, ask which branch or PR they want reviewed, then route to this case or to the Specific Commit section as appropriate.
2. **Local uncommitted changes on `main` or detached HEAD** (not on a feature branch, but edits exist that are not yet committed): follow the Uncommitted Changes section.
3. **Selected code or `#file` references** (user selects code in the editor or references `#file:path/to/file.ext`): follow the Selected Code section.
4. **Specific commit review** (user asks to review a particular commit): follow the Specific Commit section.
5. **No reviewable content**: inform the user that no diff could be determined and stop.

## Feature Branch Diff

Invoke the **pr-reference** skill to compute the diff. The skill handles branch detection, merge-base resolution, file listing, non-source exclusions, and large diff chunking.

1. Generate the structured diff to an explicit output path so that path is a single source of truth the review agent reuses for `diffPatchPath` (overridable, not implicitly coupled to the skill default):

   ```bash
   generate.sh --base-branch auto --merge-base --exclude-ext min.js,min.css,map --output .copilot-tracking/pr/pr-reference.xml
   ```

   ```powershell
   generate.ps1 -BaseBranch auto -MergeBase -ExcludeExt min.js,min.css,map -OutputPath .copilot-tracking/pr/pr-reference.xml
   ```

2. Get the changed file list:

   ```bash
   list-changed-files.sh --exclude-type deleted --format plain
   ```

   ```powershell
   list-changed-files.ps1 -ExcludeType Deleted -Format Plain
   ```

3. For large diffs, use chunk planning and batched analysis:

   ```bash
   read-diff.sh --info       # chunk count and size summary
   read-diff.sh --chunk N    # read chunk N
   ```

   ```powershell
   read-diff.ps1 -Info        # chunk count and size summary
   read-diff.ps1 -Chunk N     # read chunk N
   ```

If the changed-file list (`list-changed-files.sh` or `list-changed-files.ps1`) returns an empty list, stop and report "no reviewable content" per Decision Tree case 5.

Pass the diff output and file list as pre-computed input to the review agent so it skips its own scope detection.

## Uncommitted Changes

* Unstaged: `git diff HEAD`
* Staged: `git diff --cached`
* Untracked (new files not yet staged): enumerate with `git ls-files --others --exclude-standard`, then read the full content of each file as the review input.

## Selected Code

Use the provided code as the review input; no git diff is needed. Apply all loaded skills or review logic to the selected code. Skip artifact persistence since there is no branch context.

## Specific Commit

```bash
git diff <commit>^..<commit>
```

## Scope Rules

* Do not enumerate, list, or read source files before obtaining the diff or review input.
* Only lines present in the diff (added or modified lines) are in scope for findings.
* For selected code reviews (no diff context), all provided code lines are in scope.
* Read full file contents only for contextual understanding of diff lines, never as a source of findings.
* Pre-existing issues in unchanged code go in the **Out-of-scope Observations** table, clearly labelled and excluded from the verdict.

## Large Diff Handling

Use the `timeout` parameter on terminal commands to prevent hanging on large repositories.

| Changed Files | Strategy                                                       |
|---------------|----------------------------------------------------------------|
| Fewer than 20 | Analyze all files with full diffs.                             |
| 20 to 50      | Group files by directory and analyze each group.               |
| More than 50  | Progressive batched analysis, processing 5-10 files at a time. |

When a diff exceeds 2000 lines of combined changes or 500 lines in a single file, review the most recent commits individually using `git log --oneline` and `git show --stat`.

## Non-Source Artifact Skip List

Skip these artifacts when computing and analyzing diffs:

* Lock files: `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`
* Minified bundles: `.min.js`, `.min.css`
* Source maps: `.map`
* Binaries
* Build output directories: `/bin/`, `/obj/`, `/node_modules/`, `/dist/`, `/out/`, `/coverage/`

### Fallback (pr-reference skill unavailable)

If the pr-reference skill scripts are not found or fail, compute the diff manually:

1. Resolve the merge-base: `git merge-base origin/<default-branch> HEAD`
2. Generate the diff: `git diff <merge-base>...HEAD`
3. List changed files: `git diff <merge-base>...HEAD --name-only`
4. For uncommitted changes, supplement with `git diff HEAD`, `git diff --cached`, and `git ls-files --others --exclude-standard`

Apply the Non-Source Artifact Skip List and Large Diff Handling rules to the manual output.

© microsoft · MIT · microsoft/hve-core

Similar IDE rules

All IDE rules for Code review and refactoring →

From the same set148

The whole set →
analysis-authoring analysis-authoring provides authoring standards for exploratory notebooks and dashboards, covering section flow, plot selection, and validation budgets. CX Codex +1 ★ 1,627repo stars RPI Reviewer RPI Reviewer reviews an assigned slice of RPI evidence and returns candidate findings with locations. Useful when a large comparison needs to be split up. CX Codex +1 ★ 1,627repo stars rai-standards rai-standards is a Claude Code skill that organizes responsible AI references: NIST AI RMF 1.0, the AI STRIDE overlay, and EU AI Act requirements across development stages. CX Codex +1 ★ 1,627repo stars data-catalog Build a Markdown data catalog with declared entities and relationships. Use the skill to inventory engagement data or prepare a catalog for ERD rendering. CX Codex +1 ★ 1,627repo stars Supply Chain Skill Assessor Supply Chain Skill Assessor runs a supply-chain review against the supply-chain-security skill and returns a findings table: what passes, what is partial, where the gap sits. Handy before a release or a CI review. CX Codex +1 ★ 1,627repo stars privacy-standards privacy-standards is a Claude Code skill that provides privacy engineering references for data-flow analysis, DPIA thresholds, and open compliance standards. CX Codex +1 ★ 1,627repo stars copilot-tracking This rule organizes working files for RPI, HVE Builder, and related workflows under .copilot-tracking/. It sets paths and formatting conventions for research, plans, changes, and reviews. CX Codex +1 ★ 1,627repo stars demo-video Assembles demo videos from ordered frames or clips, WAV narration, and transitions via FFmpeg. Built for first-pass prototype walkthroughs and tutorials. CX Codex +1 ★ 1,627repo stars

Project sponsors

Companies that keep this analytics open