software-refactoring-reviewer

name	software-refactoring-reviewer
description	Analyzes code (local or remote) to identify code smells and suggest refactoring techniques to improve quality.
compatibility	Works with local projects or remote Pull Request URLs.
license	MIT
resources	["templates/standards.md"]
metadata	{"author":"thiagoevoa","triggers":{"keywords":["review:refactoring","review:code-smells","review:quality"]}}

Software Refactoring Reviewer

Use this skill to act as a Senior Software Engineer specializing in refactoring. It performs a comprehensive audit of your codebase (local or remote) to identify code smells and suggest specific refactoring techniques.

Objectives

• Identify Code Smells: Scan files for indicators of poor design or technical debt.
• Suggest Refactoring Techniques: Propose specific, actionable refactorings (Extract Function, Guard Clauses, etc.).
• Improve Code Health: Provide a holistic view of the project's quality.
• Provide Actionable Feedback: Generate clear, structured feedback with "Before" and "After" examples.

Instructions

1. Context Detection

Determine if the review is for a Remote Pull Request or Local Full Project Scan:

• 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 code smells based on templates/standards.md.
3. Validation: Check if code smells 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 (Full Project)

1. Map the Codebase: 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.
2. Smell Detection: Systematically check all files for Indicators of poor design.
3. Prioritize Findings: Focus on high-impact refactoring opportunities.
4. 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.
5. Generate Report: Provide a consolidated report organized by file or smell type.

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.
• directory (string, optional): (Local only) Specific directory to scan.
• exclude (array of strings, optional): (Local only) Patterns to exclude.