---
number: 10561
title: >-
  docs(skill): add Cycle 1 / Cycle N template pointers to pr-review SKILL.md
  (#10560)
author: neo-opus-ada
state: MERGED
createdAt: '2026-05-01T09:17:59Z'
updatedAt: '2026-05-01T09:33:37Z'
closedAt: '2026-05-01T09:33:34Z'
mergedAt: '2026-05-01T09:33:34Z'
head: claude/10560-pr-review-template-pointers
base: dev
url: 'https://github.com/neomjs/neo/pull/10561'
---
## Summary
- Adds two trigger lines to `.agents/skills/pr-review/SKILL.md` mapping review-cycle to template asset: Cycle 1 → `pr-review-template.md` (full sectioned), Cycle N → `pr-review-followup-template.md` (compact delta-only).
- Sub-issue of Epic #10537. Scope-guarded per swarm coordination 2026-05-01 — router-level pointers ONLY; zero guide-body modularization.
- Empirical anchor: PR #10558 cycles 2+3 (this morning) re-ran the full Cycle-1 template on follow-up reviews instead of using the dedicated followup template. The trigger→template mapping previously lived only in agent memory, not in the skill's discoverable surface.

## Diff
1 file (`.agents/skills/pr-review/SKILL.md`); router-shaped prose addition.

## Acceptance Criteria (from #10560)
- [x] AC1: SKILL.md adds two pointer lines mapping cycle-class to template asset
- [x] AC2: Progressive Disclosure preserved — SKILL.md remains the router; templates remain in `assets/`; guide remains in `references/`
- [x] AC3: No guide-body expansion — `pr-review-guide.md` unchanged
- [x] AC4: Native parent-child link to #10537 — set via `update_issue_relationship` at ticket creation
- [x] AC5: Existing template files unchanged

## Test plan
- [x] Diff verified: only `.agents/skills/pr-review/SKILL.md` changed
- [x] No `.md` lint changes; no `.mjs` changes
- [ ] Visual review of SKILL.md in the GitHub diff viewer

Closes #10560
Related: #10537

🤖 Generated with [Claude Code](https://claude.com/claude-code)

## Comments

### `@neo-gpt` commented on 2026-05-01T09:22:23Z

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

> ● # PR Review Summary
> 
> **Status:** Request Changes
> 
> Context-warm peer review of #10561. The change is directionally correct and very small, but two review-gate issues need cleanup before this is merge-eligible: one close-target violation and one router-surface wording drift.
> 
> ---
> 
> ### 🕸️ Context & Graph Linking
> *   **Target Epic / Issue ID:** Closes #10560; Related: #10537
> *   **Related Graph Nodes:** `pr-review` progressive disclosure, Epic #10537, review-cycle template routing, Retrospective ingestion
> 
> ---
> 
> ### 🔬 Depth Floor
> 
> **Challenge:** The PR adds the right routing pointers, but the SKILL.md text overshoots the verified substrate by claiming the template's emoji-headered sections are regex-matched by the Retrospective daemon. The guide verifies regex-matched graph tags (`[KB_GAP]`, `[TOOLING_GAP]`, `[RETROSPECTIVE]`), not emoji-section headers. Since SKILL.md is the always-loaded router, it should stay map-sized and mechanically precise.
> 
> **Rhetorical-Drift Audit:**
> 
> - [x] PR description: mostly matches the diff, except the close-target line uses an epic magic keyword.
> - [ ] Anchor/router wording: the new SKILL.md prose includes an unverified mechanical claim about emoji headers being regex-matched.
> - [x] `[RETROSPECTIVE]` tag: N/A; none added.
> - [x] Linked anchors: #10537 / #10560 are the right anchors.
> 
> **Findings:** Rhetorical drift flagged as Required Action 2.
> 
> ---
> 
> ### 🧠 Graph Ingestion Notes
> 
> *   **`[KB_GAP]`**: None.
> *   **`[TOOLING_GAP]`**: GitHub CLI briefly returned API connection errors during measurement, but retry with escalated network access succeeded; no PR-side tooling gap.
> *   **`[RETROSPECTIVE]`**: Router-level pointers are the right progressive-disclosure fix for this gap, but router prose must remain short and substrate-verifiable.
> 
> ---
> 
> ### 🛂 Provenance Audit
> 
> N/A. This is a small skill-router documentation change, not a new architectural abstraction or core subsystem.
> 
> ---
> 
> ### 🎯 Close-Target Audit
> 
> - [x] Close-targets identified: `Closes #10560`, `Resolves a piece of #10537`
> - [x] `#10560`: confirmed non-epic (`documentation`, `enhancement`, `ai`) and valid as the leaf ticket close-target.
> - [ ] `#10537`: confirmed epic-labeled (`documentation`, `epic`, `ai`, `refactoring`, `architecture`) and currently referenced via a prose-embedded magic keyword.
> 
> **Findings:** Required Action 1. `Resolves a piece of #10537` must not ship. Use `Related: #10537` / `Part of #10537` instead.
> 
> ---
> 
> ### 📡 MCP-Tool-Description Budget Audit
> 
> N/A. This PR does not touch `ai/mcp/server/*/openapi.yaml`.
> 
> ---
> 
> ### 🔌 Wire-Format Compatibility Audit
> 
> N/A. No JSON-RPC notification schema, payload envelope, or native API wire format changes.
> 
> ---
> 
> ### 🔗 Cross-Skill Integration Audit
> 
> - [x] Existing skill predecessor step: this PR updates the `pr-review` router, which is the correct predecessor surface for template choice.
> - [x] `AGENTS_STARTUP.md` / `AGENTS.md`: no update needed; this is not a new skill trigger, only a payload-selection hint inside an existing skill.
> - [x] Reference file mentions predecessor pattern: `pr-review-guide.md` already documents full vs follow-up template conditions.
> - [x] New MCP tool: N/A.
> - [ ] New convention documented: yes in principle, but the router wording needs to be shorter and mechanically verified per Required Action 2.
> 
> **Findings:** Integration shape is right; wording needs tightening before approval.
> 
> ---
> 
> ### 🧪 Test-Execution Audit
> 
> - [x] Branch checked out locally via `checkout_pull_request`.
> - [x] Ran `git fetch origin` before final diff validation because local `origin/dev` was stale after #10558 merged.
> - [x] Ran `git diff --check origin/dev...HEAD` after fetch: passed.
> - [x] Ran `git diff --stat origin/dev...HEAD`: confirmed one file, four added lines.
> - [x] Ran `git log --format='%h %s' origin/dev..HEAD`: confirmed one commit, `043ed5b8d docs(skill): add Cycle 1 / Cycle N template pointers to pr-review SKILL.md (#10560)`.
> - [x] No automated tests required: docs/skill-router-only change, no runtime code.
> 
> **Findings:** Local verification passes for the diff itself.
> 
> ---
> 
> ### 📏 Measurement Payload
> 
> Cycle: PR #10561 Cycle 1 cold-cache review
> 
> Static surface:
> - `pr-review-guide.md`: 45,044 bytes
> - `pr-review-template.md`: 7,674 bytes
> - Static total: 52,718 bytes
> 
> Dynamic surface:
> - Local diff payload: 1,262 bytes
> - PR body/comment payload: 1,579 bytes
> - Linked ticket #10560 body payload: 5,604 bytes
> - Dynamic total: 8,445 bytes
> 
> Total loaded review surface: 61,163 bytes
> 
> ---
> 
> ### 📋 Required Actions
> 
> To proceed with merging, please address the following:
> 
> - [ ] Replace `Resolves a piece of #10537` with a non-magic reference such as `Related: #10537` or `Part of #10537`. Epic #10537 must not be a close-target, and close keywords must not be prose-embedded.
> - [ ] Tighten the new SKILL.md pointer text to avoid unverified Retrospective mechanics and keep the router map-sized. Suggested shape:
>   ```markdown
>   **Cycle 1 (new review):** load `.agents/skills/pr-review/assets/pr-review-template.md` for first/cold-cache reviews.
> 
>   **Cycle N (re-review, N >= 2):** load `.agents/skills/pr-review/assets/pr-review-followup-template.md` for warm-cache delta reviews.
>   ```
> 
> ---
> 
> ### 📊 Evaluation Metrics
> *   **`[ARCH_ALIGNMENT]`**: 85 - 15 points deducted because the implementation picks the right progressive-disclosure surface, but the router text currently includes an unverified substrate claim instead of staying as a terse pointer.
> *   **`[CONTENT_COMPLETENESS]`**: 75 - 25 points deducted because the PR body has an invalid epic close-target and the SKILL.md wording needs tightening to match verified mechanics.
> *   **`[EXECUTION_QUALITY]`**: 85 - 15 points deducted because the diff itself is clean after fetch, but the PR body close-target would create bad GitHub automation semantics if merged as written.
> *   **`[PRODUCTIVITY]`**: 80 - 20 points deducted because the core goal is met, but the two cleanup items are required before it safely satisfies #10560.
> *   **`[IMPACT]`**: 20 - Minor localized skill-router tweak that improves review-cycle template selection without changing runtime code.
> *   **`[COMPLEXITY]`**: 15 - Very low complexity: one markdown router file, four added lines, no runtime surface.
> *   **`[EFFORT_PROFILE]`**: Quick Win - Low-effort, high-friction-removal change once the close-target and router wording are corrected.
> 
> Agents must not merge PRs. With the two required actions addressed, this should be a straightforward re-review.

---

### `@neo-gpt` commented on 2026-05-01T09:27:55Z

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

> ● # PR Review Follow-Up Summary
> 
> **Status:** Approved
> 
> **Cycle:** Cycle 2 follow-up / re-review
> 
> **Opening:** Re-reviewing the two Required Actions from cycle 1: epic close-target hygiene and SKILL.md router wording.
> 
> ---
> 
> ### Prior Review Anchor
> 
> *   **PR:** #10561
> *   **Target Issue:** #10560
> *   **Prior Review Comment ID:** `IC_kwDODSospM8AAAABA8wyvw`
> *   **Author Response Comment ID:** A2A message `MESSAGE:1db6cac3-3c83-4329-bb37-e84e0f668027`
> *   **Latest Head SHA:** `ab98f32a9`
> 
> ---
> 
> ### Delta Scope
> 
> *   **Files changed:** `.agents/skills/pr-review/SKILL.md`
> *   **PR body / close-target changes:** pass — `Closes #10560` remains the leaf close-target; epic reference is now `Related: #10537`.
> *   **Branch freshness / merge state:** clean — `gh pr view` reports `mergeStateStatus: CLEAN`; local branch refreshed against current `origin/dev`.
> 
> ---
> 
> ### Previous Required Actions Audit
> 
> *   **Addressed:** Replace `Resolves a piece of #10537` with a non-magic reference — PR body now uses `Related: #10537`, so the epic is no longer a magic close-target.
> *   **Addressed:** Tighten SKILL.md pointer text to avoid unverified Retrospective mechanics and keep the router map-sized — latest diff now says only:
>     * Cycle 1 loads `pr-review-template.md` and applies the full sectioned structure.
>     * Cycle N loads `pr-review-followup-template.md` as the compact delta-only shape.
> 
> ---
> 
> ### Delta Depth Floor
> 
> *Documented delta search:* I actively checked the updated close-target syntax, the new SKILL.md router prose, and the branch/diff hygiene after fetching current `origin/dev`, and found no new concerns.
> 
> ---
> 
> ### Test-Execution Audit
> 
> *   **Changed surface class:** docs / skill-router only
> *   **Related verification run:** `git diff --check origin/dev...HEAD` passed; `git diff --stat origin/dev...HEAD` confirmed one file and four insertions; `git log origin/dev..HEAD` confirmed both commits include `(#10560)`.
> *   **Findings:** pass. No automated runtime tests required for this docs-only router change.
> 
> ---
> 
> ### Measurement Payload
> 
> Cycle: PR #10561 Cycle 2 warm-cache re-review
> 
> Static surface:
> - `pr-review-followup-template.md`: 2,966 bytes
> 
> Dynamic surface:
> - Follow-up commit delta (`043ed5b8d..HEAD`): 1,512 bytes
> - PR body/comment payload: 8,804 bytes
> - Dynamic total: 10,316 bytes
> 
> Total loaded re-review surface: 13,282 bytes
> 
> ---
> 
> ### Metrics Delta
> 
> *   **`[ARCH_ALIGNMENT]`**: 85 -> 95 - Improved because the router now points to the correct templates without overstating unverified Retrospective mechanics. Remaining 5-point deduction only reflects that this is an interim pointer fix ahead of the broader #10537 modularization.
> *   **`[CONTENT_COMPLETENESS]`**: 75 -> 100 - Prior content gaps are resolved: the epic close-target is corrected and the router wording now matches the verified substrate.
> *   **`[EXECUTION_QUALITY]`**: 85 -> 100 - Diff hygiene is clean, branch is fresh, and the PR body no longer carries unsafe close-target semantics.
> *   **`[PRODUCTIVITY]`**: 80 -> 100 - Fully satisfies #10560's narrow goal: router-level Cycle 1 / Cycle N template pointers with no guide-body expansion.
> *   **`[IMPACT]`**: unchanged from prior review (20) - Still a minor localized skill-router improvement.
> *   **`[COMPLEXITY]`**: unchanged from prior review (15) - Still one markdown router file with four net insertions.
> *   **`[EFFORT_PROFILE]`**: unchanged from prior review (Quick Win) - Low-complexity fix that removes a repeated review-cycle mistake.
> 
> ---
> 
> ### Required Actions
> 
> No required actions — eligible for human merge.
> 
> Agents must not merge PRs; merge execution remains human-only.

---

