Context
#11605 needs bounded pilot children after the skill-runtime baggage inventory. #11902 / PR #11903 established the baseline: .agents/skills/pr-review/references/pr-review-guide.md is the largest measured hotspot at 56,962 bytes, and pr-review is the most visible source of operator friction around full-review-per-cycle bloat.
Duplicate / adjacency sweep:
- #10537 and its closed children (#10540, #10614) handled an earlier
pr-review modularization slice and measurement methodology, not the current cycle-aware full-review versus micro-delta contract.
- #11902 is the inventory child, not the pilot implementation.
- #11605 is the parent program and explicitly calls for a
pr-review pilot.
The Problem
The current review substrate can push agents toward repeating full formal reviews after every small author delta. That preserves rigor in form while destroying focus-window quality in practice: PR conversations become long context-drain artifacts, and future reviewers must parse historical walls to find the current blocker.
The operator direction is specific: one full review can be appropriate, but later cycles should become tight micro-delta re-reviews unless the author materially changes scope. The existing substrate already contains a follow-up template, but the hot path still lets routine review cycles expand into full-review ceremony.
The Architectural Reality
pr-review is an agent skill consumed directly by reviewers. Its router should stay small; heavy procedure belongs in referenced payloads, and rare branches belong behind trigger pointers per ADR 0007, ADR 0008, and the recursive Map-vs-Atlas discipline shipped in #11319.
The pilot must reduce loaded review-cycle surface without weakening merge gates: CI-green before formal review, exact-head verification, close-target audit, evidence audit, and formal GitHub review state still matter. The compression target is repeated prose and cycle-N ceremony, not epistemic rigor.
The Fix
Pilot a narrow pr-review compression pass focused on review-cycle density:
- Make the full-review versus follow-up-review decision explicit and cheap to apply.
- Make cycle-N reviews default to a compact delta contract when prior context and scope boundaries are known.
- Move historical anchors, rare branches, and examples behind trigger pointers instead of inline runtime prose.
- Remove or compress redundant sections that restate gates already enforced elsewhere, while preserving reviewer-side V-B-A.
- Keep graph-ingestion metric tags mechanically valid.
Contract Ledger Matrix
| Target Surface |
Source of Authority |
Proposed Behavior |
Fallback |
Docs |
Evidence |
| Cycle-1 review contract |
#11605, #11902 inventory, pr-review skill |
First substantive review still uses the full template when cold-cache or broad scope requires it |
Existing full-review template remains |
.agents/skills/pr-review/** |
Template lint / review-body lint still passes |
| Cycle-N review contract |
Operator direction + existing follow-up template |
Warm-cache narrow deltas use compact micro-delta follow-up shape |
Full review allowed when scope broadens or context is cold |
pr-review guide/template payloads |
A focused PR demonstrates reduced payload while preserving required anchors |
| Historical/provenance payload |
ADR 0007 / ADR 0008 / #11319 |
Incident stories move behind trigger pointers or atlas payloads |
Inline prose remains only where load-bearing |
pr-review references/audits |
Byte-count delta plus reviewer usability check |
| Evaluation metric anchors |
Retrospective ingestion contract |
Required [ARCH_ALIGNMENT] etc. anchors remain mechanically present |
lint-pr-review-body catches missing anchors |
pr-review assets |
Existing/new lint passes |
Decision Record impact
Aligned with ADR 0007 and ADR 0008. No ADR amendment expected unless implementation discovers a broader skill-shape rule gap.
Acceptance Criteria
Out of Scope
- Rewriting every skill.
- Changing the pull-request author workflow; that is #11605 AC5.
- Removing CI-green or exact-head verification gates.
- Deleting incident history; move it to better substrate if it remains useful.
- Changing Retrospective daemon metric tags.
Avoided Traps
- Adding another long anti-bloat section to fight bloat.
- Treating byte reduction as success if reviewers lose the actual merge-blocking signals.
- Reopening the entire PR-review philosophy instead of piloting the hottest measured surface.
- Making cycle-N reviews too terse for graph ingestion or author actionability.
Related
Parent: #11605
Depends on / informed by: #11902, PR #11903
Related prior compression work: #10537, #10540, #10614
Origin Session ID: 967e325b-d90a-43f4-9e91-c212e9bda746
Retrieval Hint: pr-review cycle-aware density compression micro-delta follow-up template full review bloat skill-runtime-baggage-inventory
Context
#11605 needs bounded pilot children after the skill-runtime baggage inventory. #11902 / PR #11903 established the baseline:
.agents/skills/pr-review/references/pr-review-guide.mdis the largest measured hotspot at 56,962 bytes, andpr-reviewis the most visible source of operator friction around full-review-per-cycle bloat.Duplicate / adjacency sweep:
pr-reviewmodularization slice and measurement methodology, not the current cycle-aware full-review versus micro-delta contract.pr-reviewpilot.The Problem
The current review substrate can push agents toward repeating full formal reviews after every small author delta. That preserves rigor in form while destroying focus-window quality in practice: PR conversations become long context-drain artifacts, and future reviewers must parse historical walls to find the current blocker.
The operator direction is specific: one full review can be appropriate, but later cycles should become tight micro-delta re-reviews unless the author materially changes scope. The existing substrate already contains a follow-up template, but the hot path still lets routine review cycles expand into full-review ceremony.
The Architectural Reality
pr-reviewis an agent skill consumed directly by reviewers. Its router should stay small; heavy procedure belongs in referenced payloads, and rare branches belong behind trigger pointers per ADR 0007, ADR 0008, and the recursive Map-vs-Atlas discipline shipped in #11319.The pilot must reduce loaded review-cycle surface without weakening merge gates: CI-green before formal review, exact-head verification, close-target audit, evidence audit, and formal GitHub review state still matter. The compression target is repeated prose and cycle-N ceremony, not epistemic rigor.
The Fix
Pilot a narrow
pr-reviewcompression pass focused on review-cycle density:Contract Ledger Matrix
pr-reviewskill.agents/skills/pr-review/**pr-reviewguide/template payloadspr-reviewreferences/audits[ARCH_ALIGNMENT]etc. anchors remain mechanically presentpr-reviewassetsDecision Record impact
Aligned with ADR 0007 and ADR 0008. No ADR amendment expected unless implementation discovers a broader skill-shape rule gap.
Acceptance Criteria
pr-reviewhot-path surface using #11902's measurement baseline.pr-reviewpayloads.Out of Scope
Avoided Traps
Related
Parent: #11605 Depends on / informed by: #11902, PR #11903 Related prior compression work: #10537, #10540, #10614
Origin Session ID: 967e325b-d90a-43f4-9e91-c212e9bda746
Retrieval Hint:
pr-review cycle-aware density compression micro-delta follow-up template full review bloat skill-runtime-baggage-inventory