---
id: 10560
title: 'pr-review skill: router-level template pointers (Cycle 1 + Cycle N)'
state: CLOSED
labels:
  - documentation
  - enhancement
  - ai
assignees:
  - neo-opus-ada
createdAt: '2026-05-01T09:16:29Z'
updatedAt: '2026-05-01T09:33:35Z'
githubUrl: 'https://github.com/neomjs/neo/issues/10560'
author: neo-opus-ada
commentsCount: 0
parentIssue: 10537
subIssues: []
subIssuesCompleted: 0
subIssuesTotal: 0
blockedBy: []
blocking: []
closedAt: '2026-05-01T09:33:35Z'
---
# pr-review skill: router-level template pointers (Cycle 1 + Cycle N)

## Context

Sub of [#10537](https://github.com/neomjs/neo/issues/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 audit
- **`assets/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:

```markdown
**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

- [ ] **(AC1)** `pr-review/SKILL.md` adds two pointer lines mapping cycle-class to template asset (Cycle 1 → `pr-review-template.md`, Cycle N → `pr-review-followup-template.md`)
- [ ] **(AC2)** Progressive Disclosure preserved: SKILL.md remains the router; templates remain in `assets/`; guide remains in `references/`. No new top-level skill content.
- [ ] **(AC3)** No guide-body expansion: `pr-review-guide.md` unchanged by this sub.
- [ ] **(AC4)** Native parent-child link to #10537 via `update_issue_relationship`.
- [ ] **(AC5)** Existing template files (`pr-review-template.md`, `pr-review-followup-template.md`) unchanged.

## 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"

## Timeline

- 2026-05-01T09:16:30Z @neo-opus-ada added the `documentation` label
- 2026-05-01T09:16:30Z @neo-opus-ada added the `enhancement` label
- 2026-05-01T09:16:30Z @neo-opus-ada assigned to @neo-opus-ada
- 2026-05-01T09:16:30Z @neo-opus-ada added the `ai` label
- 2026-05-01T09:16:43Z @neo-opus-ada added parent issue #10537
- 2026-05-01T09:18:00Z @neo-opus-ada cross-referenced by PR #10561
- 2026-05-01T09:25:02Z @neo-opus-ada referenced in commit `ab98f32` - "docs(skill): tighten pr-review SKILL.md router prose per #10561 review (#10560)

Addresses Required Actions from @neo-gpt's PR #10561 review:
- RA2 (truth-in-code): drop unverified claim about emoji-headered sections
  being regex-matched. Per the guide, regex-matched extraction targets are
  graph tags ([KB_GAP], [TOOLING_GAP], [RETROSPECTIVE]), not section
  headers. The router should stay map-sized and substrate-verifiable.
- Tightens both Cycle 1 + Cycle N pointer prose to remain router-shaped
  rather than expanding into payload territory (template content lives in
  the asset files, not in the router).

Net: SKILL.md trimmed by 4 prose lines while preserving the load-bearing
trigger→template mapping.

Co-Authored-By: Claude Opus 4.7 (Claude Code) <claude@anthropic.com>"
- 2026-05-01T09:33:35Z @tobiu referenced in commit `b4c4076` - "docs(skill): add Cycle 1 / Cycle N template pointers to pr-review SKILL.md (#10560) (#10561)

* docs(skill): add Cycle 1 / Cycle N template pointers to pr-review SKILL.md (#10560)

Adds two trigger lines mapping review-cycle to template asset:
- Cycle 1 (new review)  → assets/pr-review-template.md (full sectioned)
- Cycle N (re-review)   → assets/pr-review-followup-template.md (delta-only)

The trigger→template mapping previously lived only in agent memory
(feedback_pr_review_template_discipline.md), not in the skill's
discoverable surface. Empirical anchor: PR #10558 cycles 2+3 reviewed
this morning re-ran the full template on follow-ups, generating noisier
graph data than the dedicated followup template's delta-only shape would.

Sub-issue of Epic #10537. Scope-guarded per the swarm coordination consensus
2026-05-01: this sub adds router-level pointers ONLY. No guide-body
modularization (that's #10537's primary scope across Subs 1-5). No template-
content changes. Total diff: SKILL.md +6 lines.

Co-Authored-By: Claude Opus 4.7 (Claude Code) <claude@anthropic.com>

* docs(skill): tighten pr-review SKILL.md router prose per #10561 review (#10560)

Addresses Required Actions from @neo-gpt's PR #10561 review:
- RA2 (truth-in-code): drop unverified claim about emoji-headered sections
  being regex-matched. Per the guide, regex-matched extraction targets are
  graph tags ([KB_GAP], [TOOLING_GAP], [RETROSPECTIVE]), not section
  headers. The router should stay map-sized and substrate-verifiable.
- Tightens both Cycle 1 + Cycle N pointer prose to remain router-shaped
  rather than expanding into payload territory (template content lives in
  the asset files, not in the router).

Net: SKILL.md trimmed by 4 prose lines while preserving the load-bearing
trigger→template mapping.

Co-Authored-By: Claude Opus 4.7 (Claude Code) <claude@anthropic.com>

---------

Co-authored-by: tobiu <tobiasuhlig78@gmail.com>
Co-authored-by: Claude Opus 4.7 (Claude Code) <claude@anthropic.com>"
- 2026-05-01T09:33:35Z @tobiu closed this issue

