diff --git a/.claude/commands/workflow/brainstorm/synthesis.md b/.claude/commands/workflow/brainstorm/synthesis.md index 0f879c43..895cd764 100644 --- a/.claude/commands/workflow/brainstorm/synthesis.md +++ b/.claude/commands/workflow/brainstorm/synthesis.md @@ -2,7 +2,7 @@ name: synthesis description: Generate synthesis-specification.md from topic-framework and role analyses with @ references argument-hint: "no arguments required - synthesizes existing framework and role analyses" -allowed-tools: Read(*), Write(*), TodoWrite(*), Glob(*) +allowed-tools: Task(action-planning-agent), TodoWrite(*), Read(*), Write(*) --- ## 🧩 **Synthesis Document Generator** @@ -29,15 +29,28 @@ allowed-tools: Read(*), Write(*), TodoWrite(*), Glob(*) ## ⚙️ **Execution Protocol** -### ⚠️ Direct Execution by Main Claude -**Execution Model**: Main Claude directly executes this command without delegating to sub-agents. +### ⚠️ Agent Execution with Flow Control +**Execution Model**: Uses action-planning-agent for synthesis generation with structured file loading. **Rationale**: -- **Full Context Access**: Avoids context transmission loss that occurs with Task tool delegation -- **Complex Cognitive Analysis**: Leverages main Claude's complete reasoning capabilities for cross-role synthesis -- **Tool Usage**: Combines Read/Write/Glob tools with main Claude's analytical intelligence +- **Autonomous Execution**: Agent independently loads and processes all required documents +- **Flow Control**: Structured document loading ensures systematic analysis +- **Complex Cognitive Analysis**: Leverages agent's analytical capabilities for cross-role synthesis -**DO NOT use Task tool** - Main Claude performs intelligent analysis directly while reading/writing files, ensuring no information loss from context passing. +**Agent Responsibility**: All file reading and synthesis generation performed by action-planning-agent with FLOW_CONTROL instructions. + +### 📋 Task Tracking Protocol +Initialize synthesis task tracking using TodoWrite at command start: +```json +[ + {"content": "Detect active session and validate topic-framework.md existence", "status": "in_progress", "activeForm": "Detecting session and validating framework"}, + {"content": "Discover participating role analyses dynamically", "status": "pending", "activeForm": "Discovering role analyses"}, + {"content": "Check existing synthesis and confirm user action", "status": "pending", "activeForm": "Checking update mechanism"}, + {"content": "Execute synthesis generation using action-planning-agent with FLOW_CONTROL", "status": "pending", "activeForm": "Executing agent-based synthesis generation"}, + {"content": "Agent performs cross-role analysis and generates synthesis-specification.md", "status": "pending", "activeForm": "Agent analyzing and generating synthesis"}, + {"content": "Update workflow-session.json with synthesis completion status", "status": "pending", "activeForm": "Updating session metadata"} +] +``` ### Phase 1: Document Discovery & Validation ```bash @@ -102,79 +115,104 @@ ELSE: CREATE new synthesis ``` -### Phase 4: Synthesis Generation Process -Initialize synthesis task tracking: -```json -[ - {"content": "Validate topic-framework.md and role analyses availability", "status": "in_progress", "activeForm": "Validating source documents"}, - {"content": "Load topic framework discussion points structure", "status": "pending", "activeForm": "Loading framework structure"}, - {"content": "Cross-analyze role responses to each framework point", "status": "pending", "activeForm": "Cross-analyzing framework responses"}, - {"content": "Generate synthesis-specification.md with @ references", "status": "pending", "activeForm": "Generating synthesis with references"}, - {"content": "Update session metadata with synthesis completion", "status": "pending", "activeForm": "Updating session metadata"} -] -``` +### Phase 4: Agent Execution with Flow Control +**Synthesis Generation using action-planning-agent** -### Phase 5: Cross-Role Analysis Execution +Delegate synthesis generation to action-planning-agent with structured file loading: -**Dynamic Role Processing**: The number and types of roles are determined at runtime based on actual analysis.md files discovered in Phase 2. +```bash +Task(action-planning-agent): " +[FLOW_CONTROL] -#### 5.1 Data Collection and Preprocessing -```pseudo -# Iterate over dynamically discovered role analyses -FOR each discovered_role IN participating_roles: - role_directory = brainstorm_dir + "/" + discovered_role +Execute comprehensive synthesis generation from topic framework and role analyses - # Load role analysis (required) - role_analysis = Read(role_directory + "/analysis.md") +## Context Loading +OUTPUT_FILE: synthesis-specification.md +OUTPUT_PATH: .workflow/WFS-{session}/.brainstorming/synthesis-specification.md +SESSION_ID: {session_id} +ANALYSIS_MODE: cross_role_synthesis - # Load optional artifacts if present - IF EXISTS(role_directory + "/recommendations.md"): - role_recommendations[discovered_role] = Read(role_directory + "/recommendations.md") - END IF +## Flow Control Steps +1. **load_topic_framework** + - Action: Load structured topic discussion framework + - Command: Read(.workflow/WFS-{session}/.brainstorming/topic-framework.md) + - Output: topic_framework_content - # Extract insights from analysis - role_insights[discovered_role] = extract_key_insights(role_analysis) - role_recommendations[discovered_role] = extract_recommendations(role_analysis) - role_concerns[discovered_role] = extract_concerns_risks(role_analysis) - role_diagrams[discovered_role] = identify_diagrams_and_visuals(role_analysis) -END FOR +2. **discover_role_analyses** + - Action: Dynamically discover all participating role analysis files + - Command: Glob(.workflow/WFS-{session}/.brainstorming/*/analysis.md) + - Output: role_analysis_paths, participating_roles -# Log participating roles for metadata -participating_role_count = COUNT(participating_roles) -participating_role_names = participating_roles -``` +3. **load_role_analyses** + - Action: Load all discovered role analysis documents + - Command: Read(each path from role_analysis_paths) + - Output: role_analyses_content -#### 5.2 Cross-Role Insight Analysis -```pseudo -# Consensus identification (across all participating roles) -consensus_areas = identify_common_themes(role_insights) -agreement_matrix = create_agreement_matrix(role_recommendations) +4. **check_existing_synthesis** + - Action: Check if synthesis-specification.md already exists + - Command: Read(.workflow/WFS-{session}/.brainstorming/synthesis-specification.md) [if exists] + - Output: existing_synthesis_content [optional] -# Disagreement analysis (track which specific roles disagree) -disagreement_areas = identify_conflicting_views(role_insights) -tension_points = analyze_role_conflicts(role_recommendations) -FOR each conflict IN disagreement_areas: - conflict.dissenting_roles = identify_dissenting_roles(conflict) -END FOR +5. **load_session_metadata** + - Action: Load session metadata and context + - Command: Read(.workflow/WFS-{session}/workflow-session.json) + - Output: session_context -# Innovation opportunity extraction -innovation_opportunities = extract_breakthrough_ideas(role_insights) -synergy_opportunities = identify_cross_role_synergies(role_insights) -``` +6. **load_synthesis_template** + - Action: Load synthesis role template for structure and guidelines + - Command: Read(~/.claude/workflows/cli-templates/planning-roles/synthesis-role.md) + - Output: synthesis_template_guidelines -#### 5.3 Priority and Decision Matrix Generation -```pseudo -# Create comprehensive evaluation matrix -FOR each recommendation: - impact_score = calculate_business_impact(recommendation, role_insights) - feasibility_score = calculate_technical_feasibility(recommendation, role_insights) - effort_score = calculate_implementation_effort(recommendation, role_insights) - risk_score = calculate_associated_risks(recommendation, role_insights) - - priority_score = weighted_score(impact_score, feasibility_score, effort_score, risk_score) -END FOR +## Synthesis Requirements -SORT recommendations BY priority_score DESC +### Core Integration +**Cross-Role Analysis**: Integrate all discovered role analyses with comprehensive coverage +**Framework Integration**: Address how each role responded to topic-framework.md discussion points +**Decision Transparency**: Document both adopted solutions and rejected alternatives with rationale +**Process Integration**: Include team capability gaps, process risks, and collaboration patterns +**Visual Documentation**: Include key diagrams (architecture, data model, user journey) via Mermaid +**Priority Matrix**: Create quantified recommendation matrix with multi-dimensional evaluation +**Actionable Plan**: Provide phased implementation roadmap with clear next steps + +### Cross-Role Analysis Process (Agent Internal Execution) +Perform systematic cross-role analysis following these steps: + +1. **Data Collection**: Extract key insights, recommendations, concerns, and diagrams from each discovered role analysis +2. **Consensus Identification**: Identify common themes and agreement areas across all participating roles +3. **Disagreement Analysis**: Document conflicting views and track which specific roles disagree on each point +4. **Innovation Extraction**: Identify breakthrough ideas and cross-role synergy opportunities +5. **Priority Scoring**: Calculate multi-dimensional priority scores (impact, feasibility, effort, risk) for each recommendation +6. **Decision Matrix**: Create comprehensive evaluation matrix and sort recommendations by priority + +## Synthesis Quality Standards +Follow synthesis-specification.md structure defined in synthesis-role.md template: +- Use template structure for comprehensive document organization +- Apply analysis guidelines for cross-role synthesis process +- Include all required sections from template (Executive Summary, Key Designs, Requirements, etc.) +- Follow @ reference system for traceability to source role analyses +- Apply quality standards from template (completeness, visual clarity, decision transparency) +- Validate output against template's output validation checklist + +## Expected Deliverables +1. **synthesis-specification.md**: Complete integrated specification consolidating all role perspectives +2. **@ References**: Include cross-references to source role analyses +3. **Session Metadata Update**: Update workflow-session.json with synthesis completion status + +## Completion Criteria +- All discovered role analyses integrated without gaps +- Framework discussion points addressed across all roles +- Controversial points documented with dissenting roles identified +- Process concerns (team capabilities, risks, collaboration) captured +- Quantified priority recommendations with evaluation criteria +- Actionable implementation plan with phased approach +- Comprehensive risk assessment with mitigation strategies + +## Execution Notes +- Dynamic role participation: Only synthesize roles that produced analysis.md files +- Update mechanism: If synthesis exists, prompt user for regenerate/update/preserve decision +- Timeout allocation: Complex synthesis task (60-90 min recommended) +- Reference @intelligent-tools-strategy.md for timeout guidelines +" ``` ## 📊 **Output Specification** @@ -189,153 +227,22 @@ The synthesis process creates **one consolidated document** that integrates all └── synthesis-specification.md # ★ OUTPUT: Complete integrated specification ``` -#### synthesis-specification.md Structure (Complete Specification) +#### synthesis-specification.md Structure **Document Purpose**: Defines **"WHAT"** to build - comprehensive requirements and design blueprint. **Scope**: High-level features, requirements, and design specifications. Does NOT include executable task breakdown (that's IMPL_PLAN.md's responsibility). -```markdown -# [Topic] - Integrated Implementation Specification +**Template Reference**: Complete document structure and content guidelines available in `synthesis-role.md` template, including: +- Executive Summary with strategic overview +- Key Designs & Decisions (architecture diagrams, ADRs, user journeys) +- Controversial Points & Alternatives (decision transparency) +- Requirements & Acceptance Criteria (Functional, Non-Functional, Business) +- Design Specifications (UI/UX, Architecture, Domain Expertise) +- Process & Collaboration Concerns (team skills, risks, patterns, constraints) +- Implementation Roadmap (high-level phases) +- Risk Assessment & Mitigation strategies -**Framework Reference**: @topic-framework.md | **Generated**: [timestamp] | **Session**: WFS-[topic-slug] -**Source Integration**: All brainstorming role perspectives consolidated -**Document Type**: Requirements & Design Specification (WHAT to build) - -## Executive Summary -Strategic overview with key insights, breakthrough opportunities, and implementation priorities. - -## Key Designs & Decisions -### Core Architecture Diagram -```mermaid -graph TD - A[Component A] --> B[Component B] - B --> C[Component C] -``` -*Reference: @system-architect/analysis.md#architecture-diagram* - -### User Journey Map -![User Journey](./assets/user-journey.png) -*Reference: @ux-expert/analysis.md#user-journey* - -### Data Model Overview -```mermaid -erDiagram - USER ||--o{ ORDER : places - ORDER ||--|{ LINE-ITEM : contains -``` -*Reference: @data-architect/analysis.md#data-model* - -### Architecture Decision Records (ADRs) -**ADR-01: [Decision Title]** -- **Context**: Background and problem statement -- **Decision**: Chosen approach -- **Rationale**: Why this approach was selected -- **Reference**: @system-architect/analysis.md#adr-01 - -## Controversial Points & Alternatives -| Point | Adopted Solution | Alternative Solution(s) | Decision Rationale | Dissenting Roles | -|-------|------------------|-------------------------|--------------------| -----------------| -| Authentication | JWT Token (@security-expert) | Session-Cookie (@system-architect) | Stateless API support for multi-platform | System Architect noted session performance benefits | -| UI Framework | React (@ui-designer) | Vue.js (@subject-matter-expert) | Team expertise and ecosystem maturity | Subject Matter Expert preferred Vue for learning curve | - -*This section preserves decision context and rejected alternatives for future reference.* - -## Requirements & Acceptance Criteria -### Functional Requirements -| ID | Description | Rationale Summary | Source | Priority | Acceptance | Dependencies | -|----|-------------|-------------------|--------|----------|------------|--------------| -| FR-01 | User authentication | Enable secure multi-platform access | @product-manager/analysis.md | High | User can login via email/password | None | -| FR-02 | Data export | User-requested analytics feature | @product-owner/analysis.md | Medium | Export to CSV/JSON | FR-01 | - -### Non-Functional Requirements -| ID | Description | Rationale Summary | Target | Validation | Source | -|----|-------------|-------------------|--------|------------|--------| -| NFR-01 | Response time | UX research shows <200ms critical | <200ms | Load testing | @ux-expert/analysis.md | -| NFR-02 | Data encryption | Compliance requirement | AES-256 | Security audit | @security-expert/analysis.md | - -### Business Requirements -| ID | Description | Rationale Summary | Value | Success Metric | Source | -|----|-------------|-------------------|-------|----------------|--------| -| BR-01 | User retention | Market analysis shows engagement gap | High | 80% 30-day retention | @product-manager/analysis.md | -| BR-02 | Revenue growth | Business case justification | High | 25% MRR increase | @product-owner/analysis.md | - -## Design Specifications -### UI/UX Guidelines -**Consolidated from**: @ui-designer/analysis.md, @ux-expert/analysis.md -- Component specifications and interaction patterns -- Visual design system and accessibility requirements -- User flow and interface specifications - -### Architecture Design -**Consolidated from**: @system-architect/analysis.md, @data-architect/analysis.md -- System architecture and component interactions -- Data flow and storage strategy -- Technology stack decisions - -### Domain Expertise & Standards -**Consolidated from**: @subject-matter-expert/analysis.md -- Industry standards and best practices -- Compliance requirements and regulations -- Technical quality and domain-specific patterns - -## Process & Collaboration Concerns -**Consolidated from**: @scrum-master/analysis.md, @product-owner/analysis.md - -### Team Capability Assessment -| Required Skill | Current Level | Gap Analysis | Mitigation Strategy | Reference | -|----------------|---------------|--------------|---------------------|-----------| -| Kubernetes | Intermediate | Need advanced knowledge | Training + external consultant | @scrum-master/analysis.md | -| React Hooks | Advanced | Team ready | None | @scrum-master/analysis.md | - -### Process Risks -| Risk | Impact | Probability | Mitigation | Owner | -|------|--------|-------------|------------|-------| -| Cross-team API dependency | High | Medium | Early API contract definition | @scrum-master/analysis.md | -| UX-Dev alignment gap | Medium | High | Weekly design sync meetings | @ux-expert/analysis.md | - -### Collaboration Patterns -- **Design-Dev Pairing**: UI Designer and Frontend Dev pair programming for complex interactions -- **Architecture Reviews**: Weekly arch review for system-level decisions -- **User Testing Cadence**: Bi-weekly UX testing sessions with real users -- **Reference**: @scrum-master/analysis.md#collaboration - -### Timeline Constraints -- **Blocking Dependencies**: Project-X API must complete before Phase 2 -- **Resource Constraints**: Only 2 backend developers available in Q1 -- **External Dependencies**: Third-party OAuth provider integration timeline -- **Reference**: @scrum-master/analysis.md#constraints - -## Implementation Roadmap (High-Level) -### Development Phases -**Phase 1** (0-3 months): Foundation and core features -**Phase 2** (3-6 months): Advanced features and integrations -**Phase 3** (6+ months): Optimization and innovation - -### Technical Guidelines -- Development standards and code organization -- Testing strategy and quality assurance -- Deployment and monitoring approach - -### Feature Grouping (Epic-Level) -- High-level feature grouping and prioritization -- Epic-level dependencies and sequencing -- Strategic milestones and release planning - -**Note**: Detailed task breakdown into executable work items is handled by `/workflow:plan` → `IMPL_PLAN.md` - -## Risk Assessment & Mitigation -### Critical Risks Identified -1. **Risk**: Description | **Mitigation**: Strategy -2. **Risk**: Description | **Mitigation**: Strategy - -### Success Factors -- Key factors for implementation success -- Continuous monitoring requirements -- Quality gates and validation checkpoints - ---- -*Complete implementation specification consolidating all role perspectives into actionable guidance* -``` +**Agent Usage**: The action-planning-agent loads this template to understand expected structure and quality standards. ## 🔄 **Session Integration** @@ -400,98 +307,39 @@ Upon completion, update `workflow-session.json`: ## ✅ **Quality Assurance** -### Required Synthesis Elements -- [ ] Integration of all available role analyses with comprehensive coverage -- [ ] **Key Designs & Decisions**: Architecture diagrams, user journey maps, ADRs documented -- [ ] **Controversial Points**: Disagreement points, alternatives, and decision rationale captured -- [ ] **Process Concerns**: Team capability gaps, process risks, collaboration patterns identified -- [ ] Quantified priority recommendation matrix with evaluation criteria -- [ ] Actionable implementation plan with phased approach -- [ ] Comprehensive risk assessment with mitigation strategies +Verify synthesis output meets these standards (detailed criteria in `synthesis-role.md` template): -### Synthesis Analysis Quality Standards -- [ ] **Completeness**: Integrates all available role analyses without gaps -- [ ] **Visual Clarity**: Key diagrams (architecture, data model, user journey) included via Mermaid or images -- [ ] **Decision Transparency**: Documents not just decisions, but alternatives and why they were rejected -- [ ] **Insight Generation**: Identifies cross-role patterns and deep insights -- [ ] **Actionability**: Provides specific, executable recommendations with rationale -- [ ] **Balance**: Considers all role perspectives, including process-oriented roles (Scrum Master) -- [ ] **Forward-Looking**: Includes long-term strategic and innovation considerations +### Content Completeness +- [ ] All discovered role analyses integrated without gaps +- [ ] Key designs documented (architecture diagrams, ADRs, user journeys via Mermaid) +- [ ] Controversial points captured with alternatives and rationale +- [ ] Process concerns included (team skills, risks, collaboration patterns) +- [ ] Requirements documented (Functional, Non-Functional, Business) with sources -### Output Validation Criteria -- [ ] **Priority-Based**: Recommendations prioritized using multi-dimensional evaluation -- [ ] **Context-Rich**: Each requirement includes rationale summary for immediate understanding -- [ ] **Resource-Aware**: Team skill gaps and constraints explicitly documented -- [ ] **Risk-Managed**: Both technical and process risks captured with mitigation strategies -- [ ] **Measurable Success**: Clear success metrics and monitoring frameworks -- [ ] **Clear Actions**: Specific next steps with assigned responsibilities and timelines - -### Integration Excellence Standards -- [ ] **Cross-Role Synthesis**: Successfully identifies and documents role perspective conflicts -- [ ] **No Role Marginalization**: Process, UX, and compliance concerns equally visible as functional requirements -- [ ] **Strategic Coherence**: Recommendations form coherent strategic direction -- [ ] **Implementation Readiness**: Plans detailed enough for immediate execution, with clear handoff to IMPL_PLAN.md -- [ ] **Stakeholder Alignment**: Addresses needs and concerns of all key stakeholders -- [ ] **Decision Traceability**: Every major decision traceable to source role analysis via @ references -- [ ] **Continuous Improvement**: Establishes framework for ongoing optimization and learning +### Analysis Quality +- [ ] Cross-role synthesis identifies consensus and conflicts +- [ ] Decision transparency documents both adopted and rejected alternatives +- [ ] Priority recommendations with multi-dimensional evaluation +- [ ] Implementation roadmap with phased approach +- [ ] Risk assessment with mitigation strategies +- [ ] @ references to source role analyses throughout ## 🚀 **Recommended Next Steps** -After synthesis completion, follow this recommended workflow: +After synthesis completion, proceed to action planning: -### Option 1: Standard Planning Workflow (Recommended) +### Standard Workflow (Recommended) ```bash -# Step 1: Verify conceptual clarity (Quality Gate) -/workflow:concept-verify --session WFS-{session-id} -# → Interactive Q&A (up to 5 questions) to clarify ambiguities in synthesis - -# Step 2: Proceed to action planning (after concept verification) -/workflow:plan --session WFS-{session-id} -# → Generates IMPL_PLAN.md and task.json files - -# Step 3: Verify action plan quality (Quality Gate) -/workflow:action-plan-verify --session WFS-{session-id} -# → Read-only analysis to catch issues before execution - -# Step 4: Start implementation -/workflow:execute --session WFS-{session-id} +/workflow:concept-clarify --session WFS-{session-id} # Optional: Clarify ambiguities +/workflow:plan --session WFS-{session-id} # Generate IMPL_PLAN.md and tasks +/workflow:action-plan-verify --session WFS-{session-id} # Optional: Verify plan quality +/workflow:execute --session WFS-{session-id} # Start implementation ``` -### Option 2: TDD Workflow +### TDD Workflow ```bash -# Step 1: Verify conceptual clarity -/workflow:concept-verify --session WFS-{session-id} - -# Step 2: Generate TDD task chains (RED-GREEN-REFACTOR) +/workflow:concept-clarify --session WFS-{session-id} # Optional: Clarify ambiguities /workflow:tdd-plan --session WFS-{session-id} "Feature description" - -# Step 3: Verify TDD plan quality -/workflow:action-plan-verify --session WFS-{session-id} - -# Step 4: Execute TDD workflow +/workflow:action-plan-verify --session WFS-{session-id} # Optional: Verify plan quality /workflow:execute --session WFS-{session-id} ``` - -### Quality Gates Explained - -**`/workflow:concept-verify`** (Phase 2 - After Brainstorming): -- **Purpose**: Detect and resolve conceptual ambiguities before detailed planning -- **Time**: 10-20 minutes (interactive) -- **Value**: Reduces downstream rework by 40-60% -- **Output**: Updated synthesis-specification.md with clarifications - -**`/workflow:action-plan-verify`** (Phase 4 - After Planning): -- **Purpose**: Validate IMPL_PLAN.md and task.json consistency and completeness -- **Time**: 5-10 minutes (read-only analysis) -- **Value**: Prevents execution of flawed plans, saves 2-5 days -- **Output**: Verification report with actionable recommendations - -### Skip Verification? (Not Recommended) - -If you want to skip verification and proceed directly: -```bash -/workflow:plan --session WFS-{session-id} -/workflow:execute --session WFS-{session-id} -``` - -⚠️ **Warning**: Skipping verification increases risk of late-stage issues and rework. diff --git a/.claude/workflows/cli-templates/planning-roles/synthesis-role.md b/.claude/workflows/cli-templates/planning-roles/synthesis-role.md new file mode 100644 index 00000000..26877a6a --- /dev/null +++ b/.claude/workflows/cli-templates/planning-roles/synthesis-role.md @@ -0,0 +1,393 @@ +# Synthesis Role Template + +## Purpose +Generate comprehensive synthesis-specification.md that consolidates all role perspectives from brainstorming into actionable implementation specification. + +## Role Focus +- **Cross-Role Integration**: Synthesize insights from all participating roles +- **Decision Transparency**: Document both adopted and rejected alternatives +- **Process Integration**: Include team capabilities, risks, and collaboration patterns +- **Visual Documentation**: Key diagrams via Mermaid (architecture, data model, user journey) +- **Priority Matrix**: Quantified recommendations with multi-dimensional evaluation +- **Actionable Planning**: Phased implementation roadmap with clear next steps + +## Document Structure Template + +### synthesis-specification.md + +```markdown +# [Topic] - Integrated Implementation Specification + +**Framework Reference**: @topic-framework.md | **Generated**: [timestamp] | **Session**: WFS-[topic-slug] +**Source Integration**: All brainstorming role perspectives consolidated +**Document Type**: Requirements & Design Specification (WHAT to build) + +--- + +## Executive Summary + +Provide strategic overview covering: +- **Key Insights**: Major findings from cross-role analysis +- **Breakthrough Opportunities**: Innovation opportunities identified +- **Implementation Priorities**: High-level prioritization with rationale +- **Strategic Direction**: Recommended approach and vision + +Include metrics from role synthesis: +- Roles synthesized: [count] +- Requirements captured: [FR/NFR/BR counts] +- Controversial decisions: [count] +- Risk factors identified: [count] + +--- + +## Key Designs & Decisions + +### Core Architecture Diagram +```mermaid +graph TD + A[Component A] --> B[Component B] + B --> C[Component C] +``` +*Reference: @system-architect/analysis.md#architecture-diagram* + +### User Journey Map +![User Journey](./assets/user-journey.png) +*Reference: @ux-expert/analysis.md#user-journey* + +### Data Model Overview +```mermaid +erDiagram + USER ||--o{ ORDER : places + ORDER ||--|{ LINE-ITEM : contains +``` +*Reference: @data-architect/analysis.md#data-model* + +### Architecture Decision Records (ADRs) + +**ADR-01: [Decision Title]** +- **Context**: Background and problem statement +- **Decision**: Chosen approach +- **Rationale**: Why this approach was selected +- **Consequences**: Expected impacts and tradeoffs +- **Reference**: @[role]/analysis.md#adr-01 + +[Repeat for each major architectural decision] + +--- + +## Controversial Points & Alternatives + +Document disagreements and alternative approaches considered: + +| Point | Adopted Solution | Alternative Solution(s) | Decision Rationale | Dissenting Roles | +|-------|------------------|-------------------------|--------------------| -----------------| +| Authentication | JWT Token (@security-expert) | Session-Cookie (@system-architect) | Stateless API support for multi-platform | System Architect noted session performance benefits | +| UI Framework | React (@ui-designer) | Vue.js (@subject-matter-expert) | Team expertise and ecosystem maturity | Subject Matter Expert preferred Vue for learning curve | + +*This section preserves decision context and rejected alternatives for future reference.* + +**Analysis Guidelines**: +- Identify where roles disagreed on approach +- Document both solutions with equal respect +- Explain why one was chosen over the other +- Preserve dissenting perspectives for future consideration + +--- + +## Requirements & Acceptance Criteria + +### Functional Requirements + +| ID | Description | Rationale Summary | Source | Priority | Acceptance Criteria | Dependencies | +|----|-------------|-------------------|--------|----------|---------------------|--------------| +| FR-01 | User authentication | Enable secure multi-platform access | @product-manager/analysis.md | High | User can login via email/password with MFA | None | +| FR-02 | Data export | User-requested analytics feature | @product-owner/analysis.md | Medium | Export to CSV/JSON formats | FR-01 | + +**Guidelines**: +- Extract from product-manager, product-owner, and other role analyses +- Include rationale summary for immediate understanding +- Specify clear, testable acceptance criteria +- Map dependencies between requirements + +### Non-Functional Requirements + +| ID | Description | Rationale Summary | Target | Validation Method | Source | +|----|-------------|-------------------|--------|-------------------|--------| +| NFR-01 | Response time | UX research shows <200ms critical for engagement | <200ms | Load testing | @ux-expert/analysis.md | +| NFR-02 | Data encryption | Compliance requirement (GDPR, HIPAA) | AES-256 | Security audit | @security-expert/analysis.md | + +**Guidelines**: +- Extract performance, security, scalability requirements +- Include specific, measurable targets +- Reference source role for traceability + +### Business Requirements + +| ID | Description | Rationale Summary | Value | Success Metric | Source | +|----|-------------|-------------------|-------|----------------|--------| +| BR-01 | User retention | Market analysis shows engagement gap | High | 80% 30-day retention | @product-manager/analysis.md | +| BR-02 | Revenue growth | Business case justification for investment | High | 25% MRR increase | @product-owner/analysis.md | + +**Guidelines**: +- Capture business value and success metrics +- Link to product-manager and product-owner analyses + +--- + +## Design Specifications + +### UI/UX Guidelines +**Consolidated from**: @ui-designer/analysis.md, @ux-expert/analysis.md + +- **Component Specifications**: Reusable UI components and patterns +- **Interaction Patterns**: User interaction flows and behaviors +- **Visual Design System**: Colors, typography, spacing guidelines +- **Accessibility Requirements**: WCAG compliance, screen reader support +- **User Flow Specifications**: Step-by-step user journeys +- **Responsive Design**: Mobile, tablet, desktop breakpoints + +### Architecture Design +**Consolidated from**: @system-architect/analysis.md, @data-architect/analysis.md + +- **System Architecture**: High-level component architecture and interactions +- **Data Flow**: Data processing pipelines and transformations +- **Storage Strategy**: Database selection, schema design, caching +- **Technology Stack**: Languages, frameworks, infrastructure decisions +- **Integration Patterns**: Service communication, API design +- **Scalability Approach**: Horizontal/vertical scaling strategies + +### Domain Expertise & Standards +**Consolidated from**: @subject-matter-expert/analysis.md + +- **Industry Standards**: Compliance requirements (HIPAA, GDPR, etc.) +- **Best Practices**: Domain-specific proven patterns +- **Regulatory Requirements**: Legal and compliance constraints +- **Technical Quality**: Code quality, testing, documentation standards +- **Domain-Specific Patterns**: Industry-proven architectural patterns + +--- + +## Process & Collaboration Concerns +**Consolidated from**: @scrum-master/analysis.md, @product-owner/analysis.md + +### Team Capability Assessment + +| Required Skill | Current Level | Gap Analysis | Mitigation Strategy | Reference | +|----------------|---------------|--------------|---------------------|-----------| +| Kubernetes | Intermediate | Need advanced knowledge for scaling | Training + external consultant | @scrum-master/analysis.md | +| React Hooks | Advanced | Team ready | None | @scrum-master/analysis.md | +| GraphQL | Beginner | Significant gap for API layer | 2-week training + mentor pairing | @scrum-master/analysis.md | + +**Guidelines**: +- Identify all required technical skills +- Assess team's current capability level +- Document gap and mitigation plan +- Estimate timeline impact of skill gaps + +### Process Risks + +| Risk | Impact | Probability | Mitigation | Owner | Reference | +|------|--------|-------------|------------|-------|-----------| +| Cross-team API dependency | High | Medium | Early API contract definition | Tech Lead | @scrum-master/analysis.md | +| UX-Dev alignment gap | Medium | High | Weekly design sync meetings | Product Manager | @ux-expert/analysis.md | + +**Guidelines**: +- Capture both technical and process risks +- Include probability and impact assessment +- Specify concrete mitigation strategies +- Assign ownership for risk management + +### Collaboration Patterns + +Document recommended collaboration workflows: + +- **Design-Dev Pairing**: UI Designer and Frontend Dev pair programming for complex interactions +- **Architecture Reviews**: Weekly arch review for system-level decisions +- **User Testing Cadence**: Bi-weekly UX testing sessions with real users +- **Code Review Process**: PR review within 24 hours, 2 approvals required +- **Daily Standups**: 15-minute sync across all roles + +*Reference: @scrum-master/analysis.md#collaboration* + +### Timeline Constraints + +Document known constraints that affect planning: + +- **Blocking Dependencies**: Project-X API must complete before Phase 2 +- **Resource Constraints**: Only 2 backend developers available in Q1 +- **External Dependencies**: Third-party OAuth provider integration timeline (6 weeks) +- **Hard Deadlines**: MVP launch date for investor demo (Q2 end) + +*Reference: @scrum-master/analysis.md#constraints* + +--- + +## Implementation Roadmap (High-Level) + +### Development Phases + +**Phase 1** (0-3 months): Foundation and Core Features +- Infrastructure setup and basic architecture +- Core authentication and user management +- Essential functional requirements (FR-01, FR-02, FR-03) +- Foundational UI components + +**Phase 2** (3-6 months): Advanced Features and Integrations +- Advanced functional requirements +- Third-party integrations +- Analytics and reporting +- Advanced UI/UX enhancements + +**Phase 3** (6+ months): Optimization and Innovation +- Performance optimization +- Advanced analytics and ML features +- Innovation opportunities from brainstorming +- Technical debt reduction + +### Technical Guidelines + +**Development Standards**: +- Code organization and project structure +- Naming conventions and style guides +- Version control and branching strategy +- Development environment setup + +**Testing Strategy**: +- Unit testing (80% coverage minimum) +- Integration testing approach +- E2E testing for critical paths +- Performance testing benchmarks + +**Deployment Approach**: +- CI/CD pipeline configuration +- Staging and production environments +- Monitoring and alerting setup +- Rollback procedures + +### Feature Grouping (Epic-Level) + +**Epic 1: User Authentication & Authorization** +- Requirements: FR-01, FR-03, NFR-02 +- Priority: High +- Dependencies: None +- Estimated Timeline: 4 weeks + +**Epic 2: Data Management & Export** +- Requirements: FR-02, FR-05, NFR-01 +- Priority: Medium +- Dependencies: Epic 1 +- Estimated Timeline: 6 weeks + +[Continue for all major feature groups] + +**Note**: Detailed task breakdown into executable work items is handled by `/workflow:plan` → `IMPL_PLAN.md` + +--- + +## Risk Assessment & Mitigation + +### Critical Risks Identified + +**Technical Risks**: +1. **Risk**: Database scalability under projected load + - **Impact**: High (system downtime, user dissatisfaction) + - **Probability**: Medium + - **Mitigation**: Early load testing, database sharding plan, caching strategy + - **Owner**: System Architect + +2. **Risk**: Third-party API reliability and rate limits + - **Impact**: Medium (feature degradation) + - **Probability**: High + - **Mitigation**: Implement circuit breakers, fallback mechanisms, local caching + - **Owner**: Backend Lead + +**Process Risks**: +3. **Risk**: Cross-team coordination delays + - **Impact**: High (timeline slippage) + - **Probability**: Medium + - **Mitigation**: Weekly sync meetings, clear API contracts, buffer time in estimates + - **Owner**: Scrum Master + +4. **Risk**: Skill gap in new technologies + - **Impact**: Medium (quality issues, slower delivery) + - **Probability**: High + - **Mitigation**: Training program, pair programming, external consultant support + - **Owner**: Engineering Manager + +### Success Factors + +**Key factors for implementation success**: +- Strong product-engineering collaboration with weekly syncs +- Clear acceptance criteria and definition of done +- Regular user testing and feedback integration +- Proactive risk monitoring and mitigation + +**Continuous Monitoring Requirements**: +- Sprint velocity and burndown tracking +- Code quality metrics (coverage, complexity, tech debt) +- Performance metrics (response time, error rate, uptime) +- User satisfaction metrics (NPS, usage analytics) + +**Quality Gates and Validation Checkpoints**: +- Code review approval before merge +- Automated test suite passing (unit, integration, E2E) +- Security scan and vulnerability assessment +- Performance benchmark validation +- Stakeholder demo and approval before production + +--- + +*Complete implementation specification consolidating all role perspectives into actionable guidance* +``` + +## Analysis Guidelines for Agent + +### Cross-Role Synthesis Process + +1. **Load All Role Analyses**: Read topic-framework.md and all discovered */analysis.md files +2. **Extract Key Insights**: Identify main recommendations, concerns, and innovations from each role +3. **Identify Consensus Areas**: Find common themes across multiple roles +4. **Document Disagreements**: Capture controversial points where roles differ +5. **Prioritize Recommendations**: Use multi-dimensional scoring: + - Business impact (product-manager, product-owner) + - Technical feasibility (system-architect, data-architect) + - Implementation effort (scrum-master, developers) + - Risk assessment (security-expert, subject-matter-expert) +6. **Create Comprehensive Roadmap**: Synthesize into phased implementation plan + +### Quality Standards + +- **Completeness**: Integrate ALL discovered role analyses without gaps +- **Visual Clarity**: Include key diagrams (architecture, data model, user journey) via Mermaid or images +- **Decision Transparency**: Document not just decisions, but alternatives and why they were rejected +- **Insight Generation**: Identify cross-role patterns and deep insights beyond individual analyses +- **Actionability**: Provide specific, executable recommendations with clear rationale +- **Balance**: Give equal weight to all role perspectives (process, UX, compliance, functional) +- **Forward-Looking**: Include long-term strategic and innovation considerations +- **Traceability**: Every major decision links to source role analysis via @ references + +### @ Reference System + +Use @ references to link back to source role analyses: +- `@role/analysis.md` - Reference entire role analysis +- `@role/analysis.md#section` - Reference specific section +- `@topic-framework.md#point-3` - Reference framework discussion point + +### Dynamic Role Handling + +- Not all roles participate in every brainstorming session +- Synthesize only roles that produced analysis.md files +- Adapt structure based on available role perspectives +- If role missing, acknowledge gap if relevant to topic + +### Output Validation + +Before completing, verify: +- [ ] All discovered role analyses integrated +- [ ] Framework discussion points addressed across roles +- [ ] Controversial points documented with dissenting roles identified +- [ ] Process concerns (team skills, risks, collaboration) captured +- [ ] Quantified priority recommendations with evaluation criteria +- [ ] Actionable implementation plan with phased approach +- [ ] Comprehensive risk assessment with mitigation strategies +- [ ] @ references to source analyses throughout document