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 :

• 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:

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:

[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