feat(advisor): batch simplicity review findings

[jyaunches]

Summary

The PR Review Advisor now completes a broad simplicity sweep before it commits scope findings, so one published review batches all visible, related refactoring recommendations. Blocker cards retain their evidence and required outcome, while concise implementation guidance renders once below the blockers.

Changes

• Review the full diff and surrounding code for lower-LOC and lower-concept end states.
• Compare direct changes, existing patterns, patterns applied across current related code, and deletion or consolidation opportunities.
• Require one ledger batch for all visible simplicity findings and rescan the proposed end state for follow-on recommendations.
• Render blocker-linked simplification metadata in a brief Recommended refactoring section.
• Document the maintainer-only behavior in the PR Review Advisor README. The required documentation writer review found no public docs/** update necessary.

Type of Change

• Code change (feature, bug fix, or refactor)
• Code change with doc updates
• Doc only (prose changes, no code sample modifications)
• Doc only (includes code sample changes)

Quality Gates

• Tests added or updated for changed behavior
• Existing tests cover changed behavior — justification:
• Tests not applicable — justification:
• Sensitive paths changed (security, policy, credentials, preflight, onboarding, inference, runner, sandbox, or messaging)
• Sensitive-path review completed or maintainer-approved waiver recorded — reviewer/approval link/justification:
• Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue:

DGX Station Hardware Evidence

• Tested on DGX Station
• Tested commit:
• Station profile/scenario:
• Result: Not applicable. scripts/prepare-dgx-station-host.sh is unchanged.
• Supporting evidence:

Verification

• PR description includes a Signed-off-by: line and every commit appears as Verified in GitHub
• Normal pre-commit, commit-msg, and pre-push hooks passed, or npm run validate:pr passed after refreshing origin/main when hooks were skipped or unavailable
• Targeted behavior tests pass for the current change set, or tests are marked not applicable above — npx vitest run test/pr-review-advisor-context.test.ts test/pr-review-advisor-rendering.test.ts test/pr-review-advisor-quality.test.ts (40 passed)
• Applicable broad gate passed — Not applicable for this focused advisor prompt and comment-rendering change.
• Quality Gates section completed with required justifications or waivers
• No secrets, API keys, or credentials committed
• npm run docs builds without warnings (doc changes only)
• Doc pages follow the style guide (doc changes only)
• New doc pages include SPDX header and frontmatter (new pages only)

---

Signed-off-by: J. Yaunches jmyaunch@gmail.com

Summary by CodeRabbit

• New Features

  • Added a comprehensive simplicity review covering deletion, consolidation, and pattern reuse.
  • Added batched, evidence-based refactoring recommendations with safety boundaries.
  • Added a dedicated Recommended refactoring section beneath blocker findings.

• Improvements

  • Blocker findings now remain focused, with simplification guidance presented separately.
  • Enhanced analysis of the full change set and surrounding code to identify lower-complexity alternatives.
  • Recommendations now align with the visible blocker limit for clearer, consistent review output.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 50877c21-bf3c-4eb4-8776-956b8dabfb53

📥 Commits

Reviewing files that changed from the base of the PR and between 8f5136b and a25908c.

📒 Files selected for processing (2)

• test/pr-review-advisor-rendering.test.ts
• tools/pr-review-advisor/comment.mts

Included review availability: Your plan provides up to 12 included reviews per hour; 10 remain after this review.

---

📝 Walkthrough

Walkthrough

The PR expands scope-risk simplicity analysis and separates simplification guidance from blocker evidence in rendered review comments. Tests and documentation cover analysis instructions, recommendation limits, section ordering, safety boundaries, and output behavior.

Changes

Simplicity review workflow

Layer / File(s)	Summary
Simplicity analysis guidance tools/pr-review-advisor/analyze.mts, tools/pr-review-advisor/README.md, test/pr-review-advisor-context.test.ts	The scope-risk stage reviews deletion, consolidation, pattern reuse, and abstraction across changed and surrounding code. It batches recommendations, rescans the proposed end state, preserves safety boundaries, and allows up to 12 notes.
Separate refactoring recommendations tools/pr-review-advisor/comment.mts, test/pr-review-advisor-rendering.test.ts, tools/pr-review-advisor/README.md	Blocker sections exclude inline simplification details. A dedicated Recommended refactoring section uses the displayed blocker subset. Tests verify ordering, content, finding identifiers, and the visible blocker cap.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Merge Risk: ⚪ Minimal · up to a2590

This change batches simplicity recommendations and updates their rendering and documentation; no actionable merge-blocking risk remains beyond normal checks and review.

Sequence Diagram(s)

sequenceDiagram
  participant ScopeRiskAnalysis
  participant ReviewLedger
  participant CommentRenderer
  ScopeRiskAnalysis->>ReviewLedger: record batched simplification recommendations
  ReviewLedger->>CommentRenderer: provide displayed blockers and simplification metadata
  CommentRenderer->>CommentRenderer: render blockers without inline simplification
  CommentRenderer->>CommentRenderer: append Recommended refactoring section

Loading

Suggested labels: chore

Suggested reviewers: apurvvkumaria, ericksoa, cv

🚥 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 clearly summarizes the main change: batched simplicity review findings in the PR Review Advisor.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/pr-advisor-simplicity-review

---

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

[jyaunches]

LOC Reduction / Codebase Simplicity Review

GitHub does not allow a formal changes-requested review on a self-authored pull request, so this comment records the equivalent blocking feedback.

Why this blocks

The blocker cards and their new refactoring section select different bounded sets. renderFindingsDetails renders only blockerFindings.slice(0, 20), then passes the complete blocker collection to appendRecommendedRefactoring, which filters and applies its own separate 20-item limit.

Those selections can diverge. With 21 blockers where only blocker 21 has simplification metadata, the comment displays a PRA-21 refactoring recommendation without displaying the corresponding blocker card. The new “blocker-linked” section therefore has two sources of truth for which blockers are visible.

Refactor direction

Compute the displayed blocker collection once:

• Slice blockerFindings once.
• Use that same collection for both blocker cards and appendRecommendedRefactoring.
• Remove the second slice from the helper.
• Cover the cap boundary with a rendering case where an omitted blocker has simplification metadata.

Expected result

Every refactoring recommendation refers to a blocker card visible in the same comment, the 20-item bound has one owner, and the renderer loses an independent selection rule.

[github-code-quality]

Code Coverage Overview

Languages: TypeScript

TypeScript / code-coverage/plugin

The overall coverage in commit a25908c in the codex/pr-advisor-sim... branch remains at 96%, unchanged from commit 9716534 in the main branch.

TypeScript / code-coverage/cli

The overall coverage in commit a25908c in the codex/pr-advisor-sim... branch remains at 83%, unchanged from commit a9fc804 in the main branch.

Show a code coverage summary of the most impacted files.

File	main a9fc804	codex/pr-advisor-sim... a25908c	+/-
src/lib/onboard...file-builder.ts	95%	91%	-4%
src/lib/state/p...l-retirement.ts	86%	84%	-2%
src/lib/adapter...ateway-drift.ts	61%	60%	-1%
src/lib/actions...post-restore.ts	80%	80%	0%
src/lib/actions...ild-pipeline.ts	90%	90%	0%
src/lib/actions...light-guards.ts	87%	87%	0%
src/lib/actions...me-preflight.ts	87%	87%	0%
src/lib/sandbox...rce-identity.ts	86%	86%	0%
src/lib/tunnel/services.ts	81%	81%	0%
src/lib/onboard...nt-authority.ts	75%	79%	+4%

---

_{Updated August 19, 2026 00:48 UTC}

[jyaunches]

LOC Reduction / Codebase Simplicity Review

Resolved

Resolved at exact head a25908c65d012ec921d4dec2dff6f3249b1c7d6a.

Simplification result

• renderFindingsDetails now computes the displayed blocker collection once.
• The same collection drives both the visible blocker cards and appendRecommendedRefactoring.
• The helper no longer applies an independent 20-item selection rule.
• The new 21-blocker boundary test proves that an omitted blocker cannot produce an orphaned refactoring recommendation.

Review outcome

The two-source blocker-selection issue identified in the prior comment is gone. I found no replacement LOC-reduction or codebase-simplicity blocker.

This closes only the LOC/codebase-simplicity review. It is not an approval or a judgment on other review dimensions.

[github-actions]

PR Review Advisor — No blocking findings reported

Advisor assessment: No blocking advisor findings reported
Next action: No advisor follow-up needed.
Findings: 0 blockers · 0 warnings · 0 suggestions

Model lanes

• GPT-5.6 Terra (primary): Completed · high confidence · 0 blockers · 0 warnings · 0 suggestions
• Nemotron 3 Ultra (second opinion): Completed · medium confidence · 0 blockers · 3 warnings · 0 suggestions
• Model comparison: normalized findings differ; normalized terminology decisions differ; normalized E2E selections match; Nemotron reported the same number of blockers, 3 more warnings, the same number of suggestions.

2 terminology differences from the second opinion

Advisory only. These are normalized differences from the primary terminology receipt.

• lowest-complexity coherent end state at tools/pr-review-advisor/analyze.mts:1916: selected only by the second-opinion lane as define.
• simplicity sweep at tools/pr-review-advisor/README.md:21: selected only by the second-opinion lane as define.

Second-opinion terminology and E2E selections are advisory. Live E2E does not run automatically for pull requests.

2 semantic terminology decisions

Terminology decisions are advisory. They affect the assessment only when a separate finding identifies concrete semantic impact.

• define — complete simplicity sweep at tools/pr-review-advisor/README.md:21: Define the term where it first appears and retain the stated contrast with diff-only review.
• define — Recommended refactoring at tools/pr-review-advisor/comment.mts:1206: Retain the section name and its distinction from blocker evidence.

E2E guidance

Advisory only. A maintainer can dispatch the default E2E suite for the commit under review.

Recommended E2E: None

Workflow run details

This automated review informs maintainers. Warnings and suggestions do not require a response. A maintainer decides whether to merge.

[prekshivyas]

Reviewed exact head a25908c. The full-diff simplicity sweep, single-batch finding guidance, and blocker-linked refactoring renderer preserve the existing visible-blocker cap and comment-size boundary. Focused advisor tests (41), CLI build/typecheck, signatures, threads, and current checks are clean.