---
id: 11893
title: Compress PR-review hot path with deletion-first templates
state: CLOSED
labels:
  - documentation
  - enhancement
  - ai
  - architecture
  - model-experience
assignees:
  - neo-gpt
createdAt: '2026-05-24T11:49:39Z'
updatedAt: '2026-05-24T12:20:11Z'
githubUrl: 'https://github.com/neomjs/neo/issues/11893'
author: neo-gpt
commentsCount: 1
parentIssue: 11605
subIssues: []
subIssuesCompleted: 0
subIssuesTotal: 0
blockedBy: []
blocking: []
closedAt: '2026-05-24T12:20:11Z'
---
# Compress PR-review hot path with deletion-first templates

## Context

Operator direction on 2026-05-24: the PR-review / PR-lifecycle substrate has become a major focus-window and velocity drain. Discussion #11891 converged on a deletion-first direction after live examples from the current templates and workflow docs.

This is a focused child implementation ticket under #11605. It does not create a new governance root. It executes the first deletion-first slice from Discussion #11891 and routes through the existing compression lineage:

- #10429 / #10537: documentation compression and pr-review modularization.
- #10732 / #10733 / #10757: cognitive-load audit and mutation-gate line.
- #11605 / #11884: skill baggage compression into decision-atom maps.
- #11604: codify-deferral discipline for premature skill bloat.
- #11440 / #11887: review-loop circuit breaker and micro-delta direction.
- #11603: meta-bandwidth saturation counter-bias.

## Duplicate Sweep

No open equivalent ticket was found.

Related but not duplicate:

- #10905 created the CI / Security Checks Audit and explicitly added template checklist surfaces. This ticket removes redundant template prose while preserving the CI precondition audit substrate.
- #11546 added the Collapsed-N/A audit conciseness rule. This ticket does not directly remove that rule; it shrinks upstream audit sections so the collapse rule becomes less necessary by emergence.
- #10537, #10560, and #10733 measured or split PR-review loaded surfaces but did not perform this deletion-first template compression pass.
- #11605 is the parent compression epic; this ticket is a concrete child slice.

Fallback sweep notes: Knowledge Base ticket query returned `Error finding id`; exact local sweeps found the related issues above and no equivalent open implementation ticket.

## Ungraduated Discussion Exception

Discussion #11891 is still open, but early filing is intentional per operator direction to stop idling and resume v13 progress.

Substantive rationale:

- The work is no longer speculative: the first slice names concrete duplicated surfaces in current files.
- The implementation is deletion-first and net-shrinking, so premature ticket gravity risk is lower than another discussion cycle.
- The ticket remains bounded to the first slice; future lifecycle-wide compression can continue through #11891 / #11605.

Divergence matrix:

| Shape | Outcome | Disposition |
|---|---|---|
| Keep shaping #11891 only | More convergence hygiene, no v13 progress | Rejected by operator direction; we already have concrete deletion candidates |
| Create a new epic | Duplicates #11605 / #10757 and adds more management surface | Rejected; this belongs as a child slice under #11605 |
| File one focused child ticket | Gives agents an actionable deletion-first lane without over-scoping | Selected |
| Edit templates directly without ticket | Violates tracked-edit gate and loses A2A context bridge | Rejected |

Expected refresh points after #11891 continues: follow-up tickets may refine lifecycle-wide budgets, pull-request workflow compression, or why-first documentation changes.

## The Problem

The current PR-review hot path repeats audit and provenance material inside the default templates even when the relevant condition is already a precondition or narrow edge case.

Concrete verified examples:

- `pr-review-template.md` and `pr-review-followup-template.md` both contain full `CI / Security Checks Audit` checklist blocks.
- `pr-review/audits/ci-security-audit.md` already defines CI as a pre-formal-review gate: pending or failing CI stops the formal review before the template should be completed.
- `pr-review-template.md` renders narrow-trigger audit sections such as Provenance, Source-of-Authority, and Wire-Format Compatibility as default review-body material, usually becoming N/A ceremony.
- `pr-review-followup-template.md` is still too close to a reduced full review; it should be a true micro-delta surface for cycle-N review.
- `pr-review-guide.md` carries incident archaeology and stale PR timelines inline in hot-path rule prose.

## Architectural Reality

Current surfaces:

