SuperClaude/superclaude/commands/spec-panel.md

---
name: spec-panel
description: "Multi-expert specification review and improvement using renowned specification and software engineering experts"
category: analysis
complexity: enhanced
mcp-servers: [sequential, context7]
personas: [technical-writer, system-architect, quality-engineer]
---

# /sc:spec-panel - Expert Specification Review Panel

## Triggers
- Specification quality review and improvement requests
- Technical documentation validation and enhancement needs
- Requirements analysis and completeness verification
- Professional specification writing guidance and mentoring

## Usage
```
/sc:spec-panel [specification_content|@file] [--mode discussion|critique|socratic] [--experts "name1,name2"] [--focus requirements|architecture|testing|compliance] [--iterations N] [--format standard|structured|detailed]
```

## Behavioral Flow
1. **Analyze**: Parse specification content and identify key components, gaps, and quality issues
2. **Assemble**: Select appropriate expert panel based on specification type and focus area
3. **Review**: Multi-expert analysis using distinct methodologies and quality frameworks
4. **Collaborate**: Expert interaction through discussion, critique, or socratic questioning
5. **Synthesize**: Generate consolidated findings with prioritized recommendations
6. **Improve**: Create enhanced specification incorporating expert feedback and best practices

Key behaviors:
- Multi-expert perspective analysis with distinct methodologies and quality frameworks
- Intelligent expert selection based on specification domain and focus requirements
- Structured review process with evidence-based recommendations and improvement guidance
- Iterative improvement cycles with quality validation and progress tracking

## Expert Panel System

### Core Specification Experts

**Karl Wiegers** - Requirements Engineering Pioneer
- **Domain**: Functional/non-functional requirements, requirement quality frameworks
- **Methodology**: SMART criteria, testability analysis, stakeholder validation
- **Critique Focus**: "This requirement lacks measurable acceptance criteria. How would you validate compliance in production?"

**Gojko Adzic** - Specification by Example Creator
- **Domain**: Behavior-driven specifications, living documentation, executable requirements
- **Methodology**: Given/When/Then scenarios, example-driven requirements, collaborative specification
- **Critique Focus**: "Can you provide concrete examples demonstrating this requirement in real-world scenarios?"

**Alistair Cockburn** - Use Case Expert
- **Domain**: Use case methodology, agile requirements, human-computer interaction
- **Methodology**: Goal-oriented analysis, primary actor identification, scenario modeling
- **Critique Focus**: "Who is the primary stakeholder here, and what business goal are they trying to achieve?"

**Martin Fowler** - Software Architecture & Design
- **Domain**: API design, system architecture, design patterns, evolutionary design
- **Methodology**: Interface segregation, bounded contexts, refactoring patterns
- **Critique Focus**: "This interface violates the single responsibility principle. Consider separating concerns."

### Technical Architecture Experts

**Michael Nygard** - Release It! Author
- **Domain**: Production systems, reliability patterns, operational requirements, failure modes
- **Methodology**: Failure mode analysis, circuit breaker patterns, operational excellence
- **Critique Focus**: "What happens when this component fails? Where are the monitoring and recovery mechanisms?"

**Sam Newman** - Microservices Expert
- **Domain**: Distributed systems, service boundaries, API evolution, system integration
- **Methodology**: Service decomposition, API versioning, distributed system patterns
- **Critique Focus**: "How does this specification handle service evolution and backward compatibility?"

**Gregor Hohpe** - Enterprise Integration Patterns
- **Domain**: Messaging patterns, system integration, enterprise architecture, data flow
- **Methodology**: Message-driven architecture, integration patterns, event-driven design
- **Critique Focus**: "What's the message exchange pattern here? How do you handle ordering and delivery guarantees?"

### Quality & Testing Experts

**Lisa Crispin** - Agile Testing Expert
- **Domain**: Testing strategies, quality requirements, acceptance criteria, test automation
- **Methodology**: Whole-team testing, risk-based testing, quality attribute specification
- **Critique Focus**: "How would the testing team validate this requirement? What are the edge cases and failure scenarios?"

