catlog22/Claude-Code-Workflow
1
0
Fork 0
mirror of https://github.com/catlog22/Claude-Code-Workflow.git synced 2026-02-13 02:41:50 +08:00
Code Issues Packages Projects Releases Wiki Activity

refactor: convert synthesis command to agent-based execution

Browse Source 
- Convert synthesis.md to use action-planning-agent with FLOW_CONTROL
- Create synthesis-role.md template with comprehensive document structure
- Reorganize phase sequencing: validation → discovery → update check → agent execution
- Extract task tracking as protocol section outside phase sequence
- Add explicit OUTPUT_FILE and OUTPUT_PATH to agent context
- Move cross-role analysis logic into agent responsibilities
- Simplify Quality Assurance and Next Steps sections

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
catlog22
2025-10-16 21:23:26 +08:00
parent 5e59c1d2d9
commit 7945e219f4
2 changed files with 533 additions and 292 deletions
Download Patch File Download Diff File Expand all files Collapse all files

430
.claude/commands/workflow/brainstorm/synthesis.md
View File

@@ -2,7 +2,7 @@
name: synthesis name: synthesis
description: Generate synthesis-specification.md from topic-framework and role analyses with @ references description: Generate synthesis-specification.md from topic-framework and role analyses with @ references
argument-hint: "no arguments required - synthesizes existing framework and role analyses" 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** ## 🧩 **Synthesis Document Generator**
@@ -29,15 +29,28 @@ allowed-tools: Read(*), Write(*), TodoWrite(*), Glob(*)
## ⚙️ **Execution Protocol** ## ⚙️ **Execution Protocol**
### ⚠️ Direct Execution by Main Claude ### ⚠️ Agent Execution with Flow Control
**Execution Model**: Main Claude directly executes this command without delegating to sub-agents. **Execution Model**: Uses action-planning-agent for synthesis generation with structured file loading.
**Rationale**: **Rationale**:
- **Full Context Access**: Avoids context transmission loss that occurs with Task tool delegation - **Autonomous Execution**: Agent independently loads and processes all required documents
- **Complex Cognitive Analysis**: Leverages main Claude's complete reasoning capabilities for cross-role synthesis - **Flow Control**: Structured document loading ensures systematic analysis
- **Tool Usage**: Combines Read/Write/Glob tools with main Claude's analytical intelligence - **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 ### Phase 1: Document Discovery & Validation
```bash ```bash
@@ -102,79 +115,104 @@ ELSE:
CREATE new synthesis CREATE new synthesis
``` ```
### Phase 4: Synthesis Generation Process ### Phase 4: Agent Execution with Flow Control
Initialize synthesis task tracking: **Synthesis Generation using action-planning-agent**
```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 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 Execute comprehensive synthesis generation from topic framework and role analyses
```pseudo
# Iterate over dynamically discovered role analyses
FOR each discovered_role IN participating_roles:
role_directory = brainstorm_dir + "/" + discovered_role
# Load role analysis (required) ## Context Loading
role_analysis = Read(role_directory + "/analysis.md") 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 ## Flow Control Steps
IF EXISTS(role_directory + "/recommendations.md"): 1. **load_topic_framework**
role_recommendations[discovered_role] = Read(role_directory + "/recommendations.md") - Action: Load structured topic discussion framework
END IF - Command: Read(.workflow/WFS-{session}/.brainstorming/topic-framework.md)
- Output: topic_framework_content
# Extract insights from analysis 2. **discover_role_analyses**
role_insights[discovered_role] = extract_key_insights(role_analysis) - Action: Dynamically discover all participating role analysis files
role_recommendations[discovered_role] = extract_recommendations(role_analysis) - Command: Glob(.workflow/WFS-{session}/.brainstorming/*/analysis.md)
role_concerns[discovered_role] = extract_concerns_risks(role_analysis) - Output: role_analysis_paths, participating_roles
role_diagrams[discovered_role] = identify_diagrams_and_visuals(role_analysis)
END FOR
# Log participating roles for metadata 3. **load_role_analyses**
participating_role_count = COUNT(participating_roles) - Action: Load all discovered role analysis documents
participating_role_names = participating_roles - Command: Read(each path from role_analysis_paths)
``` - Output: role_analyses_content
#### 5.2 Cross-Role Insight Analysis 4. **check_existing_synthesis**
```pseudo - Action: Check if synthesis-specification.md already exists
# Consensus identification (across all participating roles) - Command: Read(.workflow/WFS-{session}/.brainstorming/synthesis-specification.md) [if exists]
consensus_areas = identify_common_themes(role_insights) - Output: existing_synthesis_content [optional]
agreement_matrix = create_agreement_matrix(role_recommendations)
# Disagreement analysis (track which specific roles disagree) 5. **load_session_metadata**
disagreement_areas = identify_conflicting_views(role_insights) - Action: Load session metadata and context
tension_points = analyze_role_conflicts(role_recommendations) - Command: Read(.workflow/WFS-{session}/workflow-session.json)
FOR each conflict IN disagreement_areas: - Output: session_context
conflict.dissenting_roles = identify_dissenting_roles(conflict)
END FOR
# Innovation opportunity extraction 6. **load_synthesis_template**
innovation_opportunities = extract_breakthrough_ideas(role_insights) - Action: Load synthesis role template for structure and guidelines
synergy_opportunities = identify_cross_role_synergies(role_insights) - Command: Read(~/.claude/workflows/cli-templates/planning-roles/synthesis-role.md)
``` - Output: synthesis_template_guidelines
#### 5.3 Priority and Decision Matrix Generation ## Synthesis Requirements
```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) ### Core Integration
END FOR **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
SORT recommendations BY priority_score DESC ### 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** ## 📊 **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 # ★ 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. **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). **Scope**: High-level features, requirements, and design specifications. Does NOT include executable task breakdown (that's IMPL_PLAN.md's responsibility).
```markdown **Template Reference**: Complete document structure and content guidelines available in `synthesis-role.md` template, including:
# [Topic] - Integrated Implementation Specification - 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] **Agent Usage**: The action-planning-agent loads this template to understand expected structure and quality standards.
**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*
```
## 🔄 **Session Integration** ## 🔄 **Session Integration**
@@ -400,98 +307,39 @@ Upon completion, update `workflow-session.json`:
## ✅ **Quality Assurance** ## ✅ **Quality Assurance**
### Required Synthesis Elements Verify synthesis output meets these standards (detailed criteria in `synthesis-role.md` template):
- [ ] 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
### Synthesis Analysis Quality Standards ### Content Completeness
- [ ] **Completeness**: Integrates all available role analyses without gaps - [ ] All discovered role analyses integrated without gaps
- [ ] **Visual Clarity**: Key diagrams (architecture, data model, user journey) included via Mermaid or images - [ ] Key designs documented (architecture diagrams, ADRs, user journeys via Mermaid)
- [ ] **Decision Transparency**: Documents not just decisions, but alternatives and why they were rejected - [ ] Controversial points captured with alternatives and rationale
- [ ] **Insight Generation**: Identifies cross-role patterns and deep insights - [ ] Process concerns included (team skills, risks, collaboration patterns)
- [ ] **Actionability**: Provides specific, executable recommendations with rationale - [ ] Requirements documented (Functional, Non-Functional, Business) with sources
- [ ] **Balance**: Considers all role perspectives, including process-oriented roles (Scrum Master)
- [ ] **Forward-Looking**: Includes long-term strategic and innovation considerations
### Output Validation Criteria ### Analysis Quality
- [ ] **Priority-Based**: Recommendations prioritized using multi-dimensional evaluation - [ ] Cross-role synthesis identifies consensus and conflicts
- [ ] **Context-Rich**: Each requirement includes rationale summary for immediate understanding - [ ] Decision transparency documents both adopted and rejected alternatives
- [ ] **Resource-Aware**: Team skill gaps and constraints explicitly documented - [ ] Priority recommendations with multi-dimensional evaluation
- [ ] **Risk-Managed**: Both technical and process risks captured with mitigation strategies - [ ] Implementation roadmap with phased approach
- [ ] **Measurable Success**: Clear success metrics and monitoring frameworks - [ ] Risk assessment with mitigation strategies
- [ ] **Clear Actions**: Specific next steps with assigned responsibilities and timelines - [ ] @ references to source role analyses throughout
### 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
## 🚀 **Recommended Next Steps** ## 🚀 **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 ```bash
# Step 1: Verify conceptual clarity (Quality Gate) /workflow:concept-clarify --session WFS-{session-id} # Optional: Clarify ambiguities
/workflow:concept-verify --session WFS-{session-id} /workflow:plan --session WFS-{session-id} # Generate IMPL_PLAN.md and tasks
# → Interactive Q&A (up to 5 questions) to clarify ambiguities in synthesis /workflow:action-plan-verify --session WFS-{session-id} # Optional: Verify plan quality
/workflow:execute --session WFS-{session-id} # Start implementation
# 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}
``` ```
### Option 2: TDD Workflow ### TDD Workflow
```bash ```bash
# Step 1: Verify conceptual clarity /workflow:concept-clarify --session WFS-{session-id} # Optional: Clarify ambiguities
/workflow:concept-verify --session WFS-{session-id}
# Step 2: Generate TDD task chains (RED-GREEN-REFACTOR)
/workflow:tdd-plan --session WFS-{session-id} "Feature description" /workflow:tdd-plan --session WFS-{session-id} "Feature description"
/workflow:action-plan-verify --session WFS-{session-id} # Optional: Verify plan quality
# Step 3: Verify TDD plan quality
/workflow:action-plan-verify --session WFS-{session-id}
# Step 4: Execute TDD workflow
/workflow:execute --session WFS-{session-id} /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.

393
.claude/workflows/cli-templates/planning-roles/synthesis-role.md Normal file
View File

@@ -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