PR Comment Skill

Build one self-contained PR-comment.md at the project root. It rolls every earlier review output into a single document a reviewer can paste directly into a GitHub PR.

Gather context first

This skill ships standalone, so it can't assume your project's conventions, house style, or preferences the way it could for its author. Before doing the main work:

1. Auto-detect what you safely can from the repo — language/stack, base branch, build/test commands, existing config and docs. Never ask for something you can read for yourself.
2. Ask, don't assume, for the rest. Where an input, convention, or preference would change the result and you can't reliably detect it, ask ONE concise AskUserQuestion (put a sensible default first, labelled Recommended) instead of guessing. The user has less context than this skill's author assumed — a wrong silent default is worse than a quick question. Don't ask about things you can detect, and don't ask more than you need.

For this skill, confirm up front (only the items you can't already detect):

• Which review files to consolidate — auto-detect REVIEWED.md, SCOPE_REVIEW_*.md, PLAN_REVIEW_*.md, and *_REVIEW_*.md at the repo root; ask only when none are found or the reviews live in another folder.
• The PR reference (number / title / URL) for the header — detect it from the open PR on the current branch with gh when you can; otherwise ask, or confirm there is no PR yet.
• Output target — default is PR-comment.md at the repo root; confirm if the user wants a different path, and whether to also post it to the PR with gh pr comment or just write the file.
• Tone and audience — this skill rewrites every finding into plain, B1-level English for teams whose first language is not English; confirm that fits, or keep the source reviews' existing wording instead.
• Severity labels — the 🔴 MUST FIX / 🟡 SHOULD FIX / 🟢 FOLLOW-UP scheme; confirm if the team uses different severity names.

Inputs

Usually the user hands you a PR reference (such as PR #658) or nothing at all. Work out the scope first:

• When a PR number is supplied, you may fetch gh pr view <n> --json title,author,url,headRefName,baseRefName to fill in the header. When none is supplied, try gh pr view --json ... for the open PR on the current branch before asking; only ask for the reference when detection fails.
• Hunt for review source files at the repo root (confirm with the user when none turn up there, in case the reviews live in another folder):
  • REVIEWED.md — line-level code review (MUST FIX / SHOULD FIX / FOLLOW-UP, with before/after blocks)
  • SCOPE_REVIEW_<ref>.md — strategic review (scope, architecture)
  • PLAN_REVIEW_<ref>.md — execution review (tests, performance, failure modes)
  • any other *_REVIEW_*.md file

When none of those files exist, say there is nothing to consolidate and stop.

Rules

1. Stand on its own. PR-comment.md must never point at another file by name ("see REVIEWED.md", "per the scope review"). Copy every finding in, complete with its file path, line numbers, and fix.
2. Each issue carries a real before/after code block AND a "Required test" line — never just a description. Take the code from the source review files; when it is missing, Read the source file directly to capture accurate line context. The required test must name one specific test (function name plus what it checks) that would have caught the bug, so the fix cannot silently break again.
3. Remove duplicates across the review files. When REVIEWED.md and PLAN_REVIEW_*.md raise the same issue, fold them into one entry and keep the most actionable fix.
4. Map severity like this (use the team's own severity names instead when they differ — confirm if it is not the default three):
   • MUST FIX / CRITICAL / BLOCKER → 🔴 MUST FIX
   • SHOULD FIX / HIGH → 🟡 SHOULD FIX
   • FOLLOW-UP / LOW / INFORMATIONAL → 🟢 FOLLOW-UP
5. Pick the verdict: any MUST FIX → REQUEST_CHANGES; only SHOULD FIX → NEEDS_REVISION; only FOLLOW-UP → APPROVE WITH FOLLOW-UPS; nothing → APPROVE.
6. Leave out meta commentary about the review process, agent names, or which file a finding came from.
7. Tone: plain English. The readers are developers whose first language is not English. Write so a B1-level reader follows along without reaching for a dictionary. Rules:
   • One idea per sentence. Aim for 20 words or fewer. Split long sentences in two.
   • Common words only. Choose "fix" over "remediate", "use" over "leverage", "run" over "invoke", "before" over "prior to", "because" over "due to the fact that", "old" over "pre-existing", "so" over "accordingly".
   • No idioms, metaphors, or figures of speech. Skip "blast radius", "boil the ocean", "land this", "ship it", "low-hanging fruit", "on the fence", "gotcha", "bake in", "punt on". State exactly what you mean.
   • No Latin abbreviations. Write "for example" not "e.g.", "that is" not "i.e.", "and so on" not "etc."
   • Active voice. "This deletes the row" beats "The row is deleted".
   • Name the thing. Say "the UploadDocuments function", not "this function" or "it", once you are 2+ sentences away from the last mention.
   • Define jargon on first use when you cannot avoid it. "TOCTOU (time-of-check vs. time-of-use — reading a value, then writing based on that read, with a gap where another writer can change it)".
   • Stay direct and actionable. Plain does not mean vague — "this wipes the DB column" is both simpler and more exact than "this may have unintended downstream effects on persisted state".
8. One numbering scheme. No parallel structures. Source reviews — SCOPE_REVIEW_*.md especially — often hold a separate "ship gate" or "rollout conditions" section with items like "add a feature flag", "set up an audit log", "run a canary", "file a deletion ticket". Do not copy that split into the PR comment. Sort each ship-gate item by what it actually is:
   • Code-level merge blockers (add a feature flag, add structured logging, add a config field) → fold into the MUST FIX list with a real before/after code block. Give it the next sequential issue number.
   • Pre-merge process steps an existing finding already covers (file a deletion ticket → already covered by the "old code path is still wired" finding) → drop the duplicate and reference the existing finding instead.
   • True post-merge operational steps that are not code changes (run an SQL audit, canary with a dev mailbox for 48h, verify the kill switch, schedule deletion after N clean days) → gather them in one small 📦 Post-merge rollout checklist section after the findings list. Use checkbox format (- [ ] step). Keep it to 5–7 lines.
   • The reader should see one numbered list of issues, then one short checklist of operational steps. No "ship gate" header in PR-comment.md.
9. Premise / product questions sit at the top. When the PR body is empty, or the source reviews raise unanswered product questions (common when SCOPE_REVIEW_*.md has "Unresolved decisions"), place them in a ❓ Product questions section right under the verdict block, before the issue list. Give every question a status:
   • ### N. <Topic> — ANSWERED once the author has confirmed an answer in the conversation. Quote the answer in one line, then add a short "implication" paragraph that names the findings it creates, downgrades, or upgrades.
   • ### N. <Topic> — STILL OPEN when no answer exists yet. State the question and what each possible answer would mean for the code. Once every question is answered, rename the header to ❓ Product questions — all answered, so a reader scanning the document sees that the premise is locked.
10. Severity can move between iterations. When the user re-runs the skill after the author answers a question, an existing finding may need a new severity:
    • Promotion (for example SHOULD FIX → MUST FIX): when the answer confirms the worst case. Example: "is SendTo one email or a list?" was a SHOULD FIX "decide later". Once the author says "list, comma-separated", the single-email code becomes a real bug — promote it to MUST FIX. Tag the finding title with [⚠️ PROMOTED TO MUST FIX] so a reader who saw the earlier version notices.
    • Demotion (for example MUST FIX → FOLLOW-UP): when the answer shows the behavior was intended. Example: "insurances without SendTo get no email" looked like a regression against the always-fired global list. Once the author says "empty SendTo means do nothing — this is intended", demote it to FOLLOW-UP and reframe it as observability (log a warning so operators can see the silent skips).
    • Keep the issue number stable across iterations even as severity changes. Physically move the issue body to the right section (MUST FIX / SHOULD FIX / FOLLOW-UP), but do not renumber — people may have referred to "issue 9" in conversation, and renumbering breaks those references.
11. Physical position must always match the section header. No exceptions. A MUST FIX finding belongs under the 🔴 MUST FIX header. A SHOULD FIX belongs under 🟡 SHOULD FIX. A FOLLOW-UP belongs under 🟢 FOLLOW-UP. After every Edit that promotes, demotes, or adds a finding, run this check before you return:
    • Do a structural scan (for example grep -n "^### \|^## 🔴\|^## 🟡\|^## 🟢" PR-comment.md) and walk the output.
    • For each ### N. line, look up its severity in the summary table at the bottom. The section header above it must agree.
    • When they disagree, move the finding body. Cut from ### N. through the trailing --- (include both ends) and paste it under the right section header.
    • Never leave a "Severity note: this is actually MUST FIX, ignore the SHOULD FIX header above it" workaround. That defeats scanning by section.
    • When a section's numbers run out of order because of moves (for example MUST FIX holds 1, 2, 3, 4, 5, 6, 9, 20, 21, 22), add a one-line italic note under the first out-of-order finding's title: _(Number N is kept stable from when this finding sat under <section>. <One-line reason>.)_ This tells the reader the gap is on purpose.
12. New answers can spawn new findings. When the author resolves a question, the answer often exposes a missing piece of work. Example: "applies to every hospital" reveals THG is not wired up today. Add the new finding with the next free number, place it under the correct severity header from the start, and update the summary table, the counts, and the "before re-review" list.

Output format

# PR #<num> Review — <PR title>

**Verdict: <VERDICT>**

<1-3 sentence summary of what the PR does and the headline risk.>

---

## ❓ Product questions

<Only when the source reviews include unanswered or just-answered premise questions. Omit this section when there are none.>

### 1. <Topic> — ANSWERED | STILL OPEN

**Author confirms:** <one-line quote of the answer, when ANSWERED>
<Implication paragraph: which findings does this answer create, upgrade, downgrade, or close?>

<Repeat for each question. When all are answered, rename the section header to "❓ Product questions — all answered".>

---

## 🔴 MUST FIX (blockers)

### N. <Short title — plain English, no jargon>

**File:** `path/to/file.ts:LINE_START–LINE_END`

**What is wrong:** <1 short sentence.>
**Why it matters:** <1 short sentence — user impact in concrete terms, not abstract risk.>
**How to fix:** <1 short sentence pointing at the code change.>

**Current:**
```lang
// problematic code

Fix:

// corrected code

Required test: path/to/file_test.ext

func TestName_Scenario(t *testing.T) {
    // seed
    // call the code under test
    // assert the failure mode is locked down
}

🟡 SHOULD FIX

🟢 FOLLOW-UP

🧪 Tests required before merge

<Only if the source reviews mention test gaps. Table with ID | File | What it covers.>

📦 Post-merge rollout checklist

<Only when the source reviews list true post-merge operational steps that are not code changes for this PR. Use checkbox format. Keep to 5–7 lines. Examples: SQL audits, canary recipients, kill-switch verification, scheduled deletions. Code-level merge blockers like feature flags and audit logs do NOT belong here — they go in MUST FIX. Omit this section when there are no post-merge steps.>

• <Operational step 1>
• <Operational step 2>

📋 Summary table

<Counts: N MUST FIX, N SHOULD FIX, N FOLLOW-UP = N issues.>

Before re-review, please:

1. <Concrete next step 1>
2. <Concrete next step 2>

## Process

1. Glob for review files at the repo root: `REVIEWED.md`, `SCOPE_REVIEW_*.md`, `PLAN_REVIEW_*.md`, `*_REVIEW_*.md`. Also check whether `PR-comment.md` already exists — step 11 covers iteration.
2. Read each file in full. Read large files in chunks.
3. Build one consolidated issue list. Remove duplicates by file + line range + concern.
4. For any issue missing a concrete fix snippet, Read the source file to pull the exact current code.
5. **Sort the ship-gate items.** When `SCOPE_REVIEW_*.md` (or any source) carries a separate "ship gate" / "rollout conditions" / "pre-merge checklist" section, walk it item by item:
   - Is it a code change for this PR? → MUST FIX finding (next sequential number).
   - Does an existing finding already cover it? → drop the duplicate and reference that finding number.
   - Is it a true post-merge operational step (canary, kill switch, SQL audit, scheduled deletion)? → place it under the `📦 Post-merge rollout checklist` checkbox section after the findings list. Do not number it.
6. **Pull out the premise questions.** Scan the source reviews for "Unresolved decisions", "Premise questions", "Open questions", or anything similar. Lift them to the top under `❓ Product questions`. For each one: status (ANSWERED or STILL OPEN), the answer if known, and the implication for findings.
7. Assign a single sequential numbering across every severity.
8. **Translate to plain English.** Source reviews often lean on complex sentences, idioms, and Latin abbreviations. Rewrite each finding with the Rule 7 checklist before you write the file. Common swaps:
   - "introduces a regression" → "breaks existing behavior"
   - "the blast radius is bounded" → "this only affects X"
   - "pre-existing, deferred" → "this bug was already there before this PR. Fix it in a later PR."
   - "TOCTOU" → "race condition between a read and a write"
   - "non-atomic" → "not wrapped in a transaction, so a failure in step 2 leaves step 1's changes in the database"
   - "orphaned records" → "database rows that point to deleted files"
9. Write `PR-comment.md` at the repo root (or the path the user prefers). When the user asked to post it, follow up with `gh pr comment <n> --body-file <path>`; otherwise just write the file.
10. **Self-check before returning.** Re-read the file. For each paragraph, ask: would a B1 English reader get this on the first pass? If not, rewrite it. Flag any sentence over 25 words and split it. Then confirm two structural checks:
    - No `🚦 Ship gate` section is left (those items belong in MUST FIX or `📦 Post-merge rollout checklist`).
    - Every finding's section header matches the severity in the summary table. Run `grep -n "^### \|^## 🔴\|^## 🟡\|^## 🟢" PR-comment.md` and walk the output. When a finding the table calls MUST FIX sits under `🟡 SHOULD FIX`, move it. See rule 11.
11. **Iteration handling.** When `PR-comment.md` already exists as the skill runs, the user is iterating — usually because the PR author answered a premise question or the source reviews changed. Use Edit, not Write, so the issue numbers stay stable across iterations. Specifically:
    - For a question that just got answered: switch its `STILL OPEN` to `ANSWERED`, add the quoted answer, and write the implication paragraph that names any new, promoted, or demoted findings.
    - For a finding whose severity changed: move its body to the right section header but keep its number. Add `[⚠️ PROMOTED TO MUST FIX]` or `[ℹ️ DEMOTED TO FOLLOW-UP]` to the title.
    - For a new finding an answer triggered: add it with the next sequential number, and never reuse a number from a removed finding.
    - Re-tally the counts and the "Before re-review" list at the bottom on every iteration.
12. Report back: path, verdict, and counts by severity. Under 100 words.

## When not to use

- When the user wants to POST the comment to GitHub, run `gh pr comment <n> --body-file PR-comment.md` as a follow-up step — but only when the user explicitly asks.
- When the user wants a fresh review rather than a consolidation, use the `code-review` skill instead.
- When no review files exist yet, tell the user to run `/code-review` first.