review-diff

Review code diffs for preservation of documented behavior and invariants.

Updated May 7, 2026
One-click install
npx skills add https://github.com/marktoda/cohesive --skill review-diff-marktoda
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: review-diff
Source: https://github.com/marktoda/cohesive/tree/main/skills/review-diff
Command: npx skills add https://github.com/marktoda/cohesive --skill review-diff-marktoda

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Manually verifying that code changes (PRs, branches, or uncommitted working changes) do not break existing system rules, invariants, and documented behavior is time-consuming and error-prone, especially for codebases with extensive institutional knowledge encoded in substrate.

Core Features & Use Cases

  • Scoped substrate discovery: Only scans files modified by the diff instead of the entire repository for fast, targeted reviews.
  • Parallel reviewer dispatch: Runs two specialized agents in parallel to assess both substrate alignment (preservation of behavior and invariants) and code structure quality.
  • Verdict-led output: Returns a ranked list of concrete findings with exact file references, required changes, and documentation to update, plus a clear Pass/Pass with notes/Needs substrate/Risky/Block verdict.
  • Use cases: Review PRs before merge, validate branch changes against existing specs, check uncommitted changes for cohesion issues, or verify post-implementation changes against a locked Cohesive design.

Quick Start

Use the review-diff skill to review your open PR for alignment with the codebase's existing documented behavior and invariants.

Frequently Asked Questions about review-diff

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I review a PR diff for code cohesion and invariant validation?

To review a PR diff for code cohesion, the Skill scopes substrate discovery to changed files and dispatches parallel agents to validate alignment with documented system behavior and named invariants. It outputs a verdict with ranked findings tied to exact file locations.

Can I check uncommitted working changes against existing system behavior?

Yes, you can check uncommitted working changes for cohesion issues. The Skill validates that your modifications preserve documented system behavior and named invariants, returning a Pass, Needs substrate, Risky, or Block verdict with required documentation updates.

How does diff review work for codebases with substrate tracking?

Diff review for codebases with substrate tracking works by scanning only modified files instead of the entire repository. It dispatches two parallel reviewer agents to assess substrate alignment and code structure quality, then returns a verdict-led review with concrete findings.

What is the best way to validate branch changes against locked Cohesive designs?

The best way to validate branch changes against locked Cohesive designs is to run a post-implementation verification review. The Skill checks change cohesion by validating preservation of documented system behavior and named invariants, outputting ranked findings with exact file references.

Does PR review work without scanning the entire repository?

Yes, PR review works without scanning the entire repository by scoping substrate discovery to only the files modified by the diff. This targeted approach enables fast, focused reviews while still validating alignment with existing documented behavior and invariants.

What limitations should I expect when checking code diffs for system cohesion?

When checking code diffs for system cohesion, the Skill requires a codebase with substrate tracking to validate documented behavior and named invariants. It is designed for pre-merge PR reviews, branch validation, uncommitted checks, and post-implementation verification against locked designs.