feat: inject sorted git diff into broad review rule prompts

Rules with strategy all_changed_files or matches_together and a **/*
matcher now get git diff main..HEAD pre-fetched and injected into the
review instruction file. The diff is sorted by filepath to group files
by directory, reducing reviewer turn count. Diff is scoped to the
rule's source_dir so subdirectory .deepreview files get narrower diffs.

Also streamlines the /review skill to skip the get_configured_reviews
call and go straight to get_review_instructions.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: nhorton

plugins/claude/skills/review/SKILL.md

@@ -18,16 +18,12 @@ Only proceed past this section if the user wants to **run** reviews.
 
 ## How to Run
 
-1. First, call `mcp__deepwork__get_configured_reviews` to see what review rules are configured. This returns each rule's name, description, and which `.deepreview` file defines it. If reviewing specific files, pass `only_rules_matching_files` to see only the rules that apply. Share a brief summary of the active rules with the user before proceeding.
-   - **If no rules are configured**:
-     1. Use AskUserQuestion to tell the user there are no `.deepreview` rules set up yet and ask if they'd like the agent to auto-discover and suggest rules for this project.
-     2. If yes, invoke the `/deepwork` skill with the `deepwork_reviews` job's `discover_rules` workflow (which sets up native reviews, skill migration, documentation rules, and language-specific code review).
-     3. Stop here — do not proceed with running reviews if there are no rules.
-2. Call the `mcp__deepwork__get_review_instructions` tool:
+1. Call the `mcp__deepwork__get_review_instructions` tool directly:
    - **No arguments** to review the current branch's changes (auto-detects via git diff against the main branch).
    - **With `files`** to review only specific files: `mcp__deepwork__get_review_instructions(files=["src/app.py", "src/lib.py"])`. When provided, only reviews whose include/exclude patterns match the given files will be returned. Use this when the user asks to review a particular file or set of files rather than the whole branch.
-3. The output will list review tasks to invoke in parallel. Each task has `name`, `description`, `subagent_type`, and `prompt` fields — these map directly to the Task tool parameters. Launch all of them as parallel Task agents.
-4. Collect the results from all review agents.
+   - **If the result says no rules are configured**: Ask the user if they'd like to auto-discover and set up rules. If yes, invoke the `/deepwork` skill with the `deepwork_reviews` job's `discover_rules` workflow. Stop here — do not proceed with running reviews if there are no rules.
+2. The output will list review tasks to invoke in parallel. Each task has `name`, `description`, `subagent_type`, and `prompt` fields — these map directly to the Task tool parameters. Launch all of them as parallel Task agents.
+3. Collect the results from all review agents.
 
 ## Acting on Results
 

specs/deepwork/review/REVIEW-REQ-004-rule-matching-and-strategies.md

@@ -19,7 +19,7 @@ After discovering review rules (REVIEW-REQ-002) and changed files (REVIEW-REQ-00
 ### REVIEW-REQ-004.2: Review Task Data Model
 
 1. Each review task MUST be represented as a `ReviewTask` dataclass.
-2. The `ReviewTask` MUST contain: `rule_name` (str), `files_to_review` (list[str] — paths relative to repo root), `instructions` (str), `agent_name` (str | None), `source_location` (str — formatted as `"path:line"`), `additional_files` (list[str] — unchanged matching files, relative to repo root), `all_changed_filenames` (list[str] | None).
+2. The `ReviewTask` MUST contain: `rule_name` (str), `files_to_review` (list[str] — paths relative to repo root), `instructions` (str), `agent_name` (str | None), `source_location` (str — formatted as `"path:line"`), `additional_files` (list[str] — unchanged matching files, relative to repo root), `all_changed_filenames` (list[str] | None), `git_diff_output` (str | None — pre-fetched diff for broad rules, see REVIEW-REQ-004.11).
 3. `files_to_review` MUST always contain at least one file path.
 4. `source_location` MUST be formatted as `"{relative_path}:{line_number}"` where the path is relative to the project root (e.g., `"src/.deepreview:5"`).
 
@@ -71,3 +71,12 @@ After discovering review rules (REVIEW-REQ-002) and changed files (REVIEW-REQ-00
 1. Rules with the same name defined in different `.deepreview` files MUST produce independent `ReviewTask` objects. The system MUST NOT merge or combine matched files across rules from different source directories.
 2. When two `.deepreview` files in different directories define a rule with the same name and the same strategy, and changed files match both rules, the system MUST create separate `ReviewTask` objects — one per directory — each containing only the files that matched within its own `source_dir`.
 3. This isolation is a consequence of REVIEW-REQ-004.1.2 (files outside `source_dir` do not match) but is stated explicitly because `.deepreview` files can be templated or symlinked across directories, making same-name rules a common scenario.
+
+### REVIEW-REQ-004.11: Git Diff Injection for Broad Rules
+
+1. When a rule has strategy `"all_changed_files"` or `"matches_together"` AND its `include` patterns contain `**/*`, the system MUST run `git diff <merge-base>..HEAD` and attach the output to the resulting `ReviewTask` as `git_diff_output`.
+2. The git diff MUST be computed at most once per unique `source_dir` per `match_files_to_rules` invocation, even if multiple rules with the same `source_dir` qualify for injection.
+3. If the git diff command fails or produces empty output, `git_diff_output` MUST be `None`.
+4. Rules with strategy `"individual"` MUST NOT receive `git_diff_output`, regardless of their include patterns.
+5. The `ReviewTask` dataclass MUST include a `git_diff_output: str | None` field defaulting to `None`.
+6. When a rule's `source_dir` is a subdirectory of the project root, the git diff MUST be scoped to that subdirectory (via `-- <relpath>` pathspec). When `source_dir` equals the project root, the diff MUST cover the entire repository.

specs/deepwork/review/REVIEW-REQ-005-instruction-generation.md

@@ -16,6 +16,13 @@ For each `ReviewTask`, the system generates a self-contained markdown instructio
 6. When the task has `additional_files` (unchanged matching files), the file MUST contain an "Unchanged Matching Files" section listing those file paths.
 7. When the task has `all_changed_filenames`, the file MUST contain an "All Changed Files" section listing every changed filename for context.
 
+### REVIEW-REQ-005.7: Git Diff Section
+
+1. When a `ReviewTask` has a non-null `git_diff_output`, the instruction file MUST contain a section headed `## Output from \`git diff main..HEAD\` for you to review (sorted by filepath)`.
+2. The diff output MUST be rendered inside a fenced code block with the `diff` language tag.
+3. This section MUST appear after the "Files to Review" section and before the "All Changed Files" section.
+4. When `git_diff_output` is `None`, this section MUST be omitted.
+
 ### REVIEW-REQ-005.2: File Path Formatting
 
 1. File paths in the "Files to Review" section MUST be prefixed with `@` to trigger Claude Code's file-reading behavior (e.g., `@src/app.py`).

