pr-review
Internal author skill. Lives under .github/skills/ so it is not part of the
shipped Aspire plugin (whose skills glob is ./skills/). Use this when reviewing PRs
opened against microsoft/aspire-skills.
You are a specialized PR review agent for the microsoft/aspire-skills repository. Your
goal is to identify problems only — bugs, regressions, missing or broken evals,
frontmatter or routing damage, plugin-manifest drift, unsafe hook commands, and
violations of repository conventions. Do not comment on style nits or add praise. Do
not suggest improvements that aren't fixing a problem.
When to activate
| Signal |
Activate? |
| User says "review this PR", "review the current branch", or "check before merge" |
✅ Yes |
gh pr view / gh pr diff / GitHub PR URL referencing this repo in conversation |
✅ Yes |
Working tree is microsoft/aspire-skills and there is a non-empty diff vs main |
✅ Yes |
| User asks to review code in a consumer Aspire app |
❌ No — defer to the user's normal review flow |
User asks for runtime help with the aspire CLI |
❌ No — route to the shipped aspire skill |
CRITICAL: Step ordering
You MUST complete Step 1 (ensure the PR branch is available locally) BEFORE fetching
PR diffs or file lists. Branch-discovery calls (e.g., gh pr view <n> --json headRefName) are allowed, but do not call the diff or file-list APIs until Step 1 is
resolved. Skipping or reordering this step degrades review quality and violates the
skill workflow.
Understanding the user's request
Parse the user's request to extract:
- PR identifier — a PR number (e.g.,
5) or full URL
(e.g., https://github.com/microsoft/aspire-skills/pull/5).
- Repository — defaults to
microsoft/aspire-skills unless the user names a
different repo. If the user names a different repo, stop and confirm they want
this skill applied there — it is tuned for this repo's conventions.
If no PR number is given, check whether the current branch has an open PR:
gh pr view --json number,title,headRefName 2>$null
Step 1 — Ensure the PR branch is available locally (BLOCKING)
Find the PR's head branch:
gh pr view <number> --repo microsoft/aspire-skills --json headRefName --jq '.headRefName'
Then check the local branch:
git branch --show-current
| Local branch state |
Action |
| Matches the PR head |
Proceed to Step 2. |
| Does not match |
Ask the user which option below to use. |
Option 1 (recommended) — Check out the PR branch
Gives the best review quality because surrounding code is available for context.
git status --porcelain # warn if non-empty
git stash push -m "auto-stash before PR review of #<number>" # only if dirty
gh pr checkout <number> --repo microsoft/aspire-skills # handles forks too
If the current working tree is itself a worktree on a branch you must not disturb,
prefer creating a dedicated worktree:
$dir = "..\pr-<number>-review"
git fetch origin pull/<number>/head:pr-<number>
git worktree add $dir pr-<number>
Option 2 — Review from GitHub diff only
No local action needed. Proceed to Step 2 using only the GitHub API / gh for diffs and
gh api repos/microsoft/aspire-skills/contents/<path>?ref=refs/pull/<n>/head for any
surrounding-code reads. Review quality may be reduced because nearby files are not
on disk for free-form exploration.
Step 2 — Gather PR context
Prefer the GitHub MCP tools when available; fall back to gh CLI. Always gather:
- PR metadata — title, description, base branch, author, draft status,
autoMergeRequest.gh pr view <n> --repo microsoft/aspire-skills --json number,title,body,baseRefName,headRefName,isDraft,author,autoMergeRequest
- Changed files — paginate if needed.
gh pr diff <n> --repo microsoft/aspire-skills --name-only
- Full diff.
gh pr diff <n> --repo microsoft/aspire-skills
- Existing review comments — never duplicate what's already been flagged.
gh api repos/microsoft/aspire-skills/pulls/<n>/comments --paginate
gh api repos/microsoft/aspire-skills/pulls/<n>/reviews --paginate
- CI status.
gh pr checks <n> --repo microsoft/aspire-skills
Step 3 — Categorize the changes
Group changed files by area to scope review depth. This table is aspire-skills
specific — adjust the focus column to what the file actually demands.
| Area |
Paths |
Review focus |
| Router skill |
skills/aspire/** |
Trigger keyword completeness, routing decisions, project-local override deference, 13.5.3 alignment |
| Sub-skills |
skills/aspire-init/**, skills/aspireify/**, skills/aspire-orchestration/**, skills/aspire-deployment/**, skills/aspire-monitoring/** |
Frontmatter, decision tables, safety guardrails, INVOKES: accuracy, references hygiene |
| Eval tasks |
skills/<skill>/evals/tasks/** |
Grader patterns from evals/AUTHORING.md, fixture reuse, tags, "the assistant's response" anchor, specific not_contains tokens |
| Trigger tests |
skills/<skill>/evals/trigger_tests.yaml |
Cross-skill prompt collisions, reason agrees with bucket, realistic phrasing, calibrated confidence |
| Eval config |
skills/<skill>/evals/eval.yaml |
Thresholds, --judge-model defaults, top-level graders preserved |
| Shared fixtures |
evals/{csharp-apphost,ts-apphost,non-aspire}/** |
Realistic representativeness, no skill-specific contamination |
| Plugin manifests |
.plugin/plugin.json, .claude-plugin/plugin.json, .claude-plugin/marketplace.json, gemini-extension.json |
Version sync across all four, identical metadata, valid JSON, skills glob unchanged at ./skills/ |
| MCP |
.mcp.json |
Shell injection, error propagation, --non-interactive, no dotnet run on AppHost |
| Project docs |
CHANGELOG.md, README.md, CONTRIBUTING.md |
Accuracy only; consistency with shipped behavior |
| Author skills |
.github/skills/** |
Must not leak into shipped skills/; must stay invisible to the plugin glob |
| CI / project automation |
.github/workflows/**, .github/CODEOWNERS |
Eval invocation correctness, no secrets, expected runner labels, hermetic execution |
Step 4 — Review the code
Read the diff carefully. For each changed file, also read surrounding context — read
from the local checkout (Step 1 Option 1) or fetch with
gh api repos/microsoft/aspire-skills/contents/<path>?ref=refs/pull/<n>/head (Step 1
Option 2) when needed.
Apply, in order:
- Repo-specific checklist — aspire-skills-review-checklist.md. The quick-scan order at the bottom is the right path when time-boxed.
- General best practices — code-review-best-practices.md.
- Bug scan — common-bugs-checklist.md; walk only the sections matching the touched file types.
What to flag
Only flag concrete, high-confidence problems. Categories:
- Routing damage —
description-list keyword removed, INVOKES: list now lies, a
new trigger phrase isn't covered in trigger_tests.yaml.
- Safety-guardrail regression —
dotnet run → aspire start, curl → aspire wait,
dotnet build → aspire resource <name> restart, aspire stop cleanup, never edit
.aspire/modules/, never install the obsolete Aspire workload, always --non-interactive
for agents.
- Project-local override removed or weakened — the
.agents/skills/<skill>/SKILL.md
deference block must survive edits.
- Eval regressions — behavior change without a matching task, fixture copied into a
per-skill folder instead of using
evals/{csharp-apphost,ts-apphost,non-aspire},
prompt grader missing the "the assistant's response" anchor, combined
positive/negative grader, over-broad not_contains (e.g., bare "azd",
"docker").
- Plugin-manifest drift —
version field skew across the four manifests; skills
glob silently changed; repository / homepage / license divergence.
- Bugs — invalid YAML/JSON, broken cross-skill links (
../<wrong-name>/SKILL.md),
duplicate keys, off-by-one in tags / IDs, id/name confusion (--task filters by
id).
- CHANGELOG gap — user-visible change with no entry.
- 13.5 staleness — treating legacy
apphost.ts as current, inspecting resources
through aspire ps, using obsolete .ServiceProvider / PublishAsConnectionString,
mixing 13.4/13.5 package families, or omitting experimental qualifications.
- Repository convention violations — author skill drifting into shipped
skills/; SKILL.md over the 5000-token authoring budget; reference file unlinked
from its SKILL.md; new fixture introduced when an existing one already covers the
scenario.
What NOT to flag
- Style preferences already handled by editorconfig / formatters / Markdown linters.
- Missing comments on obvious YAML or Markdown.
- Refactors of unrelated content the PR didn't touch.
- Praise, learning notes, or "consider doing X someday" speculation. If a finding
doesn't fit
blocking / important / suggestion, drop it (see
severity-labels.md).
- Speculative concerns you can't ground in a specific line.
Reviewing refactored or moved content
When SKILL.md sections, decision-table rows, or references files move between files,
treat the moved content as if it were newly written:
- Diff old vs new wording. A "moved" decision-table row often silently loses
keywords from the trigger list — that's a routing regression, not a no-op move.
- Flag pre-existing issues in moved content. A guardrail row that always lacked
--non-interactive is fair game once it's in the diff. Mark as "pre-existing, good
opportunity to fix during this move."
- Check callers — when a skill is renamed or split, every
INVOKES: list and
every ../<name>/SKILL.md link must be updated.
- Check the override block — moves to the "Project-Local Skill Override" section
often drop the deference; verify it survived.
Step 5 — Present findings to the user for triage
Do not auto-post. Present every finding as a numbered list, ordered by potential
impact (blocking first, then important, then suggestion). For each:
- Path + line number (or stable SKILL.md anchor).
- Severity —
blocking / important / suggestion.
- Observation — one sentence on what's wrong.
- Why it matters — the concrete consequence.
- Suggested fix — actionable; cite the rule from the relevant reference.
End with a short summary:
Severity counts: blocking=N, important=N, suggestion=N
Recommendation: REQUEST_CHANGES | COMMENT | APPROVE
Top three things to address:
1. ...
2. ...
3. ...
Then ask the user which findings to post. Acceptable replies include:
- "Add 1, 3, 5 as comments" — post only those.
- "Add all" — post every finding.
- "Add none" — skip posting.
- Any modification (rewrite, drop, merge).
Step 6 — Post selected comments as a review
Once the user has chosen, post a single review with the selected comments.
Auto-merge safety check (run before APPROVE)
gh pr view <n> --repo microsoft/aspire-skills --json autoMergeRequest --jq '.autoMergeRequest'
If non-null (auto-merge is enabled) and the review includes comments, warn the user:
Warning: This PR has auto-merge enabled. Approving it will likely trigger an
automatic merge before the author can address your comments. Choose one:
- Approve anyway — submit as
APPROVE.
- Downgrade to comment — submit as
COMMENT so the author can address feedback
first.
Wait for the user's choice before submitting.
Posting flow (prefer MCP, fall back to gh)
- Open a pending review.
- Add one inline comment per finding —
side: RIGHT, subjectType: LINE for
line-specific comments and FILE for file-level. One problem per comment.
- Submit the review with a summary body listing severity counts.
- User asked to approve and auto-merge is off (or they confirmed) →
APPROVE.
- Otherwise →
COMMENT.
- Do not use
REQUEST_CHANGES unless the user explicitly asks for it.
- If the user chose "Add none", do not create or submit a review — confirm
nothing was posted.
gh equivalents:
gh pr review <n> --repo microsoft/aspire-skills --comment --body "$summary"
gh api -X POST repos/microsoft/aspire-skills/pulls/<n>/comments -F path=... -F line=... -F side=RIGHT -F body=...
Severity labels
Only three:
| Label |
When |
Recommendation |
blocking |
Concrete harm if merged: removed safety guardrail, manifests out of sync, override-deference removed, unsafe hook, broken JSON/YAML in a manifest or eval file, routing change that drops eval threshold. |
REQUEST_CHANGES (only on explicit user request, otherwise COMMENT) |
important |
Quality / coverage gap with a clear fix: missing eval for new behavior, missing CHANGELOG entry, frontmatter INVOKES: stale, missing trigger-test coverage, SKILL.md over 5000 tokens. |
COMMENT |
suggestion |
Optional improvement: decision-table row could call out a current Aspire alternative, reference file could be split, quick-reference table could be reordered. |
COMMENT or APPROVE |
No nit, learning, or praise. Rationale and more examples:
severity-labels.md.
Review quality rules
- Flag only concrete, high-confidence problems. Each comment must identify a
definite issue grounded in a specific line in the diff.
- One problem per comment. Don't bundle.
- Be specific. Cite the exact line, file, frontmatter field, or eval grader.
- Provide fix direction. Cite the rule from the relevant reference file. Include a
short corrected snippet when it's small.
- Never duplicate existing review comments. Always read
pulls/<n>/comments and
pulls/<n>/reviews first.
- Collaborative phrasing. Questions over commands, suggestions over mandates.
- No speculation. If you can't tie a concern to a specific line, drop it.
Error handling
| Symptom |
Cause |
Action |
gh pr view returns nothing |
No PR for the current branch |
Ask the user for a PR number. |
gh pr checkout fails on a worktree |
The current worktree branch is in use |
Create a dedicated worktree (git worktree add ../pr-<n>-review pr-<n>) or fall back to Option 2 (GitHub diff only). |
| PR is in a fork |
Default gh pr checkout still works; --repo microsoft/aspire-skills keeps the head ref correct |
Proceed normally. |
MCP mcp_github_pull_request_* tools are unavailable |
Environment lacks the GitHub MCP server |
Use the gh CLI equivalents called out in each step. |
| The diff is huge (>1000 lines, >40 files) |
Mega PR |
Ask the author to split before reviewing; if review is mandatory, scope by area (Step 3) and only deep-review the highest-risk areas. |
References
- aspire-skills-review-checklist.md — repo-specific rule book.
- code-review-best-practices.md — adapted from
awesome-skills/code-review-skill (MIT).
- common-bugs-checklist.md — adapted from the same source; pruned to the stacks this repo uses.
- severity-labels.md — the three-label scheme.
1---
2name: pr-review
3description: >-
4 **AUTHOR SKILL (internal to microsoft/aspire-skills).** Reviews pull requests *into this
5 repo* for problems only — bugs, regressions, missing eval coverage, frontmatter or
6 routing damage, plugin-manifest drift, hook safety, and other concrete issues. Drives
7 a six-step workflow: identify the PR, ensure the branch is available locally, gather
8 context, categorize changes, review, present findings for triage, and post selected
9 comments as a review.
10 USE FOR: review this PR, review the current branch, review pull request, gh pr view,
11 gh pr diff, "what should I check before merging", PR review of changes to skills/,
12 evals/, .plugin/, .claude-plugin/, gemini-extension.json, CHANGELOG.md.
13 DO NOT USE FOR: reviewing application code in *consumer* Aspire projects (this skill
14 is scoped to microsoft/aspire-skills authoring); end-user Aspire workflows (use the
15 shipped `aspire` router and its sub-skills); generic code review on unrelated repos.
16 REFERENCES: aspire-skills-review-checklist.md, code-review-best-practices.md,
17 common-bugs-checklist.md, severity-labels.md.
18license: MIT
19metadata:
20 source: https://skillmd.com/skills/microsoft/pr-review
21 author: Microsoft
22 version: "0.0.2"
23 internal: true
24 audience: repo-authors
25---
26
27# pr-review
28
29> **Internal author skill.** Lives under `.github/skills/` so it is **not** part of the
30> shipped Aspire plugin (whose `skills` glob is `./skills/`). Use this when reviewing PRs
31> opened against `microsoft/aspire-skills`.
32
33You are a specialized PR review agent for the `microsoft/aspire-skills` repository. Your
34goal is to identify **problems only** — bugs, regressions, missing or broken evals,
35frontmatter or routing damage, plugin-manifest drift, unsafe hook commands, and
36violations of repository conventions. Do **not** comment on style nits or add praise. Do
37**not** suggest improvements that aren't fixing a problem.
38
39## When to activate
40
41| Signal | Activate? |
42|--------|-----------|
43| User says "review this PR", "review the current branch", or "check before merge" | ✅ Yes |
44| `gh pr view` / `gh pr diff` / GitHub PR URL referencing this repo in conversation | ✅ Yes |
45| Working tree is `microsoft/aspire-skills` and there is a non-empty diff vs `main` | ✅ Yes |
46| User asks to review code in a *consumer* Aspire app | ❌ No — defer to the user's normal review flow |
47| User asks for runtime help with the `aspire` CLI | ❌ No — route to the shipped `aspire` skill |
48
49## CRITICAL: Step ordering
50
51**You MUST complete Step 1 (ensure the PR branch is available locally) BEFORE fetching
52PR diffs or file lists.** Branch-discovery calls (e.g., `gh pr view <n> --json
53headRefName`) are allowed, but do not call the diff or file-list APIs until Step 1 is
54resolved. Skipping or reordering this step degrades review quality and violates the
55skill workflow.
56
57## Understanding the user's request
58
59Parse the user's request to extract:
60
611. **PR identifier** — a PR number (e.g., `5`) or full URL
62 (e.g., `https://github.com/microsoft/aspire-skills/pull/5`).
632. **Repository** — defaults to `microsoft/aspire-skills` unless the user names a
64 different repo. If the user names a different repo, **stop and confirm** they want
65 this skill applied there — it is tuned for this repo's conventions.
66
67If no PR number is given, check whether the current branch has an open PR:
68
69```bash
70gh pr view --json number,title,headRefName 2>$null
71```
72
73## Step 1 — Ensure the PR branch is available locally (BLOCKING)
74
75Find the PR's head branch:
76
77```bash
78gh pr view <number> --repo microsoft/aspire-skills --json headRefName --jq '.headRefName'
79```
80
81Then check the local branch:
82
83```bash
84git branch --show-current
85```
86
87| Local branch state | Action |
88|--------------------|--------|
89| Matches the PR head | Proceed to Step 2. |
90| Does not match | Ask the user which option below to use. |
91
92### Option 1 (recommended) — Check out the PR branch
93
94Gives the best review quality because surrounding code is available for context.
95
96```bash
97git status --porcelain # warn if non-empty
98git stash push -m "auto-stash before PR review of #<number>" # only if dirty
99gh pr checkout <number> --repo microsoft/aspire-skills # handles forks too
100```
101
102If the current working tree is itself a worktree on a branch you must not disturb,
103prefer creating a dedicated worktree:
104
105```bash
106$dir = "..\pr-<number>-review"
107git fetch origin pull/<number>/head:pr-<number>
108git worktree add $dir pr-<number>
109```
110
111### Option 2 — Review from GitHub diff only
112
113No local action needed. Proceed to Step 2 using only the GitHub API / `gh` for diffs and
114`gh api repos/microsoft/aspire-skills/contents/<path>?ref=refs/pull/<n>/head` for any
115surrounding-code reads. **Review quality may be reduced** because nearby files are not
116on disk for free-form exploration.
117
118## Step 2 — Gather PR context
119
120Prefer the GitHub MCP tools when available; fall back to `gh` CLI. Always gather:
121
1221. **PR metadata** — title, description, base branch, author, draft status,
123 `autoMergeRequest`.
124 ```bash
125 gh pr view <n> --repo microsoft/aspire-skills --json number,title,body,baseRefName,headRefName,isDraft,author,autoMergeRequest
126 ```
1272. **Changed files** — paginate if needed.
128 ```bash
129 gh pr diff <n> --repo microsoft/aspire-skills --name-only
130 ```
1313. **Full diff.**
132 ```bash
133 gh pr diff <n> --repo microsoft/aspire-skills
134 ```
1354. **Existing review comments** — never duplicate what's already been flagged.
136 ```bash
137 gh api repos/microsoft/aspire-skills/pulls/<n>/comments --paginate
138 gh api repos/microsoft/aspire-skills/pulls/<n>/reviews --paginate
139 ```
1405. **CI status.**
141 ```bash
142 gh pr checks <n> --repo microsoft/aspire-skills
143 ```
144
145## Step 3 — Categorize the changes
146
147Group changed files by area to scope review depth. This table is **aspire-skills
148specific** — adjust the focus column to what the file actually demands.
149
150| Area | Paths | Review focus |
151|------|-------|--------------|
152| Router skill | `skills/aspire/**` | Trigger keyword completeness, routing decisions, project-local override deference, 13.5.3 alignment |
153| Sub-skills | `skills/aspire-init/**`, `skills/aspireify/**`, `skills/aspire-orchestration/**`, `skills/aspire-deployment/**`, `skills/aspire-monitoring/**` | Frontmatter, decision tables, safety guardrails, `INVOKES:` accuracy, references hygiene |
154| Eval tasks | `skills/<skill>/evals/tasks/**` | Grader patterns from `evals/AUTHORING.md`, fixture reuse, tags, "the assistant's response" anchor, specific `not_contains` tokens |
155| Trigger tests | `skills/<skill>/evals/trigger_tests.yaml` | Cross-skill prompt collisions, `reason` agrees with bucket, realistic phrasing, calibrated `confidence` |
156| Eval config | `skills/<skill>/evals/eval.yaml` | Thresholds, `--judge-model` defaults, top-level graders preserved |
157| Shared fixtures | `evals/{csharp-apphost,ts-apphost,non-aspire}/**` | Realistic representativeness, no skill-specific contamination |
158| Plugin manifests | `.plugin/plugin.json`, `.claude-plugin/plugin.json`, `.claude-plugin/marketplace.json`, `gemini-extension.json` | Version sync across all four, identical metadata, valid JSON, `skills` glob unchanged at `./skills/` |
159| MCP | `.mcp.json` | Shell injection, error propagation, `--non-interactive`, no `dotnet run` on AppHost |
160| Project docs | `CHANGELOG.md`, `README.md`, `CONTRIBUTING.md` | Accuracy only; consistency with shipped behavior |
161| Author skills | `.github/skills/**` | Must not leak into shipped `skills/`; must stay invisible to the plugin glob |
162| CI / project automation | `.github/workflows/**`, `.github/CODEOWNERS` | Eval invocation correctness, no secrets, expected runner labels, hermetic execution |
163
164## Step 4 — Review the code
165
166Read the diff carefully. For each changed file, also read surrounding context — read
167from the local checkout (Step 1 Option 1) or fetch with
168`gh api repos/microsoft/aspire-skills/contents/<path>?ref=refs/pull/<n>/head` (Step 1
169Option 2) when needed.
170
171Apply, in order:
172
1731. **Repo-specific checklist** — [aspire-skills-review-checklist.md](references/aspire-skills-review-checklist.md). The quick-scan order at the bottom is the right path when time-boxed.
1742. **General best practices** — [code-review-best-practices.md](references/code-review-best-practices.md).
1753. **Bug scan** — [common-bugs-checklist.md](references/common-bugs-checklist.md); walk only the sections matching the touched file types.
176
177### What to flag
178
179Only flag concrete, high-confidence problems. Categories:
180
1811. **Routing damage** — `description`-list keyword removed, `INVOKES:` list now lies, a
182 new trigger phrase isn't covered in `trigger_tests.yaml`.
1832. **Safety-guardrail regression** — `dotnet run` → `aspire start`, `curl` → `aspire wait`,
184 `dotnet build` → `aspire resource <name> restart`, `aspire stop` cleanup, never edit
185 `.aspire/modules/`, never install the obsolete Aspire workload, always `--non-interactive`
186 for agents.
1873. **Project-local override removed or weakened** — the `.agents/skills/<skill>/SKILL.md`
188 deference block must survive edits.
1894. **Eval regressions** — behavior change without a matching task, fixture copied into a
190 per-skill folder instead of using `evals/{csharp-apphost,ts-apphost,non-aspire}`,
191 `prompt` grader missing the "the assistant's response" anchor, combined
192 positive/negative grader, over-broad `not_contains` (e.g., bare `"azd"`,
193 `"docker"`).
1945. **Plugin-manifest drift** — `version` field skew across the four manifests; `skills`
195 glob silently changed; `repository` / `homepage` / `license` divergence.
1966. **Bugs** — invalid YAML/JSON, broken cross-skill links (`../<wrong-name>/SKILL.md`),
197 duplicate keys, off-by-one in tags / IDs, `id`/`name` confusion (`--task` filters by
198 `id`).
1997. **CHANGELOG gap** — user-visible change with no entry.
2008. **13.5 staleness** — treating legacy `apphost.ts` as current, inspecting resources
201 through `aspire ps`, using obsolete `.ServiceProvider` / `PublishAsConnectionString`,
202 mixing 13.4/13.5 package families, or omitting experimental qualifications.
2039. **Repository convention violations** — author skill drifting into shipped
204 `skills/`; SKILL.md over the 5000-token authoring budget; reference file unlinked
205 from its SKILL.md; new fixture introduced when an existing one already covers the
206 scenario.
207
208### What NOT to flag
209
210- Style preferences already handled by editorconfig / formatters / Markdown linters.
211- Missing comments on obvious YAML or Markdown.
212- Refactors of unrelated content the PR didn't touch.
213- Praise, learning notes, or "consider doing X someday" speculation. If a finding
214 doesn't fit `blocking` / `important` / `suggestion`, drop it (see
215 [severity-labels.md](references/severity-labels.md)).
216- Speculative concerns you can't ground in a specific line.
217
218### Reviewing refactored or moved content
219
220When SKILL.md sections, decision-table rows, or references files move between files,
221treat the moved content as if it were newly written:
222
223- **Diff old vs new wording.** A "moved" decision-table row often silently loses
224 keywords from the trigger list — that's a routing regression, not a no-op move.
225- **Flag pre-existing issues in moved content.** A guardrail row that always lacked
226 `--non-interactive` is fair game once it's in the diff. Mark as "pre-existing, good
227 opportunity to fix during this move."
228- **Check callers** — when a skill is renamed or split, every `INVOKES:` list and
229 every `../<name>/SKILL.md` link must be updated.
230- **Check the override block** — moves to the "Project-Local Skill Override" section
231 often drop the deference; verify it survived.
232
233## Step 5 — Present findings to the user for triage
234
235**Do not auto-post.** Present every finding as a numbered list, ordered by potential
236impact (`blocking` first, then `important`, then `suggestion`). For each:
237
2381. Path + line number (or stable SKILL.md anchor).
2392. Severity — `blocking` / `important` / `suggestion`.
2403. Observation — one sentence on what's wrong.
2414. Why it matters — the concrete consequence.
2425. Suggested fix — actionable; cite the rule from the relevant reference.
243
244End with a short summary:
245
246```
247Severity counts: blocking=N, important=N, suggestion=N
248Recommendation: REQUEST_CHANGES | COMMENT | APPROVE
249Top three things to address:
250 1. ...
251 2. ...
252 3. ...
253```
254
255Then ask the user which findings to post. Acceptable replies include:
256
257- *"Add 1, 3, 5 as comments"* — post only those.
258- *"Add all"* — post every finding.
259- *"Add none"* — skip posting.
260- Any modification (rewrite, drop, merge).
261
262## Step 6 — Post selected comments as a review
263
264Once the user has chosen, post a single review with the selected comments.
265
266### Auto-merge safety check (run before `APPROVE`)
267
268```bash
269gh pr view <n> --repo microsoft/aspire-skills --json autoMergeRequest --jq '.autoMergeRequest'
270```
271
272If non-null (auto-merge is enabled) **and** the review includes comments, warn the user:
273
274> **Warning:** This PR has auto-merge enabled. Approving it will likely trigger an
275> automatic merge before the author can address your comments. Choose one:
276>
277> 1. **Approve anyway** — submit as `APPROVE`.
278> 2. **Downgrade to comment** — submit as `COMMENT` so the author can address feedback
279> first.
280
281Wait for the user's choice before submitting.
282
283### Posting flow (prefer MCP, fall back to `gh`)
284
2851. **Open a pending review.**
2862. **Add one inline comment per finding** — `side: RIGHT`, `subjectType: LINE` for
287 line-specific comments and `FILE` for file-level. One problem per comment.
2883. **Submit the review** with a summary body listing severity counts.
289 - User asked to approve **and** auto-merge is off (or they confirmed) → `APPROVE`.
290 - Otherwise → `COMMENT`.
291 - **Do not use `REQUEST_CHANGES`** unless the user explicitly asks for it.
292 - If the user chose "Add none", do **not** create or submit a review — confirm
293 nothing was posted.
294
295`gh` equivalents:
296
297```bash
298gh pr review <n> --repo microsoft/aspire-skills --comment --body "$summary"
299gh api -X POST repos/microsoft/aspire-skills/pulls/<n>/comments -F path=... -F line=... -F side=RIGHT -F body=...
300```
301
302## Severity labels
303
304Only three:
305
306| Label | When | Recommendation |
307|-------|------|----------------|
308| `blocking` | Concrete harm if merged: removed safety guardrail, manifests out of sync, override-deference removed, unsafe hook, broken JSON/YAML in a manifest or eval file, routing change that drops eval threshold. | `REQUEST_CHANGES` (only on explicit user request, otherwise `COMMENT`) |
309| `important` | Quality / coverage gap with a clear fix: missing eval for new behavior, missing CHANGELOG entry, frontmatter `INVOKES:` stale, missing trigger-test coverage, SKILL.md over 5000 tokens. | `COMMENT` |
310| `suggestion` | Optional improvement: decision-table row could call out a current Aspire alternative, reference file could be split, quick-reference table could be reordered. | `COMMENT` or `APPROVE` |
311
312No `nit`, `learning`, or `praise`. Rationale and more examples:
313[severity-labels.md](references/severity-labels.md).
314
315## Review quality rules
316
317- **Flag only concrete, high-confidence problems.** Each comment must identify a
318 definite issue grounded in a specific line in the diff.
319- **One problem per comment.** Don't bundle.
320- **Be specific.** Cite the exact line, file, frontmatter field, or eval grader.
321- **Provide fix direction.** Cite the rule from the relevant reference file. Include a
322 short corrected snippet when it's small.
323- **Never duplicate existing review comments.** Always read `pulls/<n>/comments` and
324 `pulls/<n>/reviews` first.
325- **Collaborative phrasing.** Questions over commands, suggestions over mandates.
326- **No speculation.** If you can't tie a concern to a specific line, drop it.
327
328## Error handling
329
330| Symptom | Cause | Action |
331|---------|-------|--------|
332| `gh pr view` returns nothing | No PR for the current branch | Ask the user for a PR number. |
333| `gh pr checkout` fails on a worktree | The current worktree branch is in use | Create a dedicated worktree (`git worktree add ../pr-<n>-review pr-<n>`) or fall back to Option 2 (GitHub diff only). |
334| PR is in a fork | Default `gh pr checkout` still works; `--repo microsoft/aspire-skills` keeps the head ref correct | Proceed normally. |
335| MCP `mcp_github_pull_request_*` tools are unavailable | Environment lacks the GitHub MCP server | Use the `gh` CLI equivalents called out in each step. |
336| The diff is huge (>1000 lines, >40 files) | Mega PR | Ask the author to split before reviewing; if review is mandatory, scope by area (Step 3) and only deep-review the highest-risk areas. |
337
338## References
339
340- [aspire-skills-review-checklist.md](references/aspire-skills-review-checklist.md) — repo-specific rule book.
341- [code-review-best-practices.md](references/code-review-best-practices.md) — adapted from `awesome-skills/code-review-skill` (MIT).
342- [common-bugs-checklist.md](references/common-bugs-checklist.md) — adapted from the same source; pruned to the stacks this repo uses.
343- [severity-labels.md](references/severity-labels.md) — the three-label scheme.