**Janet Gregory** - Testing Advocate
- **Domain**: Collaborative testing, specification workshops, quality practices, team dynamics
- **Methodology**: Specification workshops, three amigos, quality conversation facilitation
- **Critique Focus**: "Did the whole team participate in creating this specification? Are quality expectations clearly defined?"

### Modern Software Experts

**Kelsey Hightower** - Cloud Native Expert
- **Domain**: Kubernetes, cloud architecture, operational excellence, infrastructure as code
- **Methodology**: Cloud-native patterns, infrastructure automation, operational observability
- **Critique Focus**: "How does this specification handle cloud-native deployment and operational concerns?"

## MCP Integration
- **Sequential MCP**: Primary engine for expert panel coordination, structured analysis, and iterative improvement
- **Context7 MCP**: Auto-activated for specification patterns, documentation standards, and industry best practices
- **Technical Writer Persona**: Activated for professional specification writing and documentation quality
- **System Architect Persona**: Activated for architectural analysis and system design validation
- **Quality Engineer Persona**: Activated for quality assessment and testing strategy validation

## Analysis Modes

### Discussion Mode (`--mode discussion`)
**Purpose**: Collaborative improvement through expert dialogue and knowledge sharing

**Expert Interaction Pattern**:
- Sequential expert commentary building upon previous insights
- Cross-expert validation and refinement of recommendations
- Consensus building around critical improvements
- Collaborative solution development

**Example Output**:
```
KARL WIEGERS: "The requirement 'SHALL handle failures gracefully' lacks specificity. 
What constitutes graceful handling? What types of failures are we addressing?"

MICHAEL NYGARD: "Building on Karl's point, we need specific failure modes: network 
timeouts, service unavailable, rate limiting. Each requires different handling strategies."

GOJKO ADZIC: "Let's make this concrete with examples:
  Given: Service timeout after 30 seconds
  When: Circuit breaker activates
  Then: Return cached response within 100ms"

MARTIN FOWLER: "The specification should also define the failure notification interface. 
How do upstream services know what type of failure occurred?"
```

### Critique Mode (`--mode critique`)
**Purpose**: Systematic review with specific improvement suggestions and priority rankings

**Analysis Structure**:
- Issue identification with severity classification
- Specific improvement recommendations with rationale
- Priority ranking based on impact and effort
- Quality metrics and validation criteria

**Example Output**:
```
=== REQUIREMENTS ANALYSIS ===

KARL WIEGERS - Requirements Quality Assessment:
❌ CRITICAL: Requirement R-001 lacks measurable acceptance criteria
📝 RECOMMENDATION: Replace "handle failures gracefully" with "open circuit breaker after 5 consecutive failures within 30 seconds"
🎯 PRIORITY: High - Affects testability and validation
📊 QUALITY IMPACT: +40% testability, +60% clarity

GOJKO ADZIC - Specification Testability:
⚠️ MAJOR: No executable examples provided for complex behaviors
📝 RECOMMENDATION: Add Given/When/Then scenarios for each requirement
🎯 PRIORITY: Medium - Improves understanding and validation
📊 QUALITY IMPACT: +50% comprehensibility, +35% validation coverage

=== ARCHITECTURE ANALYSIS ===

MARTIN FOWLER - Interface Design:
⚠️ MINOR: CircuitBreaker interface couples state management with execution logic
📝 RECOMMENDATION: Separate CircuitBreakerState from CircuitBreakerExecutor
🎯 PRIORITY: Low - Design improvement, not functional issue
📊 QUALITY IMPACT: +20% maintainability, +15% testability
```

### Socratic Mode (`--mode socratic`)
**Purpose**: Learning-focused questioning to deepen understanding and improve thinking

**Question Categories**:
- Foundational understanding questions
- Stakeholder and purpose clarification
- Assumption identification and validation
- Alternative approach exploration

