From 563a63d7ff9eca15e85b8833c2f6dfaaa20d56b4 Mon Sep 17 00:00:00 2001 From: Joseph Tooby-Smith <72603918+jstoobysmith@users.noreply.github.com> Date: Mon, 16 Nov 2026 12:12:33 +0000 Subject: [PATCH 1/2] feat: Add guided review skill --- .agents/skills/guided-review/SKILL.md | 121 ++++++++++++++++++++++++++ .claude/skills/guided-review/SKILL.md | 8 ++ 2 files changed, 129 insertions(+) create mode 100644 .agents/skills/guided-review/SKILL.md create mode 100644 .claude/skills/guided-review/SKILL.md diff --git a/.agents/skills/guided-review/SKILL.md b/.agents/skills/guided-review/SKILL.md new file mode 100644 index 0000000000..452d9b384f --- /dev/null +++ b/.agents/skills/guided-review/SKILL.md @@ -0,0 +1,121 @@ +--- + +name: guided-review description: Walks a reviewer through a Physlib PR step by step, whether it changes Lean code or infrastructure such as scripts, linters, CI, documentation or skills, pointing out where to look so they can write their own comments. Use it when someone wants help reviewing a PR, even if they only say "help me review PR 1234" or "take me through this PR". + +--- + +# Guided PR review + +This skill guides a reviewer, newcomer or expert, through a Physlib PR in a fixed order. They give you a PR number. At each step you show them where to look and what is worth their attention; they make every judgment and write every comment themselves. Let the reviewer know that anyone is welcome to review, and that a review covering only some of these steps is still valuable, so they can stop whenever they like. + +## Ground rules + +- Do not write review comments, draft or final. Guide the reviewer to what to look at and leave the wording to them. All communication with PR authors must be human, as `AI-POLICY.md` requires. +- Everything is the reviewer's call. Point things out and ask questions; do not give verdicts. +- Stay on the reviewer's machine. Never post, push, comment or approve anything on GitHub. +- Do not build the project; this review does not need it, and it takes hours. + +## Step 1: Get the PR + +The goal is to have the PR's description and changes in front of you. If the request has no PR number, which we call ``, ask the reviewer for one. + +Read the description and the diff: + +```bash +gh pr view --repo leanprover-community/physlib --json title,body,author,files +``` + +```bash +gh pr diff --repo leanprover-community/physlib +``` + +If the diff is not enough to follow the code, check the PR out locally as a fallback, in a scratch directory we call `$WORK`: + +```bash +git fetch https://github.com/leanprover-community/physlib.git "pull//head" +git worktree add --detach "$WORK/pr-" FETCH_HEAD +``` + +Go through the steps below one at a time, pausing after each for the reviewer to think and make notes. At each step, present what you found clearly: a short summary first, then the details, grouped in a way that is easy to scan (for example, files by folder). Flag what seems worth a look and leave every decision to the reviewer. + +From the changed files, decide whether the PR is a Lean code PR or an infrastructure PR (scripts, linters, CI, documentation such as the Contribution Handbook, and skills), and tell the reviewer which. Use Part A for Lean code and Part B for infrastructure. A PR is rarely both; if it is, point this out to the reviewer and ask which part to follow. + +## Part A: Lean code (Steps 2 to 11) + +Use these steps for changes to Lean files. + +### Step 2: Read the description + +The goal is a description that is concise and readable by a human. Show the reviewer the description and point out anything long, vague or hard to follow, since this is the first thing worth raising. + +### Step 3: Look at the changed files as a whole + +The goal is to see whether the files changed, taken together, point to one coherent PR. List them for the reviewer and note any that seem out of place. + +### Step 4: Read the module documentation and API maps + +The goal is documentation whose physics is correct and which a reader can understand. Take the reviewer through new or changed module documentation and API map additions. Flag places where the text might rely on background reading that is not there. + +### Step 5: Read the docstrings of new results + +The goal is that each new result says clearly what it does. For each one, help the reviewer check that its docstring is concise and understandable, makes plain what the lemma is doing, and fits the overall story of the PR. + +### Step 6: Check the references + +The goal is to give the reviewer every reference so they can check it. List each one added, together with what it supports in the file: the definition, result or passage it is cited for. Do not judge them yourself: `AI-POLICY.md` says only a human can verify references. + +### Step 7: Look at the shape of each Lean file + +The goal is files built around the key data structure for their area of physics. For each file, help the reviewer see whether a definition comes first and the later results depend on it, and whether it uses the established data structures of that area rather than inventing its own. + +### Step 8: Look at the types and connections of the lemmas + +The goal is results that use the right structures and fit together. Point out where a lemma might use a general type in place of the proper one, for example `ℝ` where `Time` belongs, and where results seem disconnected or inconsistent. Also flag any lemma that does not seem to belong to this API, or that looks as if it belongs in another file. + +### Step 9: Check where each lemma sits + +The goal is each lemma in the right section of its file. Show the reviewer the file's sections and where each new lemma landed. + +### Step 10: Check the names + +The goal is lemma and definition names that are easy to understand and sit in the right namespace. Go through the new names with the reviewer and flag any that are unclear or seem to be in the wrong namespace. + +### Step 11: Read the proofs + +The goal is proofs that are concise, clear, sensible and easy to follow. Take the reviewer through each proof and point out any that are long or hard to follow. + +## Part B: Infrastructure (Steps 12 to 17) + +Use these steps for changes to scripts, linters, CI, documentation such as the Contribution Handbook, and skills. + +### Step 12: Ask whether the change is needed + +The goal is an infrastructure change that earns its place. Help the reviewer see whether it fixes a real problem, and whether something already in the repository does the same job. + +### Step 13: Check it reads clearly at a broad level + +The goal is a change a human can read and understand. Help the reviewer see whether it is clear what role each added file plays. + +### Step 14: Check the overall design + +The goal is a design the reviewer could explain. Help them see whether the overall pattern the change follows is clear, so they could say how the whole thing works. + +### Step 15: Check each piece + +The goal is that each added piece, such as a function, script or section, makes clear what it does. Go through them with the reviewer and flag any that are unclear. + +### Step 16: Check it works + +The goal is a change that does what it is meant to do. Where there is something to run, such as a script or linter, offer to test it, say what the test would show, and run it only once the reviewer agrees, since this runs code from the PR on their machine. Either way, explain how the reviewer could test it themselves. For documentation this step usually does not apply. + +### Step 17: Check related documentation + +The goal is documentation that stays in step with the change. Flag any documentation that depends on or relates to the change and has not been updated. + +## Step 18: Hand back to the reviewer + +The goal is a reviewer ready to write their own review. Remind them of the places they marked along the way, without writing comments for them. Ask how they would like to give their review, then guide them in doing it: for example, how to leave a comment on a specific line of a PR on GitHub, and how to add a suggested change. Writing and posting the review is theirs. If you checked the PR out, remove the worktree: + +```bash +git worktree remove --force "$WORK/pr-" +``` diff --git a/.claude/skills/guided-review/SKILL.md b/.claude/skills/guided-review/SKILL.md new file mode 100644 index 0000000000..956502448e --- /dev/null +++ b/.claude/skills/guided-review/SKILL.md @@ -0,0 +1,8 @@ +--- + +name: guided-review +description: Walks a reviewer through a Physlib PR step by step, whether it changes Lean code or infrastructure such as scripts, linters, CI, documentation or skills, pointing out where to look so they can write their own comments. Use it when someone wants help reviewing a PR, even if they only say "help me review PR 1234" or "take me through this PR". argument-hint: "\[PR number\]" + +--- + +Read `.agents/skills/guided-review/SKILL.md` and follow it. The request is: $ARGUMENTS From 61e16585d12f1ea23dbb2cb989512b0e2cc487c3 Mon Sep 17 00:00:00 2001 From: Joseph Tooby-Smith <72603918+jstoobysmith@users.noreply.github.com> Date: Mon, 16 Nov 2026 15:44:31 +0000 Subject: [PATCH 2/2] feat: Fix overall structure --- .agents/skills/guided-review/SKILL.md | 33 ++++++++++++++------------- 1 file changed, 17 insertions(+), 16 deletions(-) diff --git a/.agents/skills/guided-review/SKILL.md b/.agents/skills/guided-review/SKILL.md index 452d9b384f..1b1e806b7c 100644 --- a/.agents/skills/guided-review/SKILL.md +++ b/.agents/skills/guided-review/SKILL.md @@ -1,6 +1,7 @@ --- -name: guided-review description: Walks a reviewer through a Physlib PR step by step, whether it changes Lean code or infrastructure such as scripts, linters, CI, documentation or skills, pointing out where to look so they can write their own comments. Use it when someone wants help reviewing a PR, even if they only say "help me review PR 1234" or "take me through this PR". +name: guided-review +description: Walks a reviewer through a Physlib PR step by step, whether it changes Lean code or infrastructure such as scripts, linters, CI, documentation or skills, pointing out where to look so they can write their own comments. Use it when someone wants help reviewing a PR, even if they only say "help me review PR 1234" or "take me through this PR". --- @@ -10,7 +11,7 @@ This skill guides a reviewer, newcomer or expert, through a Physlib PR in a fixe ## Ground rules -- Do not write review comments, draft or final. Guide the reviewer to what to look at and leave the wording to them. All communication with PR authors must be human, as `AI-POLICY.md` requires. +- Do not write, draft or edit review comments. Guide the reviewer to what to look at and leave the wording to them. All communication with PR authors must be human, as `AI-POLICY.md` requires. - Everything is the reviewer's call. Point things out and ask questions; do not give verdicts. - Stay on the reviewer's machine. Never post, push, comment or approve anything on GitHub. - Do not build the project; this review does not need it, and it takes hours. @@ -56,26 +57,26 @@ The goal is to see whether the files changed, taken together, point to one coher The goal is documentation whose physics is correct and which a reader can understand. Take the reviewer through new or changed module documentation and API map additions. Flag places where the text might rely on background reading that is not there. -### Step 5: Read the docstrings of new results - -The goal is that each new result says clearly what it does. For each one, help the reviewer check that its docstring is concise and understandable, makes plain what the lemma is doing, and fits the overall story of the PR. - -### Step 6: Check the references +### Step 5: Check the references The goal is to give the reviewer every reference so they can check it. List each one added, together with what it supports in the file: the definition, result or passage it is cited for. Do not judge them yourself: `AI-POLICY.md` says only a human can verify references. -### Step 7: Look at the shape of each Lean file +### Step 6: Look at the shape of each Lean file The goal is files built around the key data structure for their area of physics. For each file, help the reviewer see whether a definition comes first and the later results depend on it, and whether it uses the established data structures of that area rather than inventing its own. -### Step 8: Look at the types and connections of the lemmas +### Step 7: Look at the types and connections of the lemmas The goal is results that use the right structures and fit together. Point out where a lemma might use a general type in place of the proper one, for example `ℝ` where `Time` belongs, and where results seem disconnected or inconsistent. Also flag any lemma that does not seem to belong to this API, or that looks as if it belongs in another file. -### Step 9: Check where each lemma sits +### Step 8: Check where each lemma sits The goal is each lemma in the right section of its file. Show the reviewer the file's sections and where each new lemma landed. +### Step 9: Read the docstrings of new results + +The goal is that each new result says clearly what it does. For each one, help the reviewer check that its docstring is concise and understandable, makes plain what the lemma is doing, and fits the overall story of the PR. + ### Step 10: Check the names The goal is lemma and definition names that are easy to understand and sit in the right namespace. Go through the new names with the reviewer and flag any that are unclear or seem to be in the wrong namespace. @@ -100,17 +101,17 @@ The goal is a change a human can read and understand. Help the reviewer see whet The goal is a design the reviewer could explain. Help them see whether the overall pattern the change follows is clear, so they could say how the whole thing works. -### Step 15: Check each piece +### Step 15: Check related documentation -The goal is that each added piece, such as a function, script or section, makes clear what it does. Go through them with the reviewer and flag any that are unclear. +The goal is documentation that stays in step with the change. Flag any documentation that depends on or relates to the change and has not been updated. -### Step 16: Check it works +### Step 16: Check each piece -The goal is a change that does what it is meant to do. Where there is something to run, such as a script or linter, offer to test it, say what the test would show, and run it only once the reviewer agrees, since this runs code from the PR on their machine. Either way, explain how the reviewer could test it themselves. For documentation this step usually does not apply. +The goal is that each added piece, such as a function, script or section, makes clear what it does. Go through them with the reviewer and flag any that are unclear. -### Step 17: Check related documentation +### Step 17: Check it works -The goal is documentation that stays in step with the change. Flag any documentation that depends on or relates to the change and has not been updated. +The goal is a change that does what it is meant to do. Where there is something to run, such as a script or linter, offer to test it, say what the test would show, and run it only once the reviewer agrees, since this runs code from the PR on their machine. Either way, explain how the reviewer could test it themselves. For documentation this step usually does not apply. ## Step 18: Hand back to the reviewer