review-pr

Files (7)

• SKILL.md
• bot-adjudication.md
• orchestration.md
• repos.md
• routine.md
• stack-lifecycle.md
• walkthrough.md

SKILL.md (first lines)

# review-pr

`/babysit-prs` addresses threads on PRs *you authored*. `/phillip` self-reviews *your local diff*.
**`/review-pr` reviews someone else's PR where you are the requested reviewer** and posts the review
to GitHub. The action is **post review comments + a verdict**, not *implement fixes*.

## Input / modes

Treat text accompanying the skill invocation as the input:

| Invocation | Behavior |
|---|---|
| Empty | All open PRs across every Targets repo where the current user is a requested reviewer (and not the author). |
| `<PR#>` | That PR (resolves to `Atllas-Inc/codebase` unless `--repo`; PR#s are ambiguous across repos). |
| `<URL>` | Parse owner/name/number from the GitHub URL (unambiguous). |
| `quick` | Claude-only blind reviewer, auto-selected for trivial diffs at `phillip`'s Mode thresholds. Default = full three-reviewer. |
| `... --draft` | Opt **down**: assemble + report + print the exact payload, **submit nothing**. |
| `... --no-approve` | Opt **down**: cap the verdict at `COMMENT`, never post `APPROVE`. |
| `... --no-live` | Opt **down**: skip the Tier-3 dynamic walkthrough even on a UI PR. |
| `... --no-resolve-bots` | Opt **down**: still validate bot comments, but **resolve none**. Reply only. |

### Targets (default repos)

**Read [../shared/repos.md](../shared/repos.md) at Phase 0** for the repo set, the clone paths, the
default branches, and the verify commands. **Read [repos.md](repos.md)** for what each depth means
for the verdict.

**Default reviewer = the authenticated login** (`ME`), read through `GH_TRANSPORT` (Phase 0).

---

## Core safety model (do not weaken)

This skill posts to **other people's** PRs. Five invariants:

1. **Autonomous post by default, quality-gated.** It submits the review without a confirm step.
   `--draft` opts down to assemble-and-print-only.
2. **Only verified findings reach GitHub.** A finding posts inline **only** if it was traced against
   the real code path **this session**. Unverified, "couldn't check", and low-confidence findings are
   **never posted**: they go to the local report's **NEEDS YOUR EYES** section. Nits (LOW) are held
   to the report as well. Only verified HIGH+MEDIUM post inline.
3. **Conservative verdict** (table below). `REQUEST_CHANGES` fires only on a verified HIGH.
   `APPROVE` fires only on a clean **fully-verified** pass, and never with `--no-approve`. Every
   other case is `COMMENT`.
4. **Skip self-authored PRs** (`author == ME`) and PRs already reviewed at the current head SHA
   (idempotency, Phase 2).
5. **Never review a draft PR.** A GitHub draft (`isDraft == true`) is work-in-progress and is
   **excluded end-to-end**: filtered at discovery (`select(.isDraft!=true)` / `draft:false`), skipped
   with a note when named explicitly ("PR #N is a draft, skipped. Re-request review when it is
   marked ready."), and **re-checked immediately before any post**. A PR flipped to draft mid-run is
   abandoned, never posted. Review **only open, ready-for-review** PRs.

### Severity → verdict

| Postable findings | `event` |
|---|---|
| ≥1 verified HIGH | `REQUEST_CHANGES` (inline every HIGH + MEDIUM) |
| verified MEDIUM only (no HIGH) | `COMMENT` |
| nothing verified / clean, **FULL** verify depth | `APPROVE` (default); `--no-approve` caps at `COMMENT` |
| nothing verified / clean, **reduced** depth (no clone / compile-only / no dynamic) | `COMMENT` ("no blocking issues; not fully verified"). **Never** auto-APPROVE. |
| aicc-queues HIGH resting on **runtime behavior** with **compile-only** evidence | downgrade to `COMMENT` + "compile-only evidence, runtime unverified. Please confirm." Never block on a compile alone. |

**Reviewer count gates `APPROVE` too.** A run with fewer than two reviewers caps at `COMMENT`,
whatever the verify depth. That covers `quick` mode (one blind Claude reviewer) and any run where
Codex was missing (Tier 2b). State which reviewers ran in the review body.

---

## Writing style

Copied verbatim from `~/.claude/CLAUDE.md`, which a headless run never loads.
Binding on every inline comment, review body, verdict, bot-thread reply, and report this
skill writes, orchestrator and sub-agents alike.

When you write technical text (documentation, READMEs, runbooks, procedures, error messages, release notes, reports), write plain English in the spirit of ASD-STE100 Simplified Technical English, so that a smart reader outside the field understands it on one read. Obey these rules:

CLASSIFY FIRST. Procedural text tells the reader what to do: imperative mood, maximum 20 words per sentence, one instruction per sentence. Descriptive text explains: simple tenses, maximum 25 words per sentence, one topic per paragraph, maximum six sentences per paragraph. Never mix the two in one passage.

PLAIN WORDS, for replies and for explanations written for readers outside the field. Use the common word when one exists ("use", not "utilize"). Define a concept term at its first use, in under ten words, at most one per sentence: "idempotent (safe to run twice)". Do not define product names, standard names (Postgres, S3, HTTP), or the tool the document is about. Address the reader as "you". Lead with the point. Procedures and reference documents follow the rules above alone.

VERBS. Use only: infinitive, imperative, simple present, simple past, simple future, past participle as adjective. No present perfect ("has completed" → "completed"). No "-ing" verb forms ("making it easy" → new sentence). Active voice; passive only in descriptions when the agent is unknown. Approved modals: can, will, must. Banned: should, would, may, might, could. For "should": write "must" if required, delete if optional.

SENTENCES. Keep complete grammar: no contractions, keep articles, keep "that" ("make sure that the file exists"). Put conditions before commands, with a comma: "If the test fails, read the log." No semicolons: write two sentences. No em-dashes: an em-dash hides the logic between two statements. Name the relation ("because", "but", "for example", "that is") or write two sentences. Use a vertical list for more than two items or steps.

WORDS. One word, one meaning, for the whole document: use "make sure that" for check/verify/confirm, and "configuration" for config/settings. Noun chains of maximum three words. Break longer ones with prepositions ("the timeout value for the connection pool"). Delete words that carry no fact: simply, seamlessly, robust, powerful, comprehensive, leverage, delve, pivotal, "in order to", "it is worth noting". Do not open or close with chat filler: "in conclusion", "in summary", "let's dive in", "that being said", "I hope this helps".

AVOID THE AI DRIFTS. Guard against these by direction: inflated significance ("crucial", "a testament to"), "not just X, it is Y" reframes, decorative triplets, vague attribution ("studies show"), "it is important to note" asides, and formatting habits (no emoji as structure, no boldface as decoration). State the fact. The fact carries itself. Replace: utilize → use, prior to → before, in the event that → if, e.g. → for example. American spelling.

WARNINGS. Command or condition first, then the risk: "Do not run this against production. The command deletes rows."

NEVER TOUCH. Code blocks, identifiers, CLI commands, file paths, quoted error messages, product names. Each counts as one word toward sentence limits. Facts too: when the source does not give a number or a cause, keep the general statement — do not invent specifics.

SELF-CHECK before returning: scan for contractions, "has been", "should", ", making", semicolons, em-dashes, and the deleted-word list above. Count words in your three longest sentences and split any over the limit. Collapse synonym rotation.

REPLIES TO THE USER. The same rules apply to the chat reply, at the descriptive limits (25 words per sentence, simple tenses, active voice, no contractions). Start with the answer or the result. If a concept term is necessary, define it in a few words. Do not restate the request. Keep the whole reply to 5 sentences or fewer, code and lists excluded. Do not add openers ("Certainly", "You're absolutely right") or closers ("I hope this helps"). Do not shorten quoted errors, security warnings, or confirmations before a destructive action.

STRICT MODE. If the user names STE, ASD-STE100, or compliance, also apply the STE dictionary to the document: "make sure that" for check/verify/confirm, "operate" for run, "do" for execute, "show" for display, "but" for however, "because" for since. Say once that no tool guarantees compliance and that the official dictionary is free at asd-ste100.org.

Do not apply these rules to marketing copy or brand writing.

In any markdown that will be rendered (chat responses, PR/issue bodies, reports, docs),
escape delimiter characters used literally, since two of them in one paragraph silently
corrupt everything between: `\~` for "approximately" tildes (`~...~` is strikethrough in
GFM) and `\$` for dollar amounts (`$...$` is inline LaTeX math in GitHub and VSCode
preview). Literal `~`/`$` in code stay inside backticks instead.

---

## Phase 0: Preflight + capability detection

Locate the directories containing the loaded `review-pr`, `phillip`, `claude`, and
`ui-walkthrough` skills. Call them `REVIEW_PR_DIR`, `PHILLIP_DIR`, `CLAUDE_SKILL_DIR`, and
`UI_WALKTHROUGH_DIR`. Use those directories for every skill file, rubric, reference, and script
path below.

```bash
# Probe a REPO call. `gh api user` passes while repo calls 403; see ../shared/github-transport.md.
if gh api "repos/$OWNER/$NAME" --jq .id >/dev/null 2>&1; then GH_TRANSPORT=cli; else GH_TRANSPORT=mcp; fi
SCRATCH=/private/tmp/review-pr; mkdir -p "$SCRATCH"    # NOT $TMPDIR, see below

From ptrandev/agent-skills, MIT.

More from ptrandev/agent-skills