Specialist Review

Conducts focused reviews from a specific specialist's perspective.

Overview

This skill performs a deep-dive review from one specialist's expertise:

•Parses which specialist and what target to review
•Loads or creates the specialist in the team
•Analyzes the target from that specialist's unique lens
•Conducts expert-level review with specific findings
•Generates detailed review document
•Reports key findings and recommendations

Specialist guidance: references/specialist-perspectives.md Review template: assets/specialist-review-template.md

High-Level Workflow

1. Parse Request

Extract from user request:

•Specialist role: Which expert? (e.g., "Security Specialist", "Performance Expert")
•Target: What to review? (e.g., "API authentication", "database queries")

Input validation: Apply sanitization from _patterns.md:

•Specialist role: Alphanumeric + spaces/hyphens only, convert to kebab-case for filename
•Target: Remove dangerous characters, convert to kebab-case
•Combined filename length: max 100 characters

Examples:

•"Security Specialist" + "API authentication" → security-specialist-api-authentication.md
•"Ruby Expert" + "ActiveRecord models" → ruby-expert-activerecord-models.md

2. Load or Create Specialist

Check .architecture/members.yml for the requested specialist.

If exists: Load their profile (specialties, disciplines, domains, perspective)

If doesn't exist: Create new member and add to members.yml:

yaml

- id: [specialist_id]
  name: "[Person Name]"
  title: "[Specialist Title]"
  specialties: ["[Specialty 1]", "[Specialty 2]", "[Specialty 3]"]
  disciplines: ["[Discipline 1]", "[Discipline 2]"]
  skillsets: ["[Skill 1]", "[Skill 2]"]
  domains: ["[Domain 1]", "[Domain 2]"]
  perspective: "[Their unique viewpoint]"

Inform user: "I've added [Name] ([Title]) to your architecture team."

Specialist guidance: See references/specialist-perspectives.md § Creating New Specialists

3. Analyze Target

Use available tools to examine the target:

•Glob to find relevant files
•Grep to search for patterns
•Read to examine code, configs, documentation

Understand:

•Current implementation
•Dependencies and context
•Related ADRs or documentation
•Patterns being used

4. Conduct Expert Review

Adopt the specialist's persona and expertise. Apply their unique lens.

Review from specialist's perspective:

•Focus on their domain of expertise (security, performance, maintainability, etc.)
•Provide expert-level insights, not surface-level comments
•Reference specific files, line numbers, and code
•Explain impact and provide actionable fixes

Review structure (for each specialist):

•Specialist perspective and focus
•Executive summary with assessment
•Current implementation description
•Strengths identified
•Concerns with severity and specific fixes
•Recommendations (immediate, short-term, long-term)
•Best practices and industry standards
•Code examples showing issues and improvements
•Risks if not addressed
•Success metrics

Detailed guidance by specialist: references/specialist-perspectives.md § Core Specialists

Review template: Load and fill assets/specialist-review-template.md

5. Create Review Document

Load the template:

bash

cat .claude/skills/specialist-review/assets/specialist-review-template.md

Fill in all sections with detailed, specific findings.

Save to: .architecture/reviews/[specialist-role]-[target].md

Format: [role-kebab-case]-[target-kebab-case].md

6. Report to User

Provide concise summary:

code

[Specialist Title] Review Complete: [Target]

Reviewer: [Specialist Name]
Location: .architecture/reviews/[filename].md
Assessment: [Overall assessment]

Key Findings:
1. [Most important finding]
2. [Second finding]
3. [Third finding]

Priority Actions:
1. [Critical action 1]
2. [Critical action 2]

Critical Issues: [Count]
High Priority: [Count]
Total Recommendations: [Count]

Next Steps:
- Address critical issues immediately
- Review detailed findings in document
- [Specific next action based on findings]

Specialist Quick Reference

Core Specialists (see references/specialist-perspectives.md):

•Security Specialist: Authentication, authorization, vulnerabilities, OWASP
•Performance Specialist: Query optimization, caching, bottlenecks, scalability
•Domain Expert: Business logic, domain models, ubiquitous language
•Maintainability Expert: Code quality, technical debt, testability
•Systems Architect: Architecture patterns, component interaction, coherence
•AI Engineer: LLM integration, agent orchestration, evaluation

Technology Specialists:

•JavaScript/Python/Ruby/Go/Rust Expert: Language-specific best practices
•Framework Specialists: React, Rails, Django, Spring, etc.

Creating new specialists: Automatically added to team when requested

Related Skills

Before Specialist Review:

•list-members - See available specialists
•architecture-status - Check if area previously reviewed

After Specialist Review:

•create-adr - Document decisions from findings
•architecture-review - Include in comprehensive review
•Request another specialist for different domain perspective

Workflow Examples:

•Security review → Finds auth issue → Create ADR → Performance review
•Ruby Expert review → Rails-specific guidance → Implement → Follow-up review
•Full architecture review → Deep-dive with specialists on concerns

Quality Guidelines

Excellent specialist reviews:

•Stay laser-focused within domain
•Provide expert-level, not generic, insights
•Reference exact files and line numbers
•Include code examples (current vs recommended)
•Explain "why", not just "what"
•Consider context and constraints
•Provide actionable, implementable advice
•Estimate effort for each recommendation

Avoid:

•Straying outside specialist's domain
•Vague or surface-level comments
•Missing specific locations
•Recommendations without implementation guidance

Documentation

•Specialist guidance: references/specialist-perspectives.md
•Review template: assets/specialist-review-template.md
•Common patterns: ../_patterns.md