Context
Sub of #10537. Surfaced 2026-05-01 by @tobiu after observing this morning's PR #10558 cycle 2+3 review thread: I re-ran the full pr-review-template.md for every cycle instead of using the dedicated pr-review-followup-template.md for cycles 2+. The followup template's compact shape (Prior Review Anchor → Delta Scope → Previous Required Actions Audit → Delta Depth Floor → Metrics Delta → A2A Hand-off) is the right Cycle N discipline; my over-rotation on the full template generated noisier graph data and wasted review budget.
@tobiu's framing: "i think the pr-review skill should include it. but the skill evolved into a book (focus window problems). we have a new epic to address this."
The trigger→template mapping currently lives only in agent memory (feedback_pr_review_template_discipline.md), not in the skill's own discoverable surface. Future agents reach for the wrong template by default until they bump into the same lesson empirically.
The Problem
pr-review/SKILL.md (router, 8 lines) directs agents to references/pr-review-guide.md only. Neither template is mentioned at the router level. The two templates serve different consumers:
assets/pr-review-template.md (160 lines, cold-cache loaded) — Cycle 1 reviews, full sectioned auditassets/pr-review-followup-template.md (94 lines, warm-cache loaded) — Cycle N reviews, delta-only
Without router-level pointers, the trigger→template mapping is implicit. Empirical anchor: PR #10558 cycles 2+3 were posted with the wrong (full) template before @tobiu surfaced the gap.
The Architectural Reality
pr-review/SKILL.md (8 lines) is the right substrate for the router-level pointers — it's already minimal and fits the Progressive Disclosure pattern (per learn/agentos/ProgressiveDisclosureSkills.md + .agents/skills/create-skill/). Adding 2 trigger lines preserves the router's compactness without introducing guide-body bloat.
Files in scope:
.agents/skills/pr-review/SKILL.md — add Cycle 1 / Cycle N trigger lines pointing at the two existing template assets
Out of scope: any changes to the templates themselves; any guide modularization; any new conventions or sections in pr-review-guide.md. This sub explicitly does NOT solve the larger condition-gated audit extraction work — that's #10537's primary scope across Subs 1-5.
The Fix
Add two trigger lines to pr-review/SKILL.md that map review-cycle to template:
**For new (Cycle 1) reviews:** load `.agents/skills/pr-review/assets/pr-review-template.md` and apply its full sectioned structure.
**For follow-up (Cycle N, N≥2) reviews:** load `.agents/skills/pr-review/assets/pr-review-followup-template.md` — compact delta-only shape (Prior Review Anchor → Delta Scope → Previous Required Actions Audit → Delta Depth Floor → Metrics Delta → A2A Hand-off).
Total expected diff: ~5 lines added to pr-review/SKILL.md. No other files modified.
Acceptance Criteria
Out of Scope
- Any modification to template content (the template assets themselves)
- Any guide modularization (Subs 1-5 of #10537 own that scope)
- Adding new sections, audits, or conventions to
pr-review-guide.md
- Updating
pr-review-followup-template.md's body (separate concern if needed)
- Updating downstream skills that mention pr-review (cross-skill integration is Sub-5 of #10537)
Avoided Traps
- Trap: bloat the SKILL.md router with guide-content. Rejected — SKILL.md should remain minimal per Progressive Disclosure. The fix is two pointer lines, not a re-summarization of the templates' bodies.
- Trap: solve guide modularization in this sub by stealth. Per @neo-gpt's explicit scope guard: this sub does NOT touch
pr-review-guide.md body. Guide-body work belongs to #10537's Subs 1-5.
- Trap: file as a comment on #10537 instead of a native sub. Rejected — native parent-child linkage feeds the Native Edge Graph; comments don't.
- Trap: defer to Sub-5 (cross-skill integration). Rejected per swarm coordination 2026-05-01 — Sub-5 is the LAST sub. The router-level fix is map-sized + unblocks future agents from re-running today's mistake; deferring it to Sub-5 leaves the gap open for the entire pilot+survey duration.
Related
- Parent epic: #10537 (
pr-review-guide.md modularization)
- Sibling sub-issue (already filed): #10540 (Sub-1: Loaded-surface measurement methodology + baseline)
- Originating discussion: #10429 (Map vs World Atlas + llms.txt)
- Empirical anchor (this morning's reviews): PR #10558 cycles 1, 2, 3 — agent re-ran full template every cycle
- Memory anchor (the discipline that exists today but not in the skill):
feedback_pr_review_template_discipline.md
Origin Session ID: 1f30c9d8-4a36-4be0-98a5-bd5b89289227
Retrieval Hint: "pr-review SKILL.md router template pointers Cycle 1 followup template"
Context
Sub of #10537. Surfaced 2026-05-01 by @tobiu after observing this morning's PR #10558 cycle 2+3 review thread: I re-ran the full
pr-review-template.mdfor every cycle instead of using the dedicatedpr-review-followup-template.mdfor cycles 2+. The followup template's compact shape (Prior Review Anchor → Delta Scope → Previous Required Actions Audit → Delta Depth Floor → Metrics Delta → A2A Hand-off) is the right Cycle N discipline; my over-rotation on the full template generated noisier graph data and wasted review budget.@tobiu's framing: "i think the pr-review skill should include it. but the skill evolved into a book (focus window problems). we have a new epic to address this."
The trigger→template mapping currently lives only in agent memory (
feedback_pr_review_template_discipline.md), not in the skill's own discoverable surface. Future agents reach for the wrong template by default until they bump into the same lesson empirically.The Problem
pr-review/SKILL.md(router, 8 lines) directs agents toreferences/pr-review-guide.mdonly. Neither template is mentioned at the router level. The two templates serve different consumers:assets/pr-review-template.md(160 lines, cold-cache loaded) — Cycle 1 reviews, full sectioned auditassets/pr-review-followup-template.md(94 lines, warm-cache loaded) — Cycle N reviews, delta-onlyWithout router-level pointers, the trigger→template mapping is implicit. Empirical anchor: PR #10558 cycles 2+3 were posted with the wrong (full) template before @tobiu surfaced the gap.
The Architectural Reality
pr-review/SKILL.md(8 lines) is the right substrate for the router-level pointers — it's already minimal and fits the Progressive Disclosure pattern (perlearn/agentos/ProgressiveDisclosureSkills.md+.agents/skills/create-skill/). Adding 2 trigger lines preserves the router's compactness without introducing guide-body bloat.Files in scope:
.agents/skills/pr-review/SKILL.md— add Cycle 1 / Cycle N trigger lines pointing at the two existing template assetsOut of scope: any changes to the templates themselves; any guide modularization; any new conventions or sections in
pr-review-guide.md. This sub explicitly does NOT solve the larger condition-gated audit extraction work — that's #10537's primary scope across Subs 1-5.The Fix
Add two trigger lines to
pr-review/SKILL.mdthat map review-cycle to template:**For new (Cycle 1) reviews:** load `.agents/skills/pr-review/assets/pr-review-template.md` and apply its full sectioned structure. **For follow-up (Cycle N, N≥2) reviews:** load `.agents/skills/pr-review/assets/pr-review-followup-template.md` — compact delta-only shape (Prior Review Anchor → Delta Scope → Previous Required Actions Audit → Delta Depth Floor → Metrics Delta → A2A Hand-off).Total expected diff: ~5 lines added to
pr-review/SKILL.md. No other files modified.Acceptance Criteria
pr-review/SKILL.mdadds two pointer lines mapping cycle-class to template asset (Cycle 1 →pr-review-template.md, Cycle N →pr-review-followup-template.md)assets/; guide remains inreferences/. No new top-level skill content.pr-review-guide.mdunchanged by this sub.update_issue_relationship.pr-review-template.md,pr-review-followup-template.md) unchanged.Out of Scope
pr-review-guide.mdpr-review-followup-template.md's body (separate concern if needed)Avoided Traps
pr-review-guide.mdbody. Guide-body work belongs to #10537's Subs 1-5.Related
pr-review-guide.mdmodularization)feedback_pr_review_template_discipline.mdOrigin Session ID: 1f30c9d8-4a36-4be0-98a5-bd5b89289227 Retrieval Hint: "pr-review SKILL.md router template pointers Cycle 1 followup template"