mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-05 01:50:27 +08:00
refactor: convert synthesis command to agent-based execution
- 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
@@ -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
|
||||
|
||||
*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.
|
||||
|
||||
393
.claude/workflows/cli-templates/planning-roles/synthesis-role.md
Normal file
393
.claude/workflows/cli-templates/planning-roles/synthesis-role.md
Normal 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
|
||||
|
||||
*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
|
||||
Reference in New Issue
Block a user