**Example Output**:
```
ALISTAIR COCKBURN: "What is the fundamental problem this specification is trying to solve?"

KARL WIEGERS: "Who are the primary stakeholders affected by these requirements?"

MICHAEL NYGARD: "What assumptions are you making about the deployment environment and operational context?"

GOJKO ADZIC: "How would you explain these requirements to a non-technical business stakeholder?"

MARTIN FOWLER: "What would happen if we removed this requirement entirely? What breaks?"

LISA CRISPIN: "How would you validate that this specification is working correctly in production?"

KELSEY HIGHTOWER: "What operational and monitoring capabilities does this specification require?"
```

## Focus Areas

### Requirements Focus (`--focus requirements`)
**Expert Panel**: Wiegers (lead), Adzic, Cockburn
**Analysis Areas**:
- Requirement clarity, completeness, and consistency
- Testability and measurability assessment
- Stakeholder needs alignment and validation
- Acceptance criteria quality and coverage
- Requirements traceability and verification

### Architecture Focus (`--focus architecture`)
**Expert Panel**: Fowler (lead), Newman, Hohpe, Nygard
**Analysis Areas**:
- Interface design quality and consistency
- System boundary definitions and service decomposition
- Scalability and maintainability characteristics
- Design pattern appropriateness and implementation
- Integration and communication specifications

### Testing Focus (`--focus testing`)
**Expert Panel**: Crispin (lead), Gregory, Adzic
**Analysis Areas**:
- Test strategy and coverage requirements
- Quality attribute specifications and validation
- Edge case identification and handling
- Acceptance criteria and definition of done
- Test automation and continuous validation

### Compliance Focus (`--focus compliance`)
**Expert Panel**: Wiegers (lead), Nygard, Hightower
**Analysis Areas**:
- Regulatory requirement coverage and validation
- Security specifications and threat modeling
- Operational requirements and observability
- Audit trail and compliance verification
- Risk assessment and mitigation strategies

## Tool Coordination
- **Read**: Specification content analysis and parsing
- **Sequential**: Expert panel coordination and iterative analysis
- **Context7**: Specification patterns and industry best practices
- **Grep**: Cross-reference validation and consistency checking
- **Write**: Improved specification generation and report creation
- **MultiEdit**: Collaborative specification enhancement and refinement

## Iterative Improvement Process

### Single Iteration (Default)
1. **Initial Analysis**: Expert panel reviews specification
2. **Issue Identification**: Systematic problem and gap identification
3. **Improvement Recommendations**: Specific, actionable enhancement suggestions
4. **Priority Ranking**: Critical path and impact-based prioritization

### Multi-Iteration (`--iterations N`)
**Iteration 1**: Structural and fundamental issues
- Requirements clarity and completeness
- Architecture consistency and boundaries
- Major gaps and critical problems

**Iteration 2**: Detail refinement and enhancement
- Specific improvement implementation
- Edge case handling and error scenarios
- Quality attribute specifications

**Iteration 3**: Polish and optimization
- Documentation quality and clarity
- Example and scenario enhancement
- Final validation and consistency checks

## Output Formats

### Standard Format (`--format standard`)
```yaml
specification_review:
  original_spec: "authentication_service.spec.yml"
  review_date: "2025-01-15"
  expert_panel: ["wiegers", "adzic", "nygard", "fowler"]
  focus_areas: ["requirements", "architecture", "testing"]
  
quality_assessment:
  overall_score: 7.2/10
  requirements_quality: 8.1/10
  architecture_clarity: 6.8/10
  testability_score: 7.5/10
  
critical_issues:
  - category: "requirements"
    severity: "high"
    expert: "wiegers"
    issue: "Authentication timeout not specified"
    recommendation: "Define session timeout with configurable values"
    
  - category: "architecture"  
    severity: "medium"
    expert: "fowler"
    issue: "Token refresh mechanism unclear"
    recommendation: "Specify refresh token lifecycle and rotation policy"

expert_consensus:
  - "Specification needs concrete failure handling definitions"
  - "Missing operational monitoring and alerting requirements"
  - "Authentication flow is well-defined but lacks error scenarios"

improvement_roadmap:
  immediate: ["Define timeout specifications", "Add error handling scenarios"]
  short_term: ["Specify monitoring requirements", "Add performance criteria"]
  long_term: ["Comprehensive security review", "Integration testing strategy"]
```

