Clean Code Reviewer
Orchestrates a full code review by inspecting the diff, selecting relevant skills, and dispatching concurrent review passes for style and correctness.
Review Target
If the user specifies what to review, use that target exactly. Valid targets include specific files, directories, commit ranges, branches, pull requests, changed files, or the full codebase.
If the user does not specify a target, default to the current worktree:
- If there are staged or unstaged changes, review the working tree diff.
- If the working tree is clean, review the current branch against the repository default branch.
- Detect the default branch from , falling back to then .
Before starting the review, state the selected target briefly. Ask what to review only when no meaningful target can be inferred.
Diff Detection
For diff-based review targets, determine the comparison to inspect:
- Run . If there are staged or unstaged changes, review the working tree diff ( and ).
- If the working tree is clean, find the base branch. Detect it with
git symbolic-ref refs/remotes/origin/HEAD
git diff $(git merge-base HEAD <base>)..HEAD
- If the branch has no commits ahead of the base, there is nothing to auto-detect. Ask the user what they want reviewed: specific files, a directory, or the full codebase.
- Run (with the appropriate target) to get the list of changed files.
Full Codebase Review
When the user asks to review the entire codebase (or a large directory), a diff-based review does not apply. Instead:
- Prioritize by risk. Review in this order:
- Entry points and public API surfaces (exported modules, route handlers, SDK interfaces)
- Authentication, authorization, and security-sensitive code
- Complex business logic and state management
- Data access, boundary code, and external integrations
- Utilities, helpers, and shared components
- Batch by module. Group files by their owning module or directory. Review one batch at a time, or dispatch concurrent agents per batch.
- Focus on structural issues. Without a diff to narrow scope, prioritize findings that affect architecture, correctness, and security over minor style issues.
- Cap findings per batch. Report the top 5-10 findings per module to keep the review actionable. Flag if a module needs deeper follow-up.
- Produce a summary. After all batches, produce a prioritized list of the most impactful findings across the codebase.
File Inspection
From the changed file list, classify each file:
| Pattern | Track |
|---|
| , (no JSX) | TypeScript |
| with React imports or JSX | React + TypeScript |
| , , , styled templates, Tailwind classes | CSS |
| Test files (, ) | Tests |
| New or moved , , , files | File Organization |
To detect new or moved files, run
git diff --diff-filter=AR
(with the same target used above). If any
,
,
, or
files appear, add "File Organization" to the tracks for the Style Pass.
Dispatch Concurrent Reviews
Run two review passes in parallel:
Style Pass
Step 1 — Read the index skill(s) based on file classification:
| Files | Read |
|---|
| , (TypeScript) | ../clean-typescript/SKILL.md
|
| React (JSX / React imports) | + ../clean-typescript/SKILL.md
|
| , , , styled, Tailwind | |
| Test files (, ) | ../clean-typescript-tests/SKILL.md
../clean-react-tests/SKILL.md
|
| New/moved , , , | ../clean-react-file-organization/SKILL.md
|
Step 2 — Read relevant sub-skills. Scan the diff and identify which rule categories appear. Then read only the sub-skill files that match before writing findings. Do not load all sub-skills — only the ones relevant to what is actually in the diff.
All skills are installed as siblings in the same directory. Reference TypeScript sub-skills with the sibling path pattern
../clean-typescript-{topic}/SKILL.md
and React sub-skills with
../clean-react-{topic}/SKILL.md
. Use the Skill Routing table in each index to map rule codes to sub-skill names.
Step 3 — Apply and report. Apply all loaded skills to the diff. Report findings with rule IDs.
Correctness Pass
Load
clean-code-reviewer-correctness
. Apply it to the full diff. This pass reviews for functional bugs, security vulnerabilities, performance issues, and test coverage gaps. It ignores style.
Merging Results
Combine findings from both passes into a single report.
Deduplication rule: If the correctness pass flags a code region, suppress any style finding that overlaps the same region. The correctness fix will resolve the style issue — reporting both is noise. Only keep the style finding if it addresses a genuinely independent concern at the same location.
Output Format
text
## Style
[Findings grouped by file]
## Correctness
[Findings grouped by file]
## Verdict
[Approve | Approve with suggestions | Request changes]
[One-sentence summary referencing finding codes, e.g. "Request changes — [S1] is a security hole; [C2] will break existing callers."]
Each finding uses this format, with its code as the leading identifier:
text
[S1] Severity: Block | Fix | Suggest
Category: Style (rule-id)
Location: path/to/file:line
Issue: What is wrong and why it matters.
Fix: Concrete next step.
text
[C1] Severity: Block | Fix | Suggest
Category: Correctness | Security | Performance | Test Coverage
Location: path/to/file:line
Issue: What is wrong and why it matters.
Fix: Concrete next step.
Style findings are numbered [S1], [S2], … in order of severity. Correctness findings are numbered [C1], [C2], … in order of severity. Numbers are assigned after merging so the user can reference any finding by code (e.g. "fix S2 and C1").
Severity Definitions
- Block: Will break production, cause data loss, introduce a security vulnerability, or silently corrupt behavior. Must be fixed before merge.
- Fix: Likely bug, likely vulnerability, or missing coverage for critical behavior. Should be fixed before merge.
- Suggest: Potential improvement worth considering. Does not block merge.
Verdict Rules
- Any Block finding → Request changes
- Any Fix finding → Request changes
- Only Suggest findings → Approve with suggestions
- No findings → Approve
After the verdict, always close with:
Reply with the codes you want fixed (e.g.
),
to address everything, or
to fix only Block findings.
If there are no findings, omit this prompt.
AI Behavior
- Do not review generated files, lock files, or vendored dependencies.
- Do not flag issues in code that was not changed unless the change breaks it.
- Keep the review focused. A 10-line diff should not produce 30 findings.
- When unsure whether something is a bug or intentional, use Suggest severity and say why.
- If the diff is too large to review thoroughly in one pass, say so and focus on the highest-risk files.