#582 Reuse deep-review-pro rerun results

[hubertgajewski]

Summary

• Document /deep-review-pro result reuse cache keys, invalidation, targeted reruns, and REUSED: aggregate output.
• Include read-dependency content identities in cache eligibility, and force fresh dispatch when dependency telemetry is incomplete.
• Require one final full matching-agent pass before status: ready whenever cached results or targeted reruns were used.
• Update the AI assistant owner doc and add the [enhancement] Reuse unchanged deep-review-pro agent results across reruns #582 benchmark/fixture validation report.

Closes #582
Contributes to #587

Test plan

• python3 -m unittest scripts.test_benchmark_deep_review_pro
• 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 (99% total)
• git diff --check
• git diff --cached --check
• /deep-review-pro 593 Codex-equivalent matching-agent review, including final full matching-agent guard pass with 0 blocking findings
• gh pr checks 593 (all checks passing)

Summary by CodeRabbit

• New Features

  • Agent result reuse cache speeds re-review cycles by reusing prior non-blocking analyses, with targeted reruns when needed and a final guard pass before marking ready
  • Added reuse/dispatch accounting line in output summaries

• Documentation

  • Clarified reuse eligibility, reused-section labeling, invalidation triggers, and the final validation pass
  • Added benchmark report showing reuse/skip/dispatch behavior across iterations

• Tests

  • Added tests validating the reuse-cache contract and benchmark report contents

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: eea9c230-1a9d-49d0-9fb2-bec47d1c6fed

📥 Commits

Reviewing files that changed from the base of the PR and between a76c9b2 and 64e5ff9.

📒 Files selected for processing (3)

• .claude/skills/deep-review-pro/SKILL.md
• docs/AI_ASSISTANTS.md
• scripts/test_benchmark_deep_review_pro.py

🚧 Files skipped from review as they are similar to previous changes (3)

• docs/AI_ASSISTANTS.md
• .claude/skills/deep-review-pro/SKILL.md
• scripts/test_benchmark_deep_review_pro.py

---

📝 Walkthrough

Walkthrough

This PR adds an agent result reuse cache to deep-review-pro (keys: agent prompt hash, REFERENCES.md hash, exact scoped prompt-frame, optional read-dep identities), reuses non-blocking schema-valid cached results labeled REUSED:, adds reuse accounting lines and REUSED row semantics in summaries, requires a final full matching-agent pass when reuse/targeted reruns occurred, and adds benchmark report and fixture tests validating the behavior.

Changes

Agent Result Reuse Cache Implementation

Layer / File(s)	Summary
Deep Review Pro Skill Specification .claude/skills/deep-review-pro/SKILL.md	Defines cache key components (agent prompt hash, REFERENCES.md hash, dispatched prompt-frame, harness read-dependency identities), reusability and invalidation rules for non-blocking schema-valid results, targeted dispatch rules (only blockers/newly matched/invalidated agents), mandated final full matching-agent pass with reuse disabled before status: ready, and adds reuse: dispatched … skipped … reused … final_full_matching_pass accounting plus REUSED row semantics in the token/dispatch table.
Benchmark Report: Issue #582 Rerun-Cache docs/deep-review-pro-benchmark/reports/582-rerun-cache.md	Adds a benchmark report recording harness, token-availability constraints and (unavailable) runtime fields, proxy prompt-input token estimates, baseline vs optimized per-iteration dispatch/skip/reuse tables including the final guard pass, and a fixture-based validation section describing test assertions.
User-Facing Documentation docs/AI_ASSISTANTS.md	Documents /deep-review-pro reuse eligibility inputs, REUSED: labeling, invalidation/rerun triggers, and the requirement for a final full matching-agent pass before readiness when reuse/targeted reruns were used.
Fixture Tests for Contract and Report Validation scripts/test_benchmark_deep_review_pro.py	Adds two FixtureTests: one asserting the SKILL.md reuse-cache contract text (hash/identity fields and REUSED: messaging), and one asserting the Issue #582 rerun-cache report contains expected headings, metric/table rows, (unavailable) token entries, and the dispatch/reuse sequence validation rows.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related issues

• [epic] Reduce deep-review-pro token cost without lowering review quality #587: Similar enhancement request and prior work on reuse-across-reruns that aligns with this PR's reuse-cache implementation.

Possibly related PRs

• hubertgajewski/orwellstat#591: Extends the same benchmark validation flow and modifies scripts/test_benchmark_deep_review_pro.py fixture tests in a related way.
• hubertgajewski/orwellstat#588: Builds on the benchmark harness and reporting that this PR augments with the rerun-cache report.

Poem

🐰 A little cache beneath the code,
Saves unchanged answers down the road.
We skip, we reuse, then one last run,
Ready then rings—our work is done! 🎉

🚥 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
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title correctly identifies the main change: reusing deep-review-pro rerun results as described in issue #582, with clear reference to the issue number.
Linked Issues check	✅ Passed	The PR fulfills all coding requirements from #582: implements agent result reuse cache with proper invalidation, supports targeted reruns, requires final full matching-agent pass, and includes documentation and test coverage.
Out of Scope Changes check	✅ Passed	All changes directly address #582 requirements: skill documentation, assistant docs, benchmark report, and fixture tests are all in scope for the reuse-cache feature.

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

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

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

---

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.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.claude/skills/deep-review-pro/SKILL.md:
- Line 314: The fenced code block containing the lines starting with "###
<Agent>" and the verbatim example (the block that begins with "### <Agent>" and
the following sentinel examples) is missing a language tag; update the opening
fence to include a language identifier (e.g., "text") so it reads as a fenced
block with a language tag — change the opening "```" before the "### <Agent>"
block to "```text".

In `@scripts/test_benchmark_deep_review_pro.py`:
- Line 348: The test assertion uses the wrong expected substring; update the
assertion in the test that checks the variable skill_text (in
scripts/test_benchmark_deep_review_pro.py) to look for the actual text "cached
results or targeted reruns were used" instead of "cached or targeted reruns were
used" (or make it more robust by asserting presence of both "cached" and
"targeted reruns" separately or using a regex to match either variant) so the
test matches the real content in SKILL.md.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: e71eca07-f748-410d-b95e-f772b3c142d7

📥 Commits

Reviewing files that changed from the base of the PR and between 5e6947f and a76c9b2.

📒 Files selected for processing (4)

• .claude/skills/deep-review-pro/SKILL.md
• docs/AI_ASSISTANTS.md
• docs/deep-review-pro-benchmark/reports/582-rerun-cache.md
• scripts/test_benchmark_deep_review_pro.py