@silverassist/agents-toolkit 2.5.0 → 2.6.0

package/templates/shared/prompts/resolve-github-reviews.prompt.md

@@ -0,0 +1,323 @@
+---
+agent: agent
+description: Fetch, respond to, resolve, and close GitHub PR review comments (Copilot or human)
+---
+
+# Resolve GitHub PR Reviews
+
+Clear a pull request's review threads end-to-end: **fetch → address → reply → resolve → verify `0` unresolved**.
+Works for both **Copilot** and **human** reviews.
+
+## Prerequisites
+- `gh` CLI authenticated (`gh auth status`) with `repo` scope — the GraphQL thread-resolve mutation needs it
+- Reference: `.github/prompts/_partials/github-integration.md`
+- Reference: `.github/prompts/_partials/git-operations.md`
+
+## Inputs
+- `{pr-number}` *(optional)* — target PR. Defaults to the PR for the current branch.
+- `{repo}` *(optional)* — `owner/repo` for cross-repo review (adds `--repo` / fills the GraphQL vars).
+
+> **Key fact:** the REST API **cannot** mark a review thread resolved — only the GraphQL
+> `resolveReviewThread` mutation can. **GraphQL** both *lists* threads (`reviewThreads`, Step 2) and
+> *resolves* them (Step 5.4); **REST** is used only to post *replies* (Steps 5.2–5.3).
+
+## Steps
+
+### 1. Locate the PR
+
+> `{repo}` and `{pr-number}` are prompt-template placeholders substituted by the prompt engine
+> **before the script runs**. When the user does not supply them, they stay as the literal strings
+> `{repo}` / `{pr-number}`, so the guards below compare against those literals to detect the
+> "not provided" case. Capture each into a shell variable once and check it with `-n` plus the
+> literal-placeholder guard.
+
+```bash
+# Copy the (possibly substituted) template values into shell vars.
+REPO_INPUT="{repo}"
+PR_INPUT="{pr-number}"
+
+# Resolve owner/repo — use REPO_INPUT for cross-repo review, else fall back to the current repo.
+if [ -n "$REPO_INPUT" ] && [ "$REPO_INPUT" != "{repo}" ]; then
+  REPO_SLUG="$REPO_INPUT"                                        # cross-repo, e.g. owner/name
+else
+  REPO_SLUG=$(gh repo view --json nameWithOwner -q .nameWithOwner)
+fi
+OWNER=${REPO_SLUG%/*}
+REPO=${REPO_SLUG#*/}
+
+# `gh` global flag reused by every later `gh pr` command so cross-repo works transparently.
+GH_REPO_FLAG=(--repo "$REPO_SLUG")
+
+# Current branch's PR (or pass an explicit number as {pr-number}).
+if [ -n "$PR_INPUT" ] && [ "$PR_INPUT" != "{pr-number}" ]; then
+  PR="$PR_INPUT"
+else
+  PR=$(gh pr view "${GH_REPO_FLAG[@]}" --json number -q .number)
+fi
+
+echo "Reviewing $OWNER/$REPO PR #$PR"
+gh pr view "${GH_REPO_FLAG[@]}" "$PR" --json title,state,reviewDecision,url | cat
+
+# Make the fixes in Steps 3–4 land on the PR under review — not whatever branch happens
+# to be checked out. Check out the PR's head branch before editing anything:
+gh pr checkout "$PR" "${GH_REPO_FLAG[@]}"
+echo "On branch: $(git branch --show-current)"
+# Cross-repo ({repo} set): run this prompt from a local clone of that repo — editing,
+# committing, and pushing need the target repo's working tree, not just API access.
+```
+
+### 2. Fetch unresolved review threads (paginated)
+
+Walk the GraphQL `reviewThreads` connection with `pageInfo { endCursor hasNextPage }` — a PR
+can have more than 100 threads, so a single `first:100` page is not enough. Capture each
+thread's `id` (needed to resolve it) and its first comment's `databaseId`, `path`, and `line`
+(needed to reply).
+
+```bash
+> /tmp/review-threads.jsonl
+CURSOR=null
+while : ; do
+  PAGE=$(gh api graphql -F owner="$OWNER" -F repo="$REPO" -F pr="$PR" -F after="$CURSOR" -f query='
+    query($owner:String!, $repo:String!, $pr:Int!, $after:String) {
+      repository(owner:$owner, name:$repo) {
+        pullRequest(number:$pr) {
+          reviewThreads(first:100, after:$after) {
+            pageInfo { endCursor hasNextPage }
+            nodes {
+              id
+              isResolved
+              isOutdated
+              path
+              line
+              comments(first:1) { nodes { databaseId body author { login } } }
+            }
+          }
+        }
+      }
+    }')
+  # Fail fast: an API/auth/network error must not be mistaken for "no threads".
+  if ! echo "$PAGE" | jq -e '.data.repository.pullRequest.reviewThreads' >/dev/null 2>&1; then
+    echo "ERROR: GraphQL request failed or returned an unexpected shape:" >&2
+    echo "$PAGE" >&2
+    exit 1
+  fi
+  echo "$PAGE" | jq -c '.data.repository.pullRequest.reviewThreads.nodes[]' >> /tmp/review-threads.jsonl
+  HAS_NEXT=$(echo "$PAGE" | jq -r '.data.repository.pullRequest.reviewThreads.pageInfo.hasNextPage')
+  CURSOR=$(echo "$PAGE" | jq -r '.data.repository.pullRequest.reviewThreads.pageInfo.endCursor')
+  [ "$HAS_NEXT" = "true" ] || break
+done
+
+# Unresolved threads only, one compact record per line.
+jq -r '
+  select(.isResolved == false)
+  | {
+      threadId: .id,
+      commentId: .comments.nodes[0].databaseId,
+      path: .path,
+      line: .line,
+      outdated: .isOutdated,
+      author: .comments.nodes[0].author.login,
+      body: (.comments.nodes[0].body | gsub("\n"; " ") | .[0:120])
+    }' /tmp/review-threads.jsonl
+
+# Count what is left to do (drives the final assertion in Step 6).
+UNRESOLVED=$(jq -s '[.[] | select(.isResolved == false)] | length' /tmp/review-threads.jsonl)
+echo "Unresolved threads: $UNRESOLVED"
+```
+
+### 3. Apply each fix and run checks
+
+For every unresolved thread from Step 2:
+
+1. **Apply the fix** in code (or decide it is a false positive — record the reasoning for Step 4).
+2. **Run the project's checks** so the reply reflects a verified change:
+
+   ```bash
+   npm run lint --if-present
+   npm run type-check --if-present
+   if [ -f tsconfig.json ]; then npx tsc --noEmit; fi
+   npm run test --if-present
+   ```
+
+**Then — once per batch, not per thread** — after **all** the per-thread fixes above are applied,
+run a single **whole-repo** consistency pass (the *core review*) before committing the batch. Use
+the **`core-review` skill** (`.agents/skills/core-review/SKILL.md`) as a dedicated read-only pass
+(inline on Copilot/Codex; optionally a subagent on Claude Code). A fix often leaves or introduces
+an adjacent issue (a now-stale doc line, a broken link, a table missing the new asset) that would
+trigger yet another Copilot round. Apply everything the pass flags, re-run the checks above, and
+only then proceed to Step 4. Running this once over the completed batch — rather than per thread —
+keeps the (whole-repo) review cost bounded.
+
+### 4. Commit and push fixes (before replying)
+
+Reply bodies reference the fixing commit SHA, so **commit and push first** — otherwise the SHA
+does not exist on the remote branch yet and the reply link is dead.
+
+> Run the whole-repo **core review** from Step 3 *before* this commit — pushing an adjacent,
+> unfixed issue starts a fresh Copilot round and defeats the purpose of resolving in batches.
+
+```bash
+# Stage only the files you changed for these fixes. Avoid `git add -A` — Step 1 does not
+# require a clean worktree, so it could sweep in unrelated pre-existing changes.
+git add <files you edited>
+if git diff --cached --quiet; then
+  # Nothing staged — every finding was a false positive. A bare `git commit` would fail,
+  # and `$SHA` would wrongly point at an unrelated existing HEAD. Leave `$SHA` empty and
+  # reply to those threads in Step 5 with reasoning only (never "Fixed in <sha>").
+  SHA=""
+  echo "No staged changes — skipping the fix commit; Step 5 replies with rationale only."
+else
+  git commit -m "fix: Address PR #$PR review comments"
+  if ! git push; then
+    echo "ERROR: git push failed. Do not proceed to Step 5 — \$SHA is not on the remote yet." >&2
+    echo "Diagnose the failure before retrying:" >&2
+    echo "  - Non-fast-forward: run 'git pull --rebase' then 'git push' again." >&2
+    echo "  - Branch protection / required status checks: fix locally and re-run this step," >&2
+    echo "    or contact a repo admin if the branch is protected against your role." >&2
+    echo "  - Auth: run 'gh auth status' and re-authenticate with 'repo' scope if needed." >&2
+    exit 1
+  fi
+  SHA=$(git rev-parse HEAD)
+  echo "Fix commit: $SHA"
+fi
+```
+
+If a single commit already covers all fixes, capture that SHA and skip the commit step; the point
+is that `$SHA` must be **pushed** before Step 5 references it. **Do not advance to Step 5 unless
+the push succeeded** — every reply body links to `$SHA` on the remote.
+
+### 5. Reply and resolve each thread
+
+For each unresolved thread from Step 2, run the following sub-procedure **in order**. `$COMMENT_ID`
+is the first comment's `databaseId`; `$THREAD_ID` is the thread `id`. Steps 5.1–5.3 pick exactly
+one reply path; Step 5.4 **always** runs afterward regardless of which reply path was taken.
+
+#### 5.1 — If `$COMMENT_ID` is null: PR-level acknowledgement, then go to 5.4
+
+Copilot low-confidence / suppressed notes have no inline comment id (`databaseId` is `null`) and
+cannot be replied to per-thread. Acknowledge them once with a PR-level comment, then skip to 5.4
+to resolve the thread:
+
+```bash
+if [ -z "$COMMENT_ID" ] || [ "$COMMENT_ID" = "null" ]; then
+  gh pr comment "${GH_REPO_FLAG[@]}" "$PR" --body "Addressed Copilot's low-confidence suggestions: <summary>."
+  # Skip 5.2 and 5.3; proceed directly to 5.4 for this thread.
+fi
+```
+
+#### 5.2 — Otherwise: attempt the direct replies endpoint
+
+If the finding was a **false positive** (no fix commit — `$SHA` is empty), reply with your
+reasoning instead of a SHA, e.g. `-f body="Not applicable — <why>."`. Otherwise reference the
+fix commit:
+
+```bash
+gh api "repos/$OWNER/$REPO/pulls/$PR/comments/$COMMENT_ID/replies" \
+  -f body="Fixed in $SHA: <what changed>. Thanks!"
+```
+
+#### 5.3 — Only if 5.2 returned HTTP 404: fall back to `in_reply_to`
+
+Some threads reject the direct replies endpoint (404). Only in that case, post a new review
+comment linked to the original via `in_reply_to`:
+
+```bash
+gh api "repos/$OWNER/$REPO/pulls/$PR/comments" \
+  -f body="Fixed in $SHA: <what changed>." \
+  -F in_reply_to="$COMMENT_ID"
+```
+
+Do **not** run 5.3 unless 5.2 failed with 404; running both duplicates the reply.
+
+#### 5.4 — Resolve the thread via the GraphQL mutation (REST cannot)
+
+If you address threads one at a time, resolve each one here after replying (from 5.1, 5.2, or 5.3).
+Prefer to resolve them all at once? Skip this per-thread call and use the batch loop in 5.5 instead —
+use **either** 5.4 **or** 5.5, never both, or every mutation runs twice.
+
+```bash
+gh api graphql -f id="$THREAD_ID" -f query='
+  mutation($id:ID!) {
+    resolveReviewThread(input:{threadId:$id}) {
+      thread { isResolved }
+    }
+  }'
+```
+
+#### 5.5 — Alternative: batch-resolve every addressed thread at once
+
+Instead of the per-thread call in 5.4, resolve everything in one loop once all replies are posted
+(use **either** 5.4 per thread **or** this batch loop, not both). Check the mutation response inside
+the loop — a missing `repo` scope on the token succeeds at listing but fails at resolving, and
+without this check the failure is silent and Step 6 reports leftover threads with no explanation.
+
+```bash
+jq -r 'select(.isResolved == false) | .id' /tmp/review-threads.jsonl | while read -r THREAD_ID; do
+  RESULT=$(gh api graphql -f id="$THREAD_ID" -f query='mutation($id:ID!){ resolveReviewThread(input:{threadId:$id}){ thread { isResolved } } }')
+  if [ "$(echo "$RESULT" | jq -r '.data.resolveReviewThread.thread.isResolved')" != "true" ]; then
+    echo "ERROR: failed to resolve $THREAD_ID: $RESULT" >&2
+    exit 1
+  fi
+done
+```
+
+> **`isOutdated` threads** — a thread whose code moved is marked `isOutdated` but stays
+> **unresolved**. Resolve it the same way once the concern is handled; it will not clear itself.
+
+### 6. Close the loop
+
+Re-query with the same pagination pattern and assert **zero** unresolved threads. Exit non-zero
+when threads remain so this step can gate CI or a script.
+
+```bash
+> /tmp/review-threads-remaining.jsonl
+CURSOR=null
+while : ; do
+  PAGE=$(gh api graphql -F owner="$OWNER" -F repo="$REPO" -F pr="$PR" -F after="$CURSOR" -f query='
+    query($owner:String!, $repo:String!, $pr:Int!, $after:String) {
+      repository(owner:$owner, name:$repo) {
+        pullRequest(number:$pr) {
+          reviewThreads(first:100, after:$after) {
+            pageInfo { endCursor hasNextPage }
+            nodes { isResolved }
+          }
+        }
+      }
+    }')
+  # Fail fast: an API/auth/network error must not be mistaken for "0 remaining".
+  if ! echo "$PAGE" | jq -e '.data.repository.pullRequest.reviewThreads' >/dev/null 2>&1; then
+    echo "ERROR: GraphQL request failed or returned an unexpected shape:" >&2
+    echo "$PAGE" >&2
+    exit 1
+  fi
+  echo "$PAGE" | jq -c '.data.repository.pullRequest.reviewThreads.nodes[]' >> /tmp/review-threads-remaining.jsonl
+  HAS_NEXT=$(echo "$PAGE" | jq -r '.data.repository.pullRequest.reviewThreads.pageInfo.hasNextPage')
+  CURSOR=$(echo "$PAGE" | jq -r '.data.repository.pullRequest.reviewThreads.pageInfo.endCursor')
+  [ "$HAS_NEXT" = "true" ] || break
+done
+
+REMAINING=$(jq -s '[.[] | select(.isResolved == false)] | length' /tmp/review-threads-remaining.jsonl)
+echo "Remaining unresolved threads: $REMAINING"
+if [ "$REMAINING" -eq 0 ]; then
+  echo "✅ All review threads resolved"
+else
+  echo "❌ $REMAINING thread(s) still open"
+  exit 1
+fi
+```
+
+Then summarize:
+- Threads addressed and how (fix commit SHA per finding).
+- Any threads intentionally left with a reply explaining a false positive (resolve those too).
+- Commit(s) pushed and the resulting `reviewDecision`.
+
+## Notes & edge cases
+
+- **Per-commit review rounds** — Copilot re-reviews after each push. New threads can appear;
+  re-run Steps 2–6 until Step 6 reports `0`. Request a fresh review if needed:
+  `gh pr comment "${GH_REPO_FLAG[@]}" "$PR" --body "@copilot review"` (or re-request a human reviewer).
+- **Review submissions vs comments vs threads** — a *review* (`gh pr review`) is the top-level
+  approval/verdict; *review comments* are inline; a *review thread* groups an inline comment with
+  its replies and carries the `isResolved` flag. Only threads are resolvable.
+- **Auth** — resolving needs the GraphQL API with `repo` scope; a token missing it fails the
+  mutation with a permissions error even though listing works.

