clean-code-review

Reviews code diffs with severity-ranked, evidence-based comments on behavior, tests, and complexity.

1|1|Updated Jul 6, 2026
One-click install
npx skills add https://github.com/gabesan21/project-of-projects --skill clean-code-review-gabesan21
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: clean-code-review
Source: https://github.com/gabesan21/project-of-projects/tree/main/.agents/skills/clean-code-review
Command: npx skills add https://github.com/gabesan21/project-of-projects --skill clean-code-review-gabesan21

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Code reviews often degrade into subjective style debates or perfection gates that block healthy changes. This Skill provides a structured reading script that produces evidence-based review comments with clear severity levels, so reviewers approve changes that improve code health without policing aesthetics. ## Core Features & Use Cases - Ordered Verification Script: Reads goal, contract, and tests before the diff, then verifies behavior, tests, complexity, naming, and documentation in priority order. - Severity Classification: Tags every comment as blocking, suggestion, or nit, each carrying a snippet, impact, and reason. - Explicit Decision Rules: Approves health-improving changes, requires trackable follow-ups for deferred debt, and sends work back only on blocking criteria. - Use Case: When reviewing a pull request in a PoP kanban workflow (task 005), run this script to produce a structured verdict citing violated criteria and evidence instead of opinion. ## Quick Start Review the current diff using the clean-code-review script and report each finding with its severity, evidence, and a final approve or send-back decision.

Frequently Asked Questions about clean-code-review

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I review a code diff with severity levels?▼

Read the goal, contract, and tests first, then the diff in execution order. Classify each comment as blocking, suggestion, or nit, and attach the relevant snippet, its impact, and a concrete reason rather than a style preference.

What makes a code review comment blocking versus a suggestion?▼

A comment is blocking when it involves correctness, risk, contract breakage, or a missing test for new behavior. Suggestions cover justifiable readability or cohesion improvements, and nits are non-blocking preferences that never hold the change.

Should reviewers enforce code style during review?▼

No. Automatable style belongs to the project's formatter and linter, not the reviewer. The review confirms automated checks ran clean and focuses on behavior, tests, complexity, and naming instead.

When should a code review send a change back instead of approving?▼

Send back only over a blocking item, citing the violated criterion and the evidence. Approve changes that improve overall code health even if imperfect, and record deferred debt as an explicit, trackable follow-up.

What are the limitations of this review approach?▼

The scope is limited to the diff and what it touches, not a full repository audit. It imposes no numeric limits or OO patterns, and it applies only to code projects with declared verification commands.