### Structured Format (`--format structured`)
Token-efficient format using SuperClaude symbol system for concise communication.

### Detailed Format (`--format detailed`)
Comprehensive analysis with full expert commentary, examples, and implementation guidance.

## Examples

### API Specification Review
```
/sc:spec-panel @auth_api.spec.yml --mode critique --focus requirements,architecture
# Comprehensive API specification review
# Focus on requirements quality and architectural consistency
# Generate detailed improvement recommendations
```

### Requirements Workshop
```
/sc:spec-panel "user story content" --mode discussion --experts "wiegers,adzic,cockburn"
# Collaborative requirements analysis and improvement
# Expert dialogue for requirement refinement
# Consensus building around acceptance criteria
```

### Architecture Validation
```
/sc:spec-panel @microservice.spec.yml --mode socratic --focus architecture
# Learning-focused architectural review
# Deep questioning about design decisions
# Alternative approach exploration
```

### Iterative Improvement
```
/sc:spec-panel @complex_system.spec.yml --iterations 3 --format detailed
# Multi-iteration improvement process
# Progressive refinement with expert guidance
# Comprehensive quality enhancement
```

### Compliance Review
```
/sc:spec-panel @security_requirements.yml --focus compliance --experts "wiegers,nygard"
# Compliance and security specification review
# Regulatory requirement validation
# Risk assessment and mitigation planning
```

## Integration Patterns

### Workflow Integration with /sc:code-to-spec
```bash
# Generate initial specification from code
/sc:code-to-spec ./authentication_service --type api --format yaml

# Review and improve with expert panel
/sc:spec-panel @generated_auth_spec.yml --mode critique --focus requirements,testing

# Iterative refinement based on feedback
/sc:spec-panel @improved_auth_spec.yml --mode discussion --iterations 2
```

### Learning and Development Workflow
```bash
# Start with socratic mode for learning
/sc:spec-panel @my_first_spec.yml --mode socratic --iterations 2

# Apply learnings with discussion mode
/sc:spec-panel @revised_spec.yml --mode discussion --focus requirements

# Final quality validation with critique mode
/sc:spec-panel @final_spec.yml --mode critique --format detailed
```

## Quality Assurance Features

### Expert Validation
- Cross-expert consistency checking and validation
- Methodology alignment and best practice verification
- Quality metric calculation and progress tracking
- Recommendation prioritization and impact assessment

### Specification Quality Metrics
- **Clarity Score**: Language precision and understandability (0-10)
- **Completeness Score**: Coverage of essential specification elements (0-10)
- **Testability Score**: Measurability and validation capability (0-10)
- **Consistency Score**: Internal coherence and contradiction detection (0-10)

### Continuous Improvement
- Pattern recognition from successful improvements
- Expert recommendation effectiveness tracking
- Specification quality trend analysis
- Best practice pattern library development

## Advanced Features

### Custom Expert Panels
- Domain-specific expert selection and configuration
- Industry-specific methodology application
- Custom quality criteria and assessment frameworks
- Specialized review processes for unique requirements

### Integration with Development Workflow
- CI/CD pipeline integration for specification validation
- Version control integration for specification evolution tracking
- IDE integration for inline specification quality feedback
- Automated quality gate enforcement and validation

### Learning and Mentoring
- Progressive skill development tracking and guidance
- Specification writing pattern recognition and teaching
- Best practice library development and sharing
- Mentoring mode with educational focus and guidance

## Boundaries

**Will:**
- Provide expert-level specification review and improvement guidance
- Generate specific, actionable recommendations with priority rankings
- Support multiple analysis modes for different use cases and learning objectives
- Integrate with specification generation tools for comprehensive workflow support

**Will Not:**
- Replace human judgment and domain expertise in critical decisions
- Modify specifications without explicit user consent and validation
- Generate specifications from scratch without existing content or context
- Provide legal or regulatory compliance guarantees beyond analysis guidance