- `.agents/skills/pr-review/assets/pr-review-template.md`
- `.agents/skills/pr-review/assets/pr-review-followup-template.md`
- `.agents/skills/pr-review/references/pr-review-guide.md`
- `.agents/skills/pr-review/audits/ci-security-audit.md`
- Existing audit sibling pattern under `.agents/skills/pr-review/audits/`
- Progressive Disclosure authority: ADR 0008 and `.agents/skills/create-skill/references/skill-authoring-guide.md`

The selected shape preserves rigor by keeping gates and audits accessible, but removes repeated default-render prose when a compact trigger or precondition is enough.

## The Fix

Implement the first deletion-first compression pass:

1. Remove the full CI / Security checklist blocks from both PR-review templates. Preserve the CI gate in `audits/ci-security-audit.md` and the guide trigger.
2. Keep the Collapsed-N/A rule for now. It currently shortens the symptom; upstream audit shrinkage should make it less necessary over time.
3. Collapse or pointerize narrow-trigger default template audits: Provenance, Source-of-Authority, and Wire-Format Compatibility.
4. Convert `pr-review-followup-template.md` into a true micro-delta form: status, prior anchor, changed surfaces, delta findings, required actions, hand-off.
5. Compress follow-up metrics to a default unchanged-by-reference line with explicit deltas only when needed.
6. Move or delete inline incident archaeology in `pr-review-guide.md` where stable intent and references are sufficient.
7. Preserve required graph-ingestion anchors and review metric tags.

## Contract Ledger Matrix

| Target Surface | Source of Authority | Proposed Behavior | Fallback | Docs | Evidence |
|---|---|---|---|---|---|
| PR-review cycle-1 template | Discussion #11891 + this ticket | Default template no longer repeats CI checklist or full rare-trigger audit prose | If parser requires anchors, keep terse canonical headings with trigger text only | `pr-review-template.md` | Diff line count + lint-pr-body / review-template validation where available |
| PR-review follow-up template | Discussion #11891 + #11440/#11887 | True micro-delta surface for cycle-N review | If semantic delta appears, reviewer returns to full cycle-1/cold-cache review shape | `pr-review-followup-template.md` | Diff line count + sample shape review against required anchors |
| CI / Security audit | #10905 + `ci-security-audit.md` | CI remains a pre-formal-review gate; formal template does not duplicate hold/fail checklist | Limited CI-triage note remains allowed when CI is failing and author asks for help | `audits/ci-security-audit.md`, guide trigger | Grep proves no duplicate checklist in templates; audit payload remains |
| Rare-trigger audits | Progressive Disclosure / ADR 0008 | Rare audits load/render only on their trigger or as terse trigger pointers | If a review has findings, expand the audit under canonical heading | template + audit siblings if needed | Template diff preserves discoverability without N/A bulk |
| Incident archaeology | Discussion #11891 | Hot-path guide prose states stable intent; historical examples move to provenance references or are deleted when no longer load-bearing | Keep an anchor only where it is still required to prevent a known high-severity regression | guide / audit references | Review confirms no stale line-number or ticket-timeline dependency in hot prose |

## Decision Record Impact

Aligned with ADR 0007 and ADR 0008. No ADR amendment expected. This applies existing Map vs World Atlas / Progressive Disclosure discipline to PR-review hot-path templates and guide prose.

## Discussion Criteria Mapping

- #11891 deletion-first direction: AC1, AC2, AC3, AC4, AC5.
- #11891 CI-precondition duplication: AC1 and AC6.
- #11891 narrow-trigger audit compression: AC2 and AC6.
- #11891 true cycle-N micro-delta shape: AC3 and AC4.
- #11891 provenance/archaeology split: AC5.
- #11891 no-better-linter primary solution: AC7 and AC8.

## Acceptance Criteria

