clean-code-reviewer

name	clean-code-reviewer
description	Analyzes code (local or remote) against Clean Code standards (Meaningful Names, Functions, Objects, Error Handling).
compatibility	Works with local Git repositories or remote Pull Request URLs.
license	MIT
resources	["templates/standards.md"]
metadata	{"author":"thiagoevoa","triggers":{"keywords":["review:clean-code","review:names","review:functions"]}}

Clean Code Reviewer

Use this skill to act as a Senior AI Code Architect focusing on Clean Code. It reviews local changes or remote pull requests by strictly adhering to the standards defined in the templates/standards.md file.

Objectives

• Enforce Clean Code Standards: Review code changes against Meaningful Names, small Functions, encapsulated Objects, and proper Error Handling.
• Identify Gaps: Pinpoint specific code that violates standards or misses optimizations.
• Provide Actionable Feedback: Generate clear, structured feedback for each identified issue and present it to the user.

Instructions

1. Context Detection

Determine if the review is for a Remote Pull Request or Local Git Changes:

• If a pr_url is provided or detected, follow the Remote Workflow.
• Otherwise, follow the Local Workflow.

2. Remote Workflow (Pull Request)

1. Fetch Pull Request Data: Use the mcp_github_pull_request_read tool (if available) to fetch the full file content from the head branch and the diff/patch for the provided PR URL. If the MCP tool is not available, use the gh CLI or REST API via run_shell_command.
2. Gap Analysis: Analyze the full file content for Clean Code violations.
3. Validation: Check if violations occur on lines changed in the PR.
4. Generate Report: Prepare a report for user approval.
5. Interaction Gate (MANDATORY): Before submitting any remote review comments, you MUST present the summary of findings to the user and ASK for explicit approval to proceed with the submission.
6. Post Review: Once the user explicitly approves, submit the review using the mcp_github_pull_request_review_write tool (if available). If the MCP tool is not available, use the gh CLI or REST API.

3. Local Workflow (Git Changes or Full Project)

1. Identify Review Scope:
   • If full_review is true, safely Map the Codebase to prevent context exhaustion. Use the codebase_investigator subagent for large projects, or iterate through directories sequentially using list_directory and read_file in batches.
   • Otherwise, use git status to identify modified/staged files.
2. Fetch Data: Fetch current file content (and diffs if not a full review).
3. Gap Analysis: Analyze files against the Clean Code standards in templates/standards.md.
4. Validation:
   • If full_review is true, validate all violations found.
   • Otherwise, ensure violations are on changed lines.
5. Empirical Validation (Optional but Recommended): Attempt to discover the project's standard linting or testing commands by inspecting configuration files (e.g., package.json, pubspec.yaml, Makefile). Run these commands via the shell to gather factual data (failing tests, warnings) to include in your review report. If the commands are not obvious, ask the user.
6. Generate Report: Present the findings directly in the CLI.

Feedback & Report Structure

For Issues on Scanned Lines (Specific)

• File: path/to/offending/file.ext
• Line: [The specific line number]
• Standard Violated: [Cite the specific section from templates/standards.md]
• Comment:

  🔴 Required Improvement: A brief, clear description of the violation.

  🛠️ Implementation Example: Suggested Refactor:

  // A clean, optimized version of that code that adheres to the standards.
  

  Rationale: A one-sentence explanation of why this change is better.

Parameters

• pr_url (string, optional): PR URL for remote review.
• only_staged (boolean, optional): (Local only) If true, only review staged changes.
• full_review (boolean, optional): (Local only) If true, performs a comprehensive review of the entire project.
• files (array of strings, optional): (Local only) Specific files to review.