gh-superclaude-org-superclaude-plugin/commands/spec-panel.md

description, category, complexity, mcp-servers, personas

description	category	complexity	mcp-servers	personas
Multi-expert specification review and improvement using renowned specification and software engineering experts	analysis	enhanced	sequential context7	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)

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

# 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

# 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