reviewing
Skill56 starsChanged 8 months agoMITView on GitHub
Claude-on-Claude code review protocol — reviews implementation against spec requirements and code quality standards
3 other projects use a version of this.
Adopted by
Most recently taken up by
- fynnhaupt/skillstheir own version, first seen Nov 1, 2026
- Tom-Willemsen/claude-skillstheir own version, first seen Oct 20, 2026
- jukanntenn/harness-deepseek-harnesstheir own version, first seen Oct 7, 2026
Other versions3 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 3
- jukanntenn/harness-deepseek-harness★ 2same name
- fynnhaupt/skills★ 1same name
- Tom-Willemsen/claude-skills★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository12 other files it gives its agents.
- AGENTS.mdAGENTS.md
- docs/agents.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- backpropagationSkill
- brainstormingSkill
- caveman-internalSkill
- collaboratingSkill
- design-systemSkill
- executingSkill
- graphify-integrationSkill
- karpathy-guardrailsSkill
- planningSkill
The file
We split this skill into the rules it gives an agent
6 rules. About 0 are common, 4 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 26
Read the actual code: Do NOT trust the implementer's report or summary.
- Distinctive: line 95
IMPORTANT: Should fix. Missing edge case handling, questionable design pattern, weak test assertions, over-engineering.
- Distinctive: line 102
Max 3 review iterations per task: After 3 rounds of review-fix-review, accept the code with warnings and move on.
- Distinctive: line 104
CRITICAL issues must be fixed: If a CRITICAL issue remains after 3 iterations, the task is flagged as blocked and escalated to the user.
- Very specific: line 135
If issues are found, the forge-executor is re-dispatched with the issue list to fix them.
- Very specific: line 136
After fixes, forge-reviewer is dispatched again for the next iteration.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 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
Reviewing Skill
This skill defines the two-pass review workflow that validates implementation quality before a task is marked complete. It is dispatched after a task is implemented and tests pass (at depth >= standard).
Inputs
You will receive:
- Implemented code: The files created or modified by the executor for this task
- Spec requirements: The R-numbered requirements and acceptance criteria this task must satisfy
- Task definition: From the frontier file, including task name, dependencies, and repo
- Review iteration: Which review pass this is (1, 2, or 3)
Two-Pass Review Workflow
Pass 1: Spec Compliance Review (mandatory for depth >= standard)
This is the primary review pass. It verifies that the implementation actually satisfies the spec.
Procedure:
- Read the actual code. Do NOT trust the implementer's report or summary. Open every file that was created or modified and read it.
- List every acceptance criterion from the spec requirements assigned to this task.
- Check each criterion against the code:
- Is there code that implements this criterion?
- Does the implementation match what the criterion specifies (not just approximate it)?
- Is the criterion fully satisfied, or only partially?
- Flag missing implementations — acceptance criteria with no corresponding code.
- Flag extra features — code that goes beyond what the spec requires. Over-engineering wastes tokens and introduces unnecessary complexity. If the spec says "return 201 with {id, email}", the code should not also return
created_at,updated_at, androleunless the spec asks for them. - Flag misunderstandings — code that implements something different from what the criterion describes. Example: spec says "hash with bcrypt (min 12 rounds)" but code uses SHA-256.
Output for Pass 1:
## Spec Compliance
STATUS: PASS | ISSUES
CHECKED CRITERIA:
- [x] R001/AC1: POST /auth/register accepts {email, password} — implemented in src/controllers/auth.ts:45
- [ ] R001/AC2: Password hashed with bcrypt (min 12 rounds) — MISSING, no hashing found
- [x] R001/AC3: Returns 201 with JWT + refresh token — implemented in src/controllers/auth.ts:67
ISSUES (if any):
- [CRITICAL] src/controllers/auth.ts — R001/AC2: No password hashing implemented. Raw password stored directly.
- [IMPORTANT] src/controllers/auth.ts:67 — Returns extra fields (created_at, role) not in spec. Over-engineering.Pass 2: Code Quality Review (follows spec compliance)
This pass reviews the quality of the implementation itself. Only run this if Pass 1 does not have CRITICAL issues (fix those first).
Check each of these areas:
- Naming clarity — Are variables, functions, and files named clearly? Can a reader understand what they do without reading the implementation?
- Design patterns — Does the code follow the patterns established in the codebase? Does it match the conventions from the repo's CLAUDE.md?
- Test quality — Do tests actually assert meaningful behavior? Are assertions specific (not just "test passes" or "no error thrown")? Do tests cover the acceptance criteria?
- Error handling — Are errors handled appropriately? Are error messages helpful? Are edge cases covered (null, empty, boundary values)?
- Security — No SQL/NoSQL injection vectors. No hardcoded secrets, API keys, or passwords. No unsafe patterns (eval, innerHTML with user input, unsanitized query params).
- Maintainability — Is the code reasonably structured? Would another developer understand it? Are there obvious code smells (god functions, deep nesting, copy-paste duplication)?
Output for Pass 2:
## Code Quality
STATUS: PASS | ISSUES
ISSUES (if any):
- [IMPORTANT] src/services/auth.ts:23 — Missing error handling for database connection failure. Will crash with unhandled promise rejection.
- [MINOR] src/controllers/auth.ts:12 — Variable `d` should be named `userData` or similar for clarity.
- [MINOR] src/tests/auth.test.ts:45 — Test "should register user" only asserts status code, not response body. Weak assertion.Combined Review Output
The final review output combines both passes:
STATUS: PASS | ISSUES
ISSUES (if any):
- [CRITICAL] file:line — description
- [IMPORTANT] file:line — description
- [MINOR] file:line — descriptionSeverity Levels
- CRITICAL: Blocks completion. Spec requirement not met, security vulnerability, broken functionality. Must be fixed before the task can proceed.
- IMPORTANT: Should fix. Missing edge case handling, questionable design pattern, weak test assertions, over-engineering. Fix unless review budget is exhausted.
- MINOR: Nice to fix. Naming improvements, minor redundancy, style preferences. Accept and move on if review budget is low.
Review Loop Rules
The review loop is bounded by circuit breakers to prevent infinite cycling:
- Max 3 review iterations per task. After 3 rounds of review-fix-review, accept the code with warnings and move on. Log unresolved issues in the execution summary.
- Same implementer fixes issues. The executor that wrote the code fixes the review issues. This preserves context and avoids re-reading the entire implementation.
- CRITICAL issues must be fixed. If a CRITICAL issue remains after 3 iterations, the task is flagged as blocked and escalated to the user.
- IMPORTANT issues should be fixed. Fix in iterations 1-2. In iteration 3, accept remaining IMPORTANT issues with warnings.
- MINOR issues are optional. Fix if budget allows. In iteration 2+, skip all MINOR issues and focus on CRITICAL and IMPORTANT only.
- Shrinking scope per iteration. Each iteration should address fewer issues than the previous one. If the issue count is not decreasing, something is wrong — flag for human review.
Iteration Behavior
| Iteration | Focus | Accept Condition |
| 1 | All severity levels | PASS = no CRITICAL or IMPORTANT issues |
| 2 | CRITICAL + IMPORTANT only | PASS = no CRITICAL issues, IMPORTANT count decreased |
| 3 (final) | CRITICAL only | Accept with warnings for any remaining IMPORTANT/MINOR |
After Review Completes
- PASS: Task is marked as reviewed and clean. Proceed to commit and advance.
- ISSUES resolved in loop: Task is marked as reviewed after fixes. Proceed to commit.
- ISSUES after 3 iterations: Task is marked as reviewed with warnings. Log unresolved issues. Proceed to next task.
What the Reviewer Does NOT Check
- Code style — trust linters and formatters. Do not flag indentation, semicolons, or bracket placement.
- Performance optimization — unless the spec explicitly requires specific performance characteristics.
- Documentation — unless the spec explicitly requires documentation.
- Refactoring opportunities in unrelated code — stay focused on the task's scope.
Dispatching Agents
This skill orchestrates the review by dispatching agents:
- forge-reviewer — Dispatched to perform the two-pass review. Receives the code, spec, and iteration number. Returns the combined review output.
- If issues are found, the forge-executor is re-dispatched with the issue list to fix them.
- After fixes, forge-reviewer is dispatched again for the next iteration.
- This loop continues until PASS or iteration 3 is reached.
The stop hook manages this loop via the state machine. When state is "tests passing + not reviewed", it feeds the review prompt. When state is "review issues + fix attempts < 3", it feeds the fix prompt.
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.