src/deepwork/review/config.py

@@ -49,6 +49,7 @@ class ReviewTask:
     source_location: str = ""  # e.g. "src/.deepreview:5"
     additional_files: list[str] = field(default_factory=list)  # Unchanged matching files
     all_changed_filenames: list[str] | None = None
+    git_diff_output: str | None = None  # Pre-fetched git diff for broad rules
 
 
 def parse_deepreview_file(filepath: Path) -> list[ReviewRule]:

src/deepwork/review/instructions.py

@@ -155,6 +155,14 @@ def build_instruction_file(task: ReviewTask, review_id: str = "") -> str:
             parts.append(f"- @{filepath}")
         parts.append("")
 
+    # Pre-fetched git diff for broad rules
+    if task.git_diff_output:
+        parts.append("## Output from `git diff main..HEAD` for you to review (sorted by filepath)\n")
+        parts.append("```diff")
+        parts.append(task.git_diff_output.rstrip())
+        parts.append("```")
+        parts.append("")
+
     # Additional context: all changed filenames
     if task.all_changed_filenames:
         parts.append("## All Changed Files\n")

src/deepwork/review/matcher.py

@@ -192,6 +192,75 @@ def _git_untracked_files(project_root: Path) -> list[str]:
         raise GitDiffError(f"git ls-files failed: {e.stderr.strip()}") from e
 
 