- [ ] AC1: Remove full `CI / Security Checks Audit` checklist blocks from both PR-review templates while preserving CI fail-fast behavior in `audits/ci-security-audit.md` and the guide trigger.
- [ ] AC2: Provenance, Source-of-Authority, and Wire-Format Compatibility audit surfaces no longer render as full default template sections for ordinary PRs; they are trigger pointers, sibling payloads, or terse canonical headings that expand only when applicable.
- [ ] AC3: `pr-review-followup-template.md` is reduced to a true micro-delta template and is substantially smaller than its current 136-line shape.
- [ ] AC4: Follow-up metrics default to unchanged-by-reference unless a metric changed; changed metrics still preserve the required metric tags.
- [ ] AC5: Inline empirical-anchor archaeology in `pr-review-guide.md` is moved to references or removed where stable intent is sufficient.
- [ ] AC6: Required formal-review anchors used by lint / graph ingestion remain valid; implementation documents which anchors were preserved and why.
- [ ] AC7: Net recurring hot-path line count decreases. PR body reports before/after line counts for the touched lifecycle files.
- [ ] AC8: No new audit/checklist/linter surface is introduced to justify the deletion.
- [ ] AC9: `node ai/scripts/lint/lint-skill-manifest.mjs --base origin/dev` passes, or any failure is unrelated and documented.
- [ ] AC10: Relevant PR-review template validation / lint-pr-body check is run if available; otherwise document the exact unavailable surface.

## Out of Scope

- No removal of V-B-A or PR-review rigor.
- No broad rewrite of pull-request or ticket-create workflows in this first slice.
- No direct removal of the Collapsed-N/A rule in this ticket.
- No new skill and no AGENTS.md expansion.
- No historical PR conversation rewrite.

## Avoided Traps

- Rejected: creating another anti-bloat linter as the primary fix. Existing guardrails did not stop additive drift.
- Rejected: removing the Collapsed-N/A rule first. It currently shortens the symptom.
- Rejected: hiding rare audits so deeply that reviewers cannot find them when the trigger fires. Trigger pointers must remain discoverable.
- Rejected: treating CI as optional. CI remains a hard precondition; only duplicate template prose is removed.

## Related

- Discussion #11891: https://github.com/orgs/neomjs/discussions/11891
- Parent epic: #11605
- Related: #10905, #11546, #10537, #10560, #10733, #11440, #11887, #11604, #11603, #11890

Origin Session ID: 967e325b-d90a-43f4-9e91-c212e9bda746

Handoff Retrieval Hints:

- Query Memory Core for `Discussion #11891 deletion-first PR review hot path CI checklist micro-delta`.
- Query Memory Core for `guardrail paradox lint-skill-manifest byte budgets additive micro rules`.
- Exact surfaces: `pr-review-template.md`, `pr-review-followup-template.md`, `pr-review-guide.md`, `ci-security-audit.md`.

## Timeline

- 2026-05-24T11:49:39Z @neo-gpt assigned to @neo-gpt
- 2026-05-24T11:49:40Z @neo-gpt added the `documentation` label
- 2026-05-24T11:49:40Z @neo-gpt added the `enhancement` label
- 2026-05-24T11:49:40Z @neo-gpt added the `ai` label
- 2026-05-24T11:49:40Z @neo-gpt added the `architecture` label
- 2026-05-24T11:49:40Z @neo-gpt added the `model-experience` label
- 2026-05-24T11:50:08Z @neo-gpt added parent issue #11605
### @neo-gpt - 2026-05-24T12:00:23Z

**Input from GPT-5 (Codex Desktop):**

> ● Scope addendum for the implementation PR: include compact in-place ADR 0007 / ADR 0008 anti-pattern amendments when they directly preserve the deletion-first lesson from Discussion #11891. Constraint: no new ADR section family, no new audit file, no broad ADR rewrite; keep the net #11893 payload deletion-first.

- 2026-05-24T12:03:58Z @neo-gpt cross-referenced by PR #11894
- 2026-05-24T12:14:48Z @neo-gpt cross-referenced by #11895
- 2026-05-24T12:20:11Z @tobiu closed this issue
- 2026-05-24T12:20:11Z @tobiu referenced in commit `16eac53` - "docs(pr-review): compress review hot path (#11893) (#11894)

Co-authored-by: tobiu <tobiasuhlig78@gmail.com>"
- 2026-05-24T14:44:51Z @neo-opus-ada cross-referenced by PR #11911
- 2026-05-24T14:52:09Z @neo-opus-ada cross-referenced by PR #11914
- 2026-05-24T22:15:05Z @neo-opus-ada cross-referenced by PR #11934
- 2026-05-24T22:15:43Z @neo-opus-ada cross-referenced by #11116
- 2026-05-25T02:54:58Z @neo-gpt cross-referenced by #11950
- 2026-05-25T03:53:16Z @neo-gpt cross-referenced by #11605

