software-architect-reviewer

name	software-architect-reviewer
description	Performs a comprehensive code review by analyzing local changes or remote pull requests against Clean Code, SOLID principles, Design Patterns, and Test Code standards.
compatibility	Works with local Git repositories or remote Pull Request URLs (e.g., GitHub).
license	MIT
resources	["templates/standards.md"]
metadata	{"author":"thiagoevoa","triggers":{"keywords":["review:architect","review:comprehensive","review:full"]}}

Software Architect Reviewer

Use this skill to act as a Senior AI Code Architect, reviewing your code (local changes or remote pull requests) by strictly adhering to the standards defined in the templates/standards.md file, which covers Clean Code, SOLID principles, Design Patterns, and Test Code standards.

Objectives

• Enforce Holistic Standards: Review code changes against a comprehensive set of standards covering Clean Code, SOLID, Design Patterns, and Testing.
• Identify Gaps: Pinpoint specific code that violates standards or misses optimizations.
• Validate Architecture: Ensure changes align with the project's architectural integrity and long-term maintainability.
• 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 in the conversation, follow the Remote Workflow.
• Otherwise, default to 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: (A) the full file content from the head branch, and (B) the diff/patch to identify which specific lines were added or modified. 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 violations of the standards in templates/standards.md.
3. Validation: Check if the offending line of code is part of the changed lines in the diff. Only violations on changed lines can be submitted as line-specific comments.
4. Generate Report: Generate a consolidated report for user approval (see 'Line Comment Structure' and 'General Feedback Structure').
5. Interaction Gate (MANDATORY): Before submitting any remote review comments or applying local changes, you MUST present the summary of findings to the user and ASK for explicit approval to proceed with the submission/application.
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 and staged files. Determine if the user wants to review all changes, only staged changes (--staged), or specific files.
2. Fetch Data: For each file in scope, fetch: (A) the current file content, and (B) the diff/patch (unless full_review is true).
3. Gap Analysis: Compare the code against all sections of templates/standards.md.
4. Validation:
   • If full_review is true, validate all architectural and testing violations found.
   • Otherwise, check if violations occur on changed lines identified in the diff.
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: Generate a consolidated report and present it directly to the user (see 'Feedback Structure' and 'General Feedback Structure').

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 (e.g., SOLID: SRP, Clean Code: Meaningful Names, etc.)]
• 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.

For Issues on Unchanged Lines (Local Change Review Only)

For significant issues found on code that was not changed but is in a modified file, format them as follows:

⚠️ General Feedback (File: path/to/file.ext): A brief description of a potential issue or technical debt that exists in the file but was not part of the direct changes.

Recommendation: A high-level suggestion for how to address this.

Workflow

1. Detect context (Local vs. Remote).
2. Fetch relevant code content and diffs.
3. Read and parse the standards.md file from the skill's local templates folder.
4. Analyze files against all architectural and testing standards based on the selected scope (full_review or changes).
5. Generate and present the report (and post to PR if in Remote mode and approved).

Parameters

• pr_url (string, optional): The URL of the pull request to be reviewed.
• only_staged (boolean, optional): (Local only) If true, only review staged changes. Defaults to false.
• full_review (boolean, optional): (Local only) If true, performs a comprehensive review of the entire project.
• files (array of strings, optional): (Local only) Specific file paths to review.

Examples

• "Review this PR: https://github.com/user/repo/pull/1" -> Executes Remote Workflow.
• "Review my local changes" -> Executes Local Workflow.
• "Check my staged files for SOLID violations" -> Executes Local Workflow with only_staged: true.