package/templates/shared/skills/README.md

@@ -19,10 +19,16 @@ skills directory contains symlinks to it (single source of truth):
 │   └── SKILL.md
 ├── component-architecture/
 │   └── SKILL.md
+├── core-review/
+│   └── SKILL.md
 ├── create-component/
 │   └── SKILL.md
 ├── domain-driven-design/
 │   └── SKILL.md
+├── github-review-management/
+│   └── SKILL.md
+├── nextjs-caching/
+│   └── SKILL.md
 ├── plugin-creation/
 │   └── SKILL.md
 ├── quality-checks/
@@ -31,7 +37,9 @@ skills directory contains symlinks to it (single source of truth):
 │   └── SKILL.md
 ├── testing/
 │   └── SKILL.md
-└── testing-patterns/
+├── testing-patterns/
+│   └── SKILL.md
+└── tsdoc-standards/
     └── SKILL.md
 
 .github/skills/   → symlinks to ../../.agents/skills/*   (Copilot, Codex)
@@ -54,9 +62,19 @@ description: When to use this skill. Agents use this to decide relevance.
 
 | Skill | Description |
 |-------|-------------|
+| `ai-seo-optimization` | Optimize sites for Google generative AI features, agent-friendly HTML, E-E-A-T signals |
 | `component-architecture` | React component patterns, folder structure, naming conventions |
+| `core-review` | Whole-repo pre-review (before a PR / before pushing review fixes) run as a read-only pass — inline on Copilot/Codex, optionally a subagent on Claude Code — to preempt Copilot iterations |
+| `create-component` | Scaffold a new component in a Silver Assist WordPress plugin (LoadableInterface pattern) |
 | `domain-driven-design` | DDD principles, domain organization, barrel exports |
+| `github-review-management` | Fetch, reply to, resolve & close GitHub PR review threads via `gh` CLI + GraphQL |
+| `nextjs-caching` | Next.js caching strategy: read-vs-mutation fetch, ISR tiers, CDN invalidation, dynamic-render diagnosis |
+| `plugin-creation` | Scaffold a new Silver Assist WordPress plugin from scratch (PSR-4, LoadableInterface, CI/CD) |
+| `quality-checks` | Run PHPCS, PHPStan (level 8), and PHPUnit for Silver Assist WordPress plugins |
+| `release-management` | Create and manage releases for Silver Assist WordPress plugins (unified build + GH Actions) |
+| `testing` | Write and run PHPUnit tests for Silver Assist WordPress plugins (WP_UnitTestCase) |
 | `testing-patterns` | Jest + RTL patterns for Next.js 15 and Server Actions |
+| `tsdoc-standards` | Write & enforce TSDoc (not JSDoc): allowed tags, forbidden JSDoc patterns, templates |
 
 ## Usage
 
@@ -71,5 +89,5 @@ Skills are automatically picked up by agents when relevant to your question. You
 1. Create a folder: `.agents/skills/your-skill-name/` (canonical store)
 2. Create `SKILL.md` with frontmatter
 3. Run `npx @silverassist/agents-toolkit install --skills-only` to symlink it into `.github/skills/` and `.claude/skills/`
-3. Document patterns, examples, and conventions
-4. Include ✅ CORRECT and ❌ INCORRECT examples
+4. Document patterns, examples, and conventions
+5. Include ✅ CORRECT and ❌ INCORRECT examples

package/templates/shared/skills/ai-seo-optimization/SKILL.md

@@ -7,8 +7,11 @@ description: Optimize websites for Google's generative AI features and browser a
 
 Comprehensive guide for optimizing Next.js sites for Google's generative AI features (AI Overviews, AI Mode) and emerging browser agent interactions.
 
-> **Source**: [Google AI Optimization Guide](https://developers.google.com/search/docs/fundamentals/ai-optimization-guide) (May 2026)
-> **Companion**: [Build Agent-Friendly Websites](https://web.dev/articles/ai-agent-site-ux) (April 2026)
+> **Framework note**: Although examples use Next.js conventions (e.g., `generateMetadata`), all checklist items apply to any web framework. For non-Next.js sites, substitute framework-equivalent SSR and metadata APIs.
+
+> **Source**: [Google AI Optimization Guide](https://developers.google.com/search/docs/fundamentals/ai-optimization-guide)
+> **Companion**: [Build Agent-Friendly Websites](https://web.dev/articles/ai-agent-site-ux)
+> **Verify current guidance**: These references reflect guidance as of the skill's authoring date. Always verify current Google documentation before advising clients.
 
 ---
 
@@ -321,6 +324,12 @@ These are explicitly confirmed as **unnecessary or harmful** by Google:
 
 ## 9. Audit Workflow
 
+Before beginning the audit, confirm you have access to: (1) the site URL or representative page HTML, (2) Google Search Console data if available, and (3) the page types to audit (home, landing, blog, etc.).
+
+If no site URL, HTML, or page content is provided, respond: "To perform this audit, please share the site URL, representative page HTML, or specific components you want evaluated."
+
+Representative HTML alone cannot support checks that need live signals — **index status, live crawl/HTTP accessibility, Core Web Vitals field data, and Search Console signals**. When the corresponding source is not provided (no live URL, no CrUX/PageSpeed access, no Search Console), report those items as **"Not verifiable — requires \<live URL | CrUX/PSI | Search Console\>"** rather than inferring a pass/fail from static markup.
+
 When asked to audit a site for AI optimization, follow this order:
 
 1. **Technical baseline** — Verify indexing, SSR, canonical tags, Core Web Vitals

package/templates/shared/skills/core-review/SKILL.md

@@ -0,0 +1,251 @@
+---
+name: core-review
+description: Run a thorough, whole-repo consistency review before opening a PR or before pushing fixes in response to a reviewer — as a dedicated read-only pass (inline on Copilot/Codex; optionally a subagent on Claude Code) — to preempt Copilot/reviewer iterations. Use when about to push a branch for review or to push a batch of review fixes.
+---
+
+# Silver Assist — Core Review (Pre-Review)
+
+A **pre-emptive, whole-repo consistency review** that runs *before* a reviewer (Copilot or a
+human) ever sees the branch. It catches the classes of issues that trigger multi-round review
+loops — doc↔code drift, invalid code examples, broken links, stale indexes — so they are fixed
+in the first push instead of round 5.
+
+This skill is the reviewer's knowledge; the **action** (run the review, apply the findings) is
+invoked as a step from `create-github-pr`, `resolve-github-reviews`, and `finalize-github-pr`.
+
+## When to Use
+
+Run this review at **two integration points**:
+
+1. **Pre-PR** — after the code is written and local checks pass, **before** `create-github-pr`
+   pushes the branch and opens the PR.
+2. **Pre-push during review resolution** — inside `resolve-github-reviews` / `finalize-github-pr`,
+   **before** pushing each batch of fixes, so a fix does not leave (or introduce) an adjacent
+   issue that triggers yet another reviewer round.
+
+## Why whole-repo, not just the diff
+
+Copilot re-reviews **entire files**, not just your hunks — and each push opens a fresh round.
+In recent work the rounds went `18 → 2 → 3 → 1 → 9 → 3 → 1 → 1 …`: every push surfaced new,
+mostly *valid* findings in code the diff only brushed against (a doc line that no longer matches
+the changed code, a table missing the asset you just added, a link that now resolves elsewhere).
+A review scoped to the whole repo — or at least every file that imports, re-exports, documents,
+or enumerates the changed symbol or asset, plus every index/README that lists its siblings —
+catches those before the reviewer does. Reviewing only the diff reproduces exactly the slow loop
+this flow exists to avoid.
+
+## How to run it (portable across agents)
+
+Run the review as a **dedicated, read-only pass**: it inspects and reports; it does **not** edit.
+The caller applies the fixes, so the review stays unbiased by the intent behind the change. The
+pass works the same on every agent — **Copilot** (the primary reviewer to preempt), **Codex**,
+and **Claude Code**; only the *mechanism* differs, and **subagents are a Claude-Code-only
+optimization, never a requirement**:
+
+- **GitHub Copilot** — no subagents; run the checklist **inline as a distinct pass** before
+  pushing (not folded into the edit under review), over the **whole repository — not just the
+  diff**. Copilot's built-in code review can help on the diff, but only this whole-repo pass
+  covers the drift that triggers new review rounds.
+- **Codex** — no subagents either; the same **inline whole-repo pass**, producing the same
+  prioritized findings list.
+- **Claude Code** — *optionally* delegate the pass to a read-only **subagent** (`Explore` or
+  `general-purpose`) with the brief: "Review this whole repository against the core-review
+  checklist; report findings as `severity | file:line | problem | suggested fix`; do not edit any
+  files." Relay its findings back to the main flow. Running it inline works too.
+
+Whichever agent, the contract is identical: **read-only in, prioritized findings out**, then the
+caller fixes and re-runs until clean.
+
+## The review checklist
+
+Each item lists what to look for and a concrete ❌→✅ example. These are the failure modes that
+actually caused review rounds.
+
+### 1. Docs ↔ code consistency
+
+- Docs claiming behavior the code does not have.
+- A symbol/asset categorized differently across files (e.g. a metadata array vs a README table row).
+- An instruction that contradicts the actual code convention (barrel vs internal import path;
+  an auto-merge `if:` guard that differs from the shipped workflow).
+- A table/tree/index entry for a file that does not exist in the repo (or a file missing from it).
+
+```text
+❌ "The REST API lists review threads and marks them resolved."
+✅ "GraphQL lists review threads (reviewThreads) and resolves them (resolveReviewThread);
+    REST only posts replies." (matches what the code actually calls)
+```
+
+### 2. Code-example validity
+
+Every "correct" snippet must actually compile and match the standard it illustrates.
+
+```typescript
+// ❌ Non-void function with an empty body — does not compile
+export function formatDate(dateString: string): string {}
+
+// ✅ Real body that returns the declared type
+export function formatDate(dateString: string): string {
+  return new Date(dateString).toLocaleDateString("en-US", { dateStyle: "long" });
+}
+```
+
+- No JSDoc patterns inside a TSDoc example (`@param {string} x`, `@param props.child`, `{type}` braces).
+- No syntactically invalid inline snippets (e.g. `foo(a: 1)` where an object was meant: `foo({ a: 1 })`).
+- A JSX component used as an example must return an element, not infer `void`.
+
+### 3. Links & references
+
+- Broken relative links — count the `../` hops from the file's real location.
+
+```text
+❌ From .github/instructions/, linking a test as ../commands/__tests__/init.test.ts
+✅ ../../src/commands/__tests__/init.test.ts   (correct number of ../ hops)
+```
+
+- Outdated version/path references (a GitHub Action pinned `@v4` when the repo standard is `@v7`;
+  a deep module path where the repo convention is a barrel import such as `@/transformer`).
+
+### 4. Markdown hygiene
+
+- Every fenced code block has a language tag (` ```bash `, ` ```typescript `, ` ```text `).
+- Nested backtick spans render correctly (use longer outer fences when a snippet contains backticks).
+- No stray empty bullets or blank list items in templates — use an HTML comment placeholder instead.
+
+### 5. Inventories / tables completeness
+
+README instructions/skills/prompts tables, `AGENTS.md` indexes, directory trees, and any
+"N total" counts must list **all** shipped assets — or be explicitly marked truncated with a total.
+When you add or rename an asset, grep for every index that enumerates its siblings and update each.
+
+### 6. Shell / script robustness (for prompt & skill snippets)
+
+- Stage specific paths, not `git add -A`, so the commit does not sweep unrelated pre-existing changes.
+- Paginate past the first 100 items (walk `pageInfo { endCursor hasNextPage }`), don't stop at page one.
+- A failed API call must **fail fast**, not be treated as an empty result.
+
+```bash
+# ❌ An auth/network failure looks identical to "no threads" — the assertion passes on error
+COUNT=$(gh api graphql -f query='...' | jq '.data.repository.pullRequest.reviewThreads.nodes | length')
+
+# ✅ Fail fast: distinguish an error shape from a genuine empty result before counting
+if ! echo "$PAGE" | jq -e '.data.repository.pullRequest.reviewThreads' >/dev/null 2>&1; then
+  echo "ERROR: GraphQL request failed or returned an unexpected shape" >&2
+  exit 1
+fi
+```
+
+- An "assertion" whose failure branch still exits `0` is not an assertion — exit non-zero on failure.
+- Handle the "all findings were false positives → nothing to commit" case so a referenced `$SHA`
+  is not an unrelated existing HEAD (guard with `git diff --cached --quiet`).
+- Cross-platform test assertions: don't hard-code the `/` path separator (`[\\/]` in regexes),
+  and include `stderr` in failure messages so CI shows why a spawned CLI exited non-zero.
+
+### 7. Repo health
+
+- `package-lock.json` in sync — after a dependency bump, `npm ci` must exit `0`
+  (a drifted lockfile fails with `Missing … from lock file`). Regenerate with
+  `npm install --package-lock-only` and verify `npm ci`.
+- CI matrix / workflow config sanity (a `workflow_run` trigger names a workflow whose `name:`
+  actually exists; `on:` events match intent; least-privilege `permissions:`).
+
+## Highest-recall patterns (from real review rounds)
+
+A few patterns account for **most** reviewer findings — and they are exactly the ones a
+diff-focused read misses, because the defect lives in a file the change only touches the
+*meaning* of. **Check these first.** (Percentages below are from an actual review round of this
+skill's own PR, where a reviewer found 10 issues the initial self-review missed.)
+
+### P1 — Propagate a reframe to *every* description of the concept (highest yield)
+
+When you rename or reframe anything (a term, a default, a capability), the change must reach
+**every surface that describes it** — not only the canonical/body text, but each one-line
+description: README tables, per-agent asset maps (`AGENTS.md`, `AGENTS.codex.md`), directory
+trees, and the CHANGELOG summary. **A concept described two ways is a guaranteed finding** — half
+the findings in the reference round were this single class (the body was reframed; the index rows
+still advertised the old wording).
+
+**Technique — the reframe sweep:** after any rename/reframe, grep the whole repo for the *old*
+term and each synonym, then reconcile every hit.
+
+```bash
+# e.g. after reframing "subagent" → "read-only pass", hunt every lingering description
+grep -rn "subagent" . --include="*.md"
+```
+
+### P2 — Keep the *mechanism* branch-specific, never the *scope/contract*
+
+When guidance branches per agent / platform / environment, only the **mechanism** may differ; the
+**scope or contract** must stay identical across every branch.
+
+```text
+❌ "Copilot runs it inline over the changed files and their neighbors."   (silently narrowed scope)
+✅ "Copilot runs it inline over the whole repository."                     (mechanism differs, scope constant)
+```
+
+### P3 — "We updated X" must match the diff
+
+Every CHANGELOG / PR / summary claim that an artifact was changed must correspond to a file
+**actually in the diff**, and the named target must be a place that could plausibly hold that
+content.
+
+```text
+❌ CHANGELOG: "the prompts README now lists the new skill"  (that file is not in the diff, and a
+   prompts index would not list skills anyway)
+✅ Record only the indexes actually updated (here: the skills README + the asset maps).
+```
+
+### P4 — When you touch an inventory, cross-check *every* sibling
+
+Editing a tree/table to add your entry re-presents the whole inventory as complete — so a
+**pre-existing** omission now reads as your bug. Enumerate what exists on disk and reconcile.
+
+```bash
+# every skill directory here must appear in the README tree AND the skills table
+# (list directories only — a plain `ls` would also print the skills README.md)
+ls -d templates/shared/skills/*/
+```
+
+### P5 — A generated procedure that makes fixes must commit before it pushes
+
+Any documented step that can create fixes and then pushes must **explicitly commit** them and
+confirm a clean worktree (`git status`) first — otherwise the fixes are silently omitted from the
+push, and a referenced `$SHA` points at the wrong commit.
+
+## Output contract
+
+Report findings as a **prioritized list**, most severe first, one row each:
+
+```text
+severity | file:line | problem | suggested fix
+```
+
+- **severity** — `critical` (compile/CI break, wrong behavior claim), `warning` (stale doc,
+  broken link, missing index entry), `nit` (wording, formatting).
+- **file:line** — a clickable anchor so the fix is one jump away.
+- **suggested fix** — concrete enough to apply directly.
+
+Empty output ("no findings") is a valid, good result — say so explicitly rather than inventing nits.
+
+## Acting on findings & convergence
+
+These steps are performed by the **caller** (the agent flow that invoked this skill), not by the
+read-only review pass itself — the pass only inspects and reports.
+
+1. The caller applies every `critical` and `warning`; applies `nit`s unless there is a reason not to.
+2. The caller re-runs the project's checks (`lint`, `type-check`, `tsc --noEmit`, `test`, `build` — whichever exist).
+3. The caller re-runs the review over the whole repo. **Loop until the pass reports zero findings
+   *within the change's blast radius***, *then* push. Pre-existing issues outside that scope are
+   noted (see "What NOT to flag" below) but do not block convergence.
+
+Because these repos guide agents, an inaccurate doc induces downstream errors — so it is worth
+iterating N times to reach an optimal, consistent result rather than stopping at the first
+"good enough" pass. Convergence here means the review pass finds nothing new, not merely
+that CI is green.
+
+## What NOT to flag (avoid false positives)
+
+- Intentional, documented deviations (a snippet explicitly labeled "❌ INCORRECT" is *meant* to be wrong).
+- Style preferences the repo has not adopted — match the surrounding code, don't impose new conventions.
+- Truncated inventories that already declare a total ("… 13 skills total").
+- Pre-existing, unrelated issues outside the change's blast radius — note them separately, do not
+  block the push on them.