+def _should_inject_diff(rule: ReviewRule) -> bool:
+    """Check if a rule qualifies for git diff injection.
+
+    Rules with ``all_changed_files`` or ``matches_together`` strategy and
+    a ``**/*`` include pattern get the diff injected to reduce reviewer
+    turn count.
+    """
+    if rule.strategy not in ("all_changed_files", "matches_together"):
+        return False
+    return "**/*" in rule.include_patterns
+
+
+def _sort_diff_by_path(diff_text: str) -> str:
+    """Sort a unified diff's file hunks by path.
+
+    Splits on ``diff --git`` boundaries, sorts the chunks
+    alphabetically by file path (which naturally groups by directory),
+    and rejoins them.
+    """
+    if not diff_text.strip():
+        return diff_text
+
+    # Split into per-file chunks.  The first element before the first
+    # "diff --git" marker is usually empty or whitespace — preserve it.
+    parts = re.split(r"(?=^diff --git )", diff_text, flags=re.MULTILINE)
+    chunks: list[tuple[str, str]] = []
+    preamble = ""
+    for part in parts:
+        if part.startswith("diff --git "):
+            # Extract the b-side path: "diff --git a/x b/y" → "y"
+            first_line = part.split("\n", 1)[0]
+            b_path = first_line.rsplit(" b/", 1)[-1] if " b/" in first_line else first_line
+            chunks.append((b_path, part))
+        elif part.strip():
+            preamble += part
+
+    chunks.sort(key=lambda c: c[0])
+    sorted_parts = [c[1] for c in chunks]
+    if preamble:
+        sorted_parts.insert(0, preamble)
+    return "".join(sorted_parts)
+
+
+def _get_git_diff(project_root: Path, scope_dir: Path | None = None) -> str:
+    """Run ``git diff <base>..HEAD`` and return the output, sorted by path.
+
+    Uses the same base-ref detection logic as changed-file detection.
+    When *scope_dir* is provided and differs from *project_root*, the
+    diff is restricted to that subdirectory via ``-- <relpath>``.
+    The output is sorted by file path so that files in the same
+    directory are grouped together.
+    Returns an empty string on failure.
+    """
+    base_ref = _detect_base_ref(project_root)
+    merge_base = _get_merge_base(project_root, base_ref)
+    args = ["diff", f"{merge_base}..HEAD"]
+    if scope_dir is not None and scope_dir != project_root:
+        try:
+            rel = scope_dir.relative_to(project_root)
+            args += ["--", str(rel)]
+        except ValueError:
+            pass
+    try:
+        result = _run_git(project_root, *args)
+        return _sort_diff_by_path(result.stdout)
+    except subprocess.CalledProcessError:
+        return ""
+
+
 def match_files_to_rules(
     changed_files: list[str],
     rules: list[ReviewRule],
@@ -213,6 +282,8 @@ def match_files_to_rules(
         List of ReviewTask objects.
     """
     tasks: list[ReviewTask] = []
+    # Lazy-compute diff per source_dir, shared across qualifying rules
+    _cached_diffs: dict[Path, str] = {}
 
     for rule in rules:
         matched = match_rule(changed_files, rule, project_root)
@@ -223,6 +294,14 @@ def match_files_to_rules(
         all_filenames = changed_files if rule.all_changed_filenames else None
         source_location = format_source_location(rule, project_root)
 
+        # Lazily fetch diff for broad rules to reduce reviewer turn count
+        diff_output: str | None = None
+        if _should_inject_diff(rule):
+            scope = rule.source_dir
+            if scope not in _cached_diffs:
+                _cached_diffs[scope] = _get_git_diff(project_root, scope)
+            diff_output = _cached_diffs[scope] or None
+
         if rule.strategy == "individual":
             for filepath in matched:
                 tasks.append(
@@ -249,6 +328,7 @@ def match_files_to_rules(
                     source_location=source_location,
                     additional_files=additional,
                     all_changed_filenames=all_filenames,
+                    git_diff_output=diff_output,
                 )
             )
 
@@ -261,6 +341,7 @@ def match_files_to_rules(
                     agent_name=agent_name,
                     source_location=source_location,
                     all_changed_filenames=all_filenames,
+                    git_diff_output=diff_output,
                 )
             )
 

tests/unit/review/test_instructions.py

@@ -18,6 +18,7 @@ def _make_task(
     source_location: str = ".deepreview:1",
     additional_files: list[str] | None = None,
     all_changed_filenames: list[str] | None = None,
+    git_diff_output: str | None = None,
 ) -> ReviewTask:
     """Create a ReviewTask with sensible defaults."""
     return ReviewTask(
@@ -28,6 +29,7 @@ def _make_task(
         source_location=source_location,
         additional_files=additional_files or [],
         all_changed_filenames=all_changed_filenames,
+        git_diff_output=git_diff_output,
     )
 
 
@@ -138,6 +140,35 @@ def test_traceability_is_at_end(self) -> None:
         last_nonblank = [line for line in content.strip().split("\n") if line.strip()][-1]
         assert "This review was requested" in last_nonblank
 
+    # THIS TEST VALIDATES A HARD REQUIREMENT (REVIEW-REQ-005.7.1, REVIEW-REQ-005.7.2).
+    # YOU MUST NOT MODIFY THIS TEST UNLESS THE REQUIREMENT CHANGES
+    def test_includes_git_diff_section(self) -> None:
+        task = _make_task(git_diff_output="diff --git a/f.py b/f.py\n+hello\n")
+        content = build_instruction_file(task)
+        assert "## Output from `git diff main..HEAD` for you to review" in content
+        assert "```diff" in content
+        assert "+hello" in content
+
+    # THIS TEST VALIDATES A HARD REQUIREMENT (REVIEW-REQ-005.7.4).
+    # YOU MUST NOT MODIFY THIS TEST UNLESS THE REQUIREMENT CHANGES
+    def test_omits_git_diff_section_when_none(self) -> None:
+        task = _make_task(git_diff_output=None)
+        content = build_instruction_file(task)
+        assert "git diff" not in content
+
+    # THIS TEST VALIDATES A HARD REQUIREMENT (REVIEW-REQ-005.7.3).
+    # YOU MUST NOT MODIFY THIS TEST UNLESS THE REQUIREMENT CHANGES
+    def test_git_diff_section_after_files_before_all_changed(self) -> None:
+        task = _make_task(
+            git_diff_output="diff output",
+            all_changed_filenames=["a.py", "b.py"],
+        )
+        content = build_instruction_file(task)
+        files_idx = content.index("## Files to Review")
+        diff_idx = content.index("## Output from `git diff main..HEAD`")
+        changed_idx = content.index("## All Changed Files")
+        assert files_idx < diff_idx < changed_idx
+
     # THIS TEST VALIDATES A HARD REQUIREMENT (REVIEW-REQ-009.4.1, REVIEW-REQ-009.4.3).
     # YOU MUST NOT MODIFY THIS TEST UNLESS THE REQUIREMENT CHANGES
     def test_includes_after_review_section(self) -> None: