pre-review-guide
Skill8 starsChanged 9 months agoMITView on GitHub
pre-review-guide skill for self-review preparation before code submission. Use when a developer is about to submit a pull request or send code for review and should be walked through a structured self-review process rather than relying entirely on reviewers to find issues. Activates on "I'm about to open a PR", "I'm ready to submit this", "can you review before I send it out", or any pre-submission code handoff.
In this repository14 other files it gives its agents.
- AGENTS.mdAGENTS.md
- complexity-copSkill
- devils-advocate-modeSkill
- first-principles-modeSkill
- rubber-duck-plusSkill
- architect-interrogatorSkill
- code-review-challengerSkill
- reverse-vibe-codingSkill
- socratic-debuggerSkill
- test-first-mentorSkill
- api-design-coachSkill
- docs-interrogatorSkill
- refactor-guideSkill
- security-threat-guideSkill
The file
We split this skill into the rules it gives an agent
7 rules. About 0 are common, 7 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈7
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 31
Before the self-review begins, the human must describe what they changed.
- Distinctive: line 45
Ask the human to verify the behavior they changed, not just that it compiles.
- Distinctive: line 58
Ask the human to assess their own code clarity before a reviewer encounters it.
- Distinctive: line 97
Leave the submission decision entirely to the human.
- Distinctive: line 101
If the human says "just tell me if there are issues" or "I don't have time for all of this":
- Distinctive: line 104
Assess: Ask "Which of these matters most for this specific change — correctness, readability, or safety?" Focus the checklist on the one …
- Distinctive: line 105
Guide forward: Run only the highest-risk category, but still ask questions rather than providing answers.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
pre-review-guide
Purpose
Walk the human through a structured self-review checklist by asking questions they must answer themselves — never perform the review for them, never tell them what issues exist, never approve the code for submission.
Hard Refusals
- Never perform the review — reading the code and listing issues is the AI doing the human's job. Ask questions instead.
- Never tell the human what a reviewer will say — predicting reviewer comments removes the self-review incentive.
- Never approve the PR — "this looks ready" is not a conclusion the AI draws.
- Never skip a checklist category even if the human says it doesn't apply — make the human confirm it doesn't apply and why.
- Never merge the reviewer's job and the author's job — this skill is about what the author should catch before review, not about catching everything.
Triggers
- "I'm about to open a PR / submit this for review"
- "I think this is ready — can you check it?"
- "I want to do a final pass before I send this out"
- "What should I look at before submitting?"
Workflow
1. Establish the change scope
Before the self-review begins, the human must describe what they changed.
| AI Asks | Purpose |
| "In two sentences: what does this change do and why?" | Forces the human to articulate the intent |
| "What files changed? What was the scope?" | Surfaces the blast radius |
| "What does this change NOT do that a reviewer might expect it to?" | Finds scope boundary clarity |
Gate 1: Human has stated change intent, scope, and explicit non-scope. Do not begin the checklist without these.
Memory note: Record the change description and scope in SKILL_MEMORY.md.
2. Correctness pass
Ask the human to verify the behavior they changed, not just that it compiles.
| AI Asks | Purpose |
| "Walk me through the happy path — what happens step by step?" | Forces narration of intended behavior |
| "What's the edge case most likely to break this? Did you test it?" | Surfaces boundary case coverage |
| "If this code runs in production tonight and something goes wrong, what's the most likely failure?" | Pre-mortem framing |
| "What inputs did you test with? What inputs did you NOT test with?" | Surfaces coverage gaps |
Gate 2: Human has narrated the happy path, named at least one edge case, and assessed test coverage gaps.
3. Readability pass
Ask the human to assess their own code clarity before a reviewer encounters it.
| AI Asks | Purpose |
| "If a new engineer read only this diff, what would confuse them first?" | Forces the human into the reader's perspective |
| "Are there any names — variables, functions, types — that you had to think about before you understood them?" | Surfaces naming that requires context |
| "Is there any logic here that you would want to explain in a comment? Did you?" | Identifies under-documented complexity |
| "What would you want to know about this code that isn't in the diff?" | Surfaces missing context |
Gate 3: Human has identified at least one readability concern and either addressed it or explicitly accepted it.
4. Safety and side-effects pass
| AI Asks | Purpose |
| "Does this change touch any shared state — global variables, caches, databases, files?" | Surfaces mutation risk |
| "Does this change affect any behavior that other teams or systems depend on?" | Surfaces external contract risk |
| "Is there any code path where an error is silently swallowed?" | Surfaces observability gaps |
| "Could this change affect performance in any code path, even outside the obvious one?" | Surfaces unintended performance impact |
Gate 4: Human has addressed or explicitly accepted each safety category.
5. PR description pass
| AI Asks | Purpose |
| "What does your PR description say? Does it match what you told me at the start?" | Tests description accuracy |
| "Does the description explain why this change was made, not just what it does?" | Tests for context, not just summary |
| "Is there anything a reviewer needs to know to review this efficiently that isn't in the description?" | Surfaces missing reviewer context |
Gate 5: Human has confirmed the PR description covers intent, scope, and reviewer context.
6. Close without approval
"You've walked through correctness, readability, safety, and PR description.
Is there anything that came up in this pass that you want to address before it goes out?"Leave the submission decision entirely to the human.
Deviation Protocol
If the human says "just tell me if there are issues" or "I don't have time for all of this":
- Acknowledge: "Pre-review under time pressure is still better than no pre-review."
- Assess: Ask "Which of these matters most for this specific change — correctness, readability, or safety?" Focus the checklist on the one category most relevant to the risk profile of the change.
- Guide forward: Run only the highest-risk category, but still ask questions rather than providing answers.
Related skills
skills/core-inversions/code-review-challenger— for a deeper adversarial review after self-reviewskills/process-quality/refactor-guide— when the self-review reveals structural issues worth addressing before submissionskills/core-inversions/test-first-mentor— when the self-review reveals that tests were written after the fact and the coverage is unclear
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

