#581 Send scoped subdiffs to deep-review-pro agents

[hubertgajewski]

Summary

Closes #581
Contributes to #587

Adds the /deep-review-pro scope-builder contract for per-agent prompt frames. The workflow now documents a complete CHANGED_FILES manifest, <changed-files> prompt block, agent-specific hunk selection, and conservative full-diff handling for the broad security/simplification/code/architecture reviewers.

Updates every specialist prompt so agents know their inline diff may be scoped and that Read, Grep, and Glob remain available for context outside the subdiff. Also records the prompt-footprint benchmark evidence in docs/deep-review-pro-benchmark/reports/581-agent-subdiffs.md.

Test plan

• python3 scripts/test_benchmark_deep_review_pro.py
• python3 -m coverage run -m unittest scripts.test_benchmark_deep_review_pro
• python3 -m coverage report -m scripts/benchmark-deep-review-pro.py scripts/test_benchmark_deep_review_pro.py
• git diff --check
• Manual security-review fallback: no injection/path traversal/parse-error/secret/permission findings in the changed docs and fixed-path tests.
• Manual deep-review-lite checklist: pass/N/A only; no blocking findings.
• Project As a tester I want to have basic Playwright tests for OrwellStat #1 Estimate field verified as 5.
• CI verifies the pushed branch.

Summary by CodeRabbit

Release Notes

• Refactor

  • Refined deep-review-pro agent dispatch to better scope information per agent role; broad reviewers receive full diffs while specialists receive targeted hunks with complete file manifests.
  • Streamlined agent prompt instructions and unified handling of empty diff/manifest conditions.

• Tests

  • Enhanced test coverage for agent prompt frames and scope selection with comprehensive assertions.

• Documentation

  • Updated agent documentation to clarify input handling and dispatch behavior.

[coderabbitai]

Warning

Review limit reached

@hubertgajewski, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 26 minutes and 32 seconds. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 63b9fdf1-045d-416d-b2a5-25778c285c36

📥 Commits

Reviewing files that changed from the base of the PR and between bad6aa6 and 8174b2b.

📒 Files selected for processing (9)

• .claude/agents/deep-review-architecture.md
• .claude/agents/deep-review-ci.md
• .claude/agents/deep-review-code.md
• .claude/agents/deep-review-python.md
• .claude/agents/deep-review-security.md
• .claude/agents/deep-review-typescript.md
• .claude/skills/deep-review-pro/SKILL.md
• docs/deep-review-pro-benchmark/reports/581-agent-subdiffs.md
• scripts/test_benchmark_deep_review_pro.py

📝 Walkthrough

Walkthrough

PR #592 implements agent-specific subdiffs for deep-review-pro by formalizing a scope-builder that derives CHANGED_FILES manifests and filtered diffs, hardening the PROMPT_FRAME contract against injection, and consolidating ten agent prompts to reference the unified contract instead of local boilerplate.

Changes

Deep Review Pro Scope Builder and Unified Agent Contract

Layer / File(s)	Summary
SKILL.md scope builder and contract hardening .claude/skills/deep-review-pro/SKILL.md	Formalizes scope builder deriving FILE_DIFFS and CHANGED_FILES manifest from diff/untracked inputs, adds entity-encoded injection defenses to PROMPT_FRAME contract, and updates parallel dispatch to pass agent-specific PROMPT_FRAME_ frames instead of shared prompt.
Agent prompts unified to PROMPT_FRAME contract .claude/agents/deep-review-*.md (10 files)	All specialist agent prompts (architecture, CI, code, docs, project-checklist, python, QA, security, simplification, typescript, unit-test) updated to reference centralized PROMPT_FRAME contract, add early-exit on empty diff+manifest, remove redundant untrusted-content boilerplate, and include complete changed-file manifest in "How to run" steps.
Documentation updates and benchmark report docs/AI_ASSISTANTS.md, docs/deep-review-pro-benchmark/reports/581-agent-subdiffs.md	Updated AI_ASSISTANTS.md to document per-agent vs. broad-reviewer prompt framing; added benchmark report with methodology, token-count comparisons (before/after across fixtures), and validation criteria for scoped subdiff dispatch.
Diff parsing and prompt-frame building functions scripts/benchmark-deep-review-pro.py	Added PromptFrameInput dataclass, constants for fence tags and prompt blocks, and functions to sanitize values, build/parse diffs, extract file manifests, and classify paths by review scope (docs, typescript, python, CI, QA, unit-test), enabling per-agent prompt-frame construction.
Test infrastructure for roster parsing and prompt-frame validation scripts/test_benchmark_deep_review_pro.py	Expanded roster parsing to 8 columns with ROSTER_FIELDS and prompt_scope validation, added helpers to read agent prompts and extract tagged blocks, and added test coverage for agent-specific prompt frame presence, scope selection across agents, untrusted-tag sanitization, and manifest generation from mixed diffs.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related issues

• #584: Centralizing the PROMPT_FRAME in SKILL.md and compacting per-agent boilerplate by replacing local instructions with brief references directly implements the boilerplate-reduction refactor.
• #586: New scope-builder, per-agent prompt-frame dispatch, and diff-classification functions implement the same primitives needed to support large-diff risk bucketing and scope-based dispatch.

Possibly related PRs

• hubertgajewski/orwellstat#588: Modifies the shared prompt-frame and diff-parsing logic in scripts/benchmark-deep-review-pro.py and test coverage in scripts/test_benchmark_deep_review_pro.py, with coordinated updates to docs/AI_ASSISTANTS.md.
• hubertgajewski/orwellstat#531: Updates the same agent prompt files (deep-review-qa, deep-review-ci, deep-review-security) to align instruction sections with renamed skill contracts and early-exit workflows.
• hubertgajewski/orwellstat#591: Overlaps on agent prompt instructions (deep-review-docs, deep-review-security, deep-review-project-checklist) with coordinated scope/early-exit alignment and also updates SKILL.md dispatch trigger logic.

Poem

🐰 A rabbit charts the review scope so fine,
Each agent gets its hunks, a manifest sign,
No redundant boilerplate, just contract divine,
Injection defenses woven through each line,
Subdiffs save tokens—efficiency sublime! ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and specifically summarizes the main change: sending scoped subdiffs to deep-review-pro agents instead of full diffs.
Linked Issues check	✅ Passed	The PR implementation addresses all key requirements from issue #581: scoped subdiffs for specialist agents [#581], complete changed-files manifest [#581], fence-tag sanitization [#581], and broad-context handling [#581].
Out of Scope Changes check	✅ Passed	All changes directly support the core objective of sending scoped subdiffs to agents. The benchmark report, prompt updates, and script enhancements are all within scope of issue #581.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feature/581

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}