--- name: roast description: Have the AI review the current pull request's diff against the target repository's own policies and commit history — not an external ruleset — then post the findings as a PR review with inline comments and a summary. Use when the user says roast, review, asks for a PR review, or wants CodeRabbit-style automated review after shipping. --- # Roast Workflow Use this skill when the user asks the AI to roast (review) a pull request, or right after `ship` opens/updates one and the user asks for a review pass on it. ## Contents - [At A Glance](#at-a-glance) - [Requirements](#requirements) - [What This Is Not](#what-this-is-not) - [Trigger Rules](#trigger-rules) - [Sources Of Truth](#sources-of-truth) - [Prerequisites](#prerequisites) - [Default Path](#default-path) - [Severity Guide](#severity-guide) - [Comment Format](#comment-format) - [Guardrails](#guardrails) - [Stop Conditions](#stop-conditions) - [Handoff](#handoff) - [Response Examples](#response-examples) ## At A Glance 1. Confirm there is an open pull request for the current branch. 2. Read the actual PR diff, not just the working tree. 3. Check the diff against this repo's own policies, not external style rules. 4. Report findings by severity, then post them as a single PR review: one comment anchored to each finding's diff line, plus one summary. 5. Stop. Do not push fixes unless the user explicitly asks. ## Requirements What the end user needs in place before this skill can work at all: - A GitHub MCP connector configured for this session, authenticated as an account with comment/review write access to the repository (not just read). Without write access, findings can still be produced but never posted. - `gh` installed and authenticated as a fallback path, for when the MCP connector is unavailable mid-session. - The branch must already have an open, non-draft pull request — run `ship` first if it doesn't. This skill reviews an existing PR; it does not create one. - `context/policies/` present in the repo for the policy-compliance checks to mean anything; if this repo doesn't have them, that check is skipped rather than invented (see [Sources Of Truth](#sources-of-truth)). ## What This Is Not - Not a fix workflow. It reports; it does not edit code. - Not a replacement for `ship`'s commit-time validation — this runs against the PR as a whole, after it exists. - Not permission to approve, merge, or request changes on the PR unless the user explicitly asks; posting a comment is not a review decision. - Not a search for an external "coderabbit ruleset." This repo's own `context/policies/` files and code are the standard, not a hosted or invented rulebook. ## Trigger Rules - Run when the user explicitly asks to roast, review, review the PR, or check the branch the way an automated reviewer would. - Run immediately after `ship` when the user's current-turn message explicitly asks for a review alongside it (e.g. "ship it and roast it"). A preference stated in an earlier turn does not carry forward — posting a PR review is gated by `context/policies/approval-policy.md` the same as any other mutation, needing the current-turn go-ahead every time, not a remembered standing instruction. - Do not run automatically on every `ship` unless the user has said so; `ship` and `roast` are separate skills with separate trigger rules. ## Sources Of Truth Rely on what already exists in this repo instead of an external knowledge base: - `context/policies/branch-policy.md`, `context/policies/commit-policy.md`, and `context/policies/writing-guidelines.md` for naming, commit, and PR-text compliance. - `context/policies/review-policy.md` for reviewer priority order, severity levels, and findings format — do not invent a different taxonomy. - `context/policies/approval-policy.md` for which PR actions need the user's current-turn go-ahead. - The PR's own commit history for whether Conventional Commits was actually followed, not just the final diff. - Any project-local architecture, design-system, or lint/CI config already in the repo (e.g. `CLAUDE.md`, `AGENTS.md`, linter configs, CI workflow files). Read what the repo already enforces; do not assume rules it does not have. - The PR description and linked issue/task, if any, as the benchmark for scope — read it before judging whether something is missing or out of scope. For each `context/policies/` above, use the target repo's copy when it exists; otherwise use the bundled copy at `${CLAUDE_PLUGIN_ROOT}/context/policies/`. If the repo has none of the above beyond generic conventions, review against correctness, the conventions already visible in the surrounding code, and the policies above only. ## Prerequisites - Call `get_me` first to confirm the connected GitHub identity and its access before doing anything else — this predicts permission failures (fork PRs, read-only tokens) instead of discovering them after building the review. If the MCP path is unavailable, use `gh api user` as the equivalent identity check before continuing. - Confirm the current branch is non-`main` and has an open, non-draft pull request; use the GitHub MCP connector to fetch it, falling back to `gh` only if the MCP path is unavailable or blocked. If no PR exists yet, that most likely means `ship` hasn't run on this branch — say so instead of a generic "no PR found." - Fetch the full PR diff and commit list from GitHub, not a local `git diff` guess — the PR may include commits from other pushes. - Record the PR's current head SHA, base SHA (or an equivalent diff-identity hash), and state (open) before reviewing, and re-check all of them immediately before posting — if the head or base changed (a force-push, a new commit, or a retargeted base branch), re-fetch the diff and recompute findings instead of posting against a stale one; if the PR was merged or closed while the review was being built, stop and report that instead of posting to a PR that's no longer open. - Check for an existing pending review on the PR (`pull_request_review_write` method `get`/list, or the equivalent read). Never auto-discard it, even if it belongs to the connected account — account ownership doesn't tell you whether it's a stale leftover from an interrupted run or a still-active review from the same account running concurrently in another session. If one exists, stop and surface it to the user for confirmation before proceeding, without making any other PR mutation (see Stop Conditions). - Check for this skill's prior review(s) on the PR: find the latest review body ending in the `` marker (see Comment Format), and use that SHA as the prior review's commit. If one exists, review only the code delta since that commit and note which earlier findings still stand, were fixed, or no longer apply — do not re-post unchanged findings as if they were new. Scope and policy compliance (PR title, description, branch name) are PR-level, not commit-level — re-check those against their current state every time, even on a delta review. - Read the sources listed above before judging anything. ## Default Path 1. Fetch the PR (title, body, commits, diff) through the GitHub MCP connector. 2. Compare the diff against the PR description/linked task — flag scope gaps in either direction (planned-but-missing, or shipped-but-unplanned). 3. Check policy compliance: branch name, each commit title/body, and the PR title/body against `context/policies/`. 4. Scan the full diff for hardcoded secrets, tokens, keys, or credentials first, before any file-type exclusion, and flag any as Critical — this check applies to every file in the diff, generated/vendored/lockfiles included, since leaked credentials show up in those as often as in hand-written code. 5. Check the code itself: correctness, error handling, edge cases, and consistency with existing patterns in the touched files. Skip generated, vendored, or lockfile diffs (e.g. `*.lock`, `dist/`, `node_modules/`, checked-in build output) for this correctness pass only — no human authored those lines. If the diff is too large to read in one pass, review file-by-file, prioritizing logic and security-sensitive files over docs/config, rather than silently truncating or skipping the rest. Past a handful of files, split the file-by-file pass across parallel read-only subagents (e.g. `Explore`) instead of working through them serially — each takes a disjoint subset of files plus the sources from [Sources Of Truth](#sources-of-truth) and returns findings only, with no git/GitHub write tools and no ability to post anything itself. Before splitting, skim the diff for cross-file relationships — a shared type/interface, schema, or config touched in more than one file. Merge overlapping relationships into connected file groups (if group {A, B} and group {B, C} share a file, treat {A, B, C} as one group), then keep each complete group in one subagent's subset rather than letting it split across two. A change whose other half a subagent cannot see can appear correct in isolation but be wrong in combination. After subagent findings return, run a final pass yourself over any cross-file groups the skim flagged, checking exactly the cross-file inconsistency the skim was watching for, plus any cross-file issue a subagent's own findings surfaced that the skim didn't catch — the skim only reduces the odds of missing a relationship, it doesn't guarantee catching all of them. Skip this final pass only when neither the skim nor the subagent findings turned up anything cross-file to check. Either way, this keeps the sweep's cost tied to real cross-file surface area instead of total file count. This skill still merges, ranks, and formats every returned finding, and still owns posting the review — a subagent gathers evidence, it never becomes a second reviewer with its own voice or a shortcut around the rest of this Default Path. 6. Rank findings by severity (see below). Group findings that land on the same file/line into a single inline comment instead of stacking multiple comments on one line. 7. Post the findings as one PR review through the GitHub MCP connector: - `pull_request_review_write` with method `create` to open a pending review. - `add_comment_to_pending_review` once per remaining file/line, capped at 20 inline comments. Beyond the cap, add the rest to the summary body's Unanchored findings block instead of continuing to post individual comments — a wall of inline comments is noise, not signal. If any `add_comment_to_pending_review` call fails, stop adding further comments and do not call `submit_pending` — report the failure and that a pending review was left partially built on the PR (see Stop Conditions). - `pull_request_review_write` with method `submit_pending` (event `COMMENT`, never `REQUEST_CHANGES`/`APPROVE` unless the user asks) using the summary report as the review body. A finding can only anchor to a line inside the diff's hunks — GitHub rejects comments on unchanged lines. Route any finding without a valid diff-line anchor (e.g. "this untouched file should have been updated too") into the summary body's "Unanchored findings" section instead of dropping it or erroring. Fall back to `gh api repos///issues//comments -f body=` to post the full report as one issue comment only if the MCP review-write path is itself unavailable — it returns a parseable `id`/`html_url`, unlike relying on console output from `gh pr comment`. 8. Confirm `submit_pending` (or the `gh` fallback) actually returned a review ID/URL before declaring success — a call that doesn't error is not proof it posted. For the `gh` fallback, validate the response's `id`/`html_url`, or read back the PR's issue comments and match the one just created; don't assume success from the absence of an error. 9. Report the same findings to the user in the chat response. ## Severity Guide See `context/policies/review-policy.md` for the severity levels (Critical/Important/Minor) and reviewer priority order findings must follow. ## Comment Format Inline comment (one per line-specific finding, via `add_comment_to_pending_review`): carry the fields from `context/policies/review-policy.md`'s Findings Format section (severity, finding, why it matters / what to do) and render them in the same visual language as the review body, top to bottom: 1. **Severity alert**: a GitHub alert whose color matches the severity, with the same emoji as the scoreboard. Use `[!CAUTION]` 🚨 for Critical, `[!WARNING]` ⚠️ for Important, `[!NOTE]` 💡 for Minor, and `[!TIP]` 🤔 for a judgment call. Its first line is the bold severity plus a two-to-four-word topic. 2. **What's wrong**: one or two sentences, with code identifiers, paths, and headings in backticks. 3. **🛠️ Fix**: the concrete remediation, starting with a verb. 4. **Suggestion block** (optional): when the fix is a small change to the anchored lines, add a ` ```suggestion ` block so the author can apply it in one click. Anchor the comment's `startLine`..`line` (side `RIGHT`) to exactly the lines the block replaces; omit it when the fix spans other lines or files. 5. **🤖 Prompt for AI agents**: a collapsed `
` holding a ` ```text ` block the author can paste into any coding agent. Make it self-contained, since the agent won't see the PR: file path, line range, and the quoted anchored text or nearest heading (lines shift as other fixes land), what's wrong, the fix, and how to confirm it worked. Keep it to plain instructions with no emoji or alert markup. ````markdown > [!NOTE] > **💡 Minor** · Table of contents out of sync `Contents` stops at `Handoff`, but the file has a `## Response Examples` section (line 114). `land`'s Contents already lists it. **🛠️ Fix:** Add the missing entry so the table of contents matches the file. ```suggestion - [Handoff](#handoff) - [Response Examples](#response-examples) ```
🤖 Prompt for AI agents ```text In skills/yap/SKILL.md, the Contents list (lines 12-21) ends at "- [Handoff](#handoff)" but the file also has a "## Response Examples" section. Add "- [Response Examples](#response-examples)" after the Handoff entry. Confirm every "## " heading in the file has a matching Contents entry. ```
```` When several findings share one line (see Default Path step 6), post one comment with an alert per finding, most severe first, and at most one suggestion block. Put each finding's prompt directly under its own alert and Fix line; place the single suggestion block after the last finding. Review-body summary (the `submit_pending` body, covers everything that isn't line-specific plus a rollup). Layout, top to bottom: 1. **Header** — `## 🔥 Roasted — PR #: >, file(s)`. Build every field from this actual pass: the real PR number, whether it covers the whole PR or only the delta since the prior review's commit, and how many files this pass reviewed. Never copy the placeholder text below verbatim or leave a stale count from a different pass. 2. **Verdict callout** (always visible) — a GitHub alert, which renders as a colored box: `[!TIP]` (green) for zero issues, `[!WARNING]` (amber) for important/minor issues only, `[!CAUTION]` (red) when anything is critical. 3. **Scoreboard table** (always visible) — counts per severity plus judgment calls. 4. **One collapsed `
` per section** — bold name, topical emoji, and status in the ``. Put the section's checks in a ` ```diff ` block: `+` lines render green (passing check), `-` lines render red (issue), lines starting with a space stay neutral (judgment calls — not enforced). Hard-wrap at ~76 characters and repeat the same prefix on continuation lines; GitHub won't soft-wrap code blocks and an unprefixed continuation loses its color. 5. **`---` then a collapsed "Review info" footer** — commit range, full vs. delta review, files reviewed, standards used. 6. **Hidden marker** `` as the last line, so a later pass can find this skill's prior review and its commit reliably. Keep GitHub alerts and the table at the top level — alerts don't render inside `
`. Every `
` must open and close in a matched pair; count them before posting, since one stray tag breaks the nesting of everything after it. ````markdown ## 🔥 Roasted — PR #: `>, file(s) > [!TIP] > **Clean pass.** Nothing blocking. <[M] judgment call(s) worth a glance.> | 🚨 Critical | ⚠️ Important | 💡 Minor | 🤔 Judgment calls | | :---: | :---: | :---: | :---: | | **[n]** | **[n]** | **[n]** | **[n]** |
🔭 Scope — [✅ Pass / ❌ Issues / 🤔 Judgment call]
```diff + ✅ planned vs. shipped, no gaps ```
📐 Policy compliance — [status]
```diff + ✅ branch name matches branch-policy.md + ✅ commit title/body follow commit-policy.md - ❌ [IMPORTANT] PR body missing Validation section — add what ran ```
🔍 Code review — [status]
```diff + ✅ no secrets in diff 🤔 [JUDGMENT CALL] — see inline comment ```
📎 Unanchored findings — [count]
```diff - ❌ [SEVERITY] — ```
🤖 Prompts for AI agents ```text 1. 2. ```
---
ℹ️ Review info
- **Commits:** ``..`` (`>) - **Files reviewed ():** ``, `` - **Standards:** `context/policies/review-policy.md`, `context/policies/`
```` Omit the `Unanchored findings` block entirely when there are none — don't post an empty collapsed section. Write the finding text in the tone required by `context/policies/writing-guidelines.md`: concise, technical, no marketing language. The emoji, alerts, and color conventions above are this section's own formatting, not a `writing-guidelines.md` requirement, and don't extend to PR titles or descriptions. ## Guardrails - Never edit files, commit, or push as part of this skill. - Never approve, merge, or request-changes the PR unless the user explicitly asks for that decision. - Post one review per pass (one pending review, submitted once); do not open multiple pending reviews or submit partial reviews one comment at a time. - Do not invent policies this repo does not have. If something looks wrong but no policy or visible convention covers it, tag it `[JUDGMENT CALL]` per `context/policies/review-policy.md`, not a severity. - A subagent used for the parallel file-review pass gets read-only tools only — it must not be able to comment, review, commit, or push. Its findings are input to this skill's own ranking and posting, never posted directly. ## Stop Conditions - Stop if there is no open, non-draft pull request for the current branch — say to run `ship` first rather than just "no PR found." - Stop if the GitHub MCP connector and `gh` are both unavailable — report the findings in chat only and say the PR comment could not be posted. - Stop if the connected account lacks permission to comment (e.g. a fork-originated PR) — report this as a permissions issue, not as MCP being down, and share the findings in chat instead. - Stop before posting if the user asked for a private/local review only. - Stop and re-fetch instead of posting if the PR head SHA changed since the diff was fetched; do not post a review against a diff that no longer matches the PR. - Stop if the PR was merged or closed after the review was fetched but before it was posted — report the findings in chat and do not post to a PR that's no longer open. - Stop if a pending review already exists on the PR — report it and ask the user to confirm discarding it (or resolve it on GitHub themselves) before proceeding; never discard it automatically. - If `add_comment_to_pending_review` or `submit_pending` fails after inline comments were already added, do not exit silently — report that a pending review was left partially built on the PR, with the findings in chat, so the user knows it needs manual submission or discarding on GitHub. ## Handoff - Only use the success phrasing below once the post is confirmed (a returned review ID/URL), not just because the API call didn't error. - Unless the user asked for plain output, open with a fresh one-line success phrase in the orc voice, speaking as the Trialmaster from `context/personality.md` (the target repo's copy when it exists, otherwise `${CLAUDE_PLUGIN_ROOT}/context/personality.md`). If they did, open with the plain result instead. - Report the PR number and the finding counts by severity. - If there were zero findings, say so plainly and skip listing severities. - If posting stops or fails, drop the orc voice and state the blocker plainly, then share the findings in chat instead. ## Response Examples Opening lines are samples of the orc voice; write a fresh one each time. Clean review, no findings: ```text 🔥 Hah! Two rounds in the arena and it drew no blood. PR #123: 0 issues found. ``` Review with findings: ```text 🔥 Trial by fire done: three cracks in the armor. Roast the code, never the coder. ✨ PR #124: 3 issues found — 1 critical, 1 important, 1 minor. Posted as a PR review with inline comments plus a summary. ``` Blocked review: ```text ⚠️ Roast is blocked: no open pull request on this branch yet. Run `ship` first, then roast. No comment or review was posted. ```