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

refactor: Enhance synthesis.md with comprehensive improvements

Browse Source 
Major improvements to brainstorm synthesis specification:

1. Output Definition Unification (Critical)
   - Remove synthesis-report.md references
   - Unify to synthesis-specification.md as single output
   - Update all metadata and descriptions

2. Execution Model Clarification (High)
   - Change "Direct Execution Only" to "Direct Execution by Main Claude"
   - Clarify: Main Claude + Read/Write/Glob + cognitive analysis
   - Emphasize avoiding context transmission loss

3. Dynamic Role Discovery (High)
   - Replace hardcoded 9-role list with runtime discovery
   - Scan .brainstorming/* directories for actual analysis.md files
   - Support flexible participation (1 to 9+ roles)
   - Update metadata to reflect dynamic role counts

4. Enhanced Document Structure (Critical)
   - Add "Key Designs & Decisions" section
     * Core architecture diagrams (Mermaid)
     * User journey maps (images)
     * Data model overview (ERD)
     * Architecture Decision Records (ADRs)

   - Add "Controversial Points & Alternatives" section
     * Document disagreements and rejected alternatives
     * Preserve decision context and rationale
     * Track dissenting roles

   - Add "Process & Collaboration Concerns" section
     * Team capability assessment
     * Process risks and mitigation
     * Collaboration patterns
     * Timeline constraints

5. Requirements Table Enhancement (Medium)
   - Add "Rationale Summary" column to all requirement tables
   - Reduce over-reliance on @ references
   - Provide immediate context for better readability

6. Responsibility Clarification
   - synthesis-specification.md: Defines "WHAT" (requirements, design)
   - IMPL_PLAN.md: Defines "HOW" (executable tasks)
   - Clear handoff between brainstorm and planning phases

7. Updated Quality Assurance Standards
   - Visual Clarity: Diagrams required
   - Decision Transparency: Alternatives documented
   - No Role Marginalization: Process roles equally visible
   - Context-Rich: Rationale included
   - Decision Traceability: @ references maintained

Related: plan.md improvements for auto-continue clarity and synthesis integration

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

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
catlog22
2025-10-04 16:40:06 +08:00
parent 9a28866837
commit 7f4dfe51fd
1 changed files with 134 additions and 33 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -13,12 +13,16 @@ allowed-tools: Read(*), Write(*), TodoWrite(*), Glob(*)
### Core Function
**Specialized command for generating synthesis-specification.md** that integrates topic-framework.md and all role analysis.md files using @ reference system. Creates comprehensive implementation specification with cross-role insights.
**Dynamic Role Discovery**: Automatically detects which roles participated in brainstorming by scanning for `*/analysis.md` files. Synthesizes only actual participating roles, not predefined lists.
### Primary Capabilities
- **Framework Integration**: Reference topic-framework.md discussion points across all roles
- **Role Analysis Integration**: Consolidate all role/analysis.md files using @ references
- **Cross-Framework Comparison**: Compare how each role addressed framework discussion points
- **Dynamic Role Discovery**: Automatically identifies participating roles at runtime
- **Framework Integration**: Reference topic-framework.md discussion points across all discovered roles
- **Role Analysis Integration**: Consolidate all discovered role/analysis.md files using @ references
- **Cross-Framework Comparison**: Compare how each participating role addressed framework discussion points
- **@ Reference System**: Create structured references to source documents
- **Update Detection**: Smart updates when new role analyses are added
- **Flexible Participation**: Supports any subset of available roles (1 to 9+)
### Document Integration Model
**Three-Document Reference System**:
@@ -58,16 +62,33 @@ IF NOT EXISTS:
### Phase 2: Role Analysis Discovery
```bash
# Discover available role analyses
# Dynamically discover available role analyses
SCAN_DIRECTORY: .workflow/WFS-{session}/.brainstorming/
FIND_ANALYSES: [
*/analysis.md files in role directories
Scan all subdirectories for */analysis.md files
Extract role names from directory names
]
# Available roles (for reference, actual participation is dynamic):
# - product-manager
# - product-owner
# - scrum-master
# - system-architect
# - ui-designer
# - ux-expert
# - data-architect
# - subject-matter-expert
# - test-strategist
LOAD_DOCUMENTS: {
"topic_framework": topic-framework.md,
"role_analyses": [discovered analysis.md files],
"role_analyses": [dynamically discovered analysis.md files],
"participating_roles": [extract role names from discovered directories],
"existing_synthesis": synthesis-specification.md (if exists)
}
# Note: Not all roles participate in every brainstorming session
# Only synthesize roles that actually produced analysis.md files
```
### Phase 3: Update Mechanism Check
@@ -96,37 +117,55 @@ Initialize synthesis task tracking:
]
```
### Phase 4: Cross-Role Analysis Execution
### Phase 5: Cross-Role Analysis Execution
#### 4.1 Data Collection and Preprocessing
**Dynamic Role Processing**: The number and types of roles are determined at runtime based on actual analysis.md files discovered in Phase 2.
#### 5.1 Data Collection and Preprocessing
```pseudo
FOR each role_directory in brainstorming_roles:
IF role_directory exists:
role_analysis = Read(role_directory + "/analysis.md")
role_recommendations = Read(role_directory + "/recommendations.md") IF EXISTS
role_insights[role] = extract_key_insights(role_analysis)
role_recommendations[role] = extract_recommendations(role_analysis)
role_concerns[role] = extract_concerns_risks(role_analysis)
# Iterate over dynamically discovered role analyses
FOR each discovered_role IN participating_roles:
role_directory = brainstorm_dir + "/" + discovered_role
# Load role analysis (required)
role_analysis = Read(role_directory + "/analysis.md")
# Load optional artifacts if present
IF EXISTS(role_directory + "/recommendations.md"):
role_recommendations[discovered_role] = Read(role_directory + "/recommendations.md")
END IF
# 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
# Log participating roles for metadata
participating_role_count = COUNT(participating_roles)
participating_role_names = participating_roles
```
#### 4.2 Cross-Role Insight Analysis
#### 5.2 Cross-Role Insight Analysis
```pseudo
# Consensus identification
# Consensus identification (across all participating roles)
consensus_areas = identify_common_themes(role_insights)
agreement_matrix = create_agreement_matrix(role_recommendations)
# Disagreement analysis
# 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
# Innovation opportunity extraction
innovation_opportunities = extract_breakthrough_ideas(role_insights)
synergy_opportunities = identify_cross_role_synergies(role_insights)
```
#### 4.3 Priority and Decision Matrix Generation
#### 5.3 Priority and Decision Matrix Generation
```pseudo
# Create comprehensive evaluation matrix
FOR each recommendation:
@@ -242,6 +281,33 @@ erDiagram
- 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
@@ -278,6 +344,9 @@ erDiagram
### Streamlined Status Synchronization
Upon completion, update `workflow-session.json`:
**Dynamic Role Participation**: The `participating_roles` and `roles_synthesized` values are determined at runtime based on actual analysis.md files discovered.
```json
{
"phases": {
@@ -285,22 +354,47 @@ Upon completion, update `workflow-session.json`:
"status": "completed",
"synthesis_completed": true,
"completed_at": "timestamp",
"participating_roles": ["product-manager", "product-owner", "scrum-master", "system-architect", "ui-designer", "ux-expert", "data-architect", "subject-matter-expert", "test-strategist"],
"participating_roles": ["<dynamically-discovered-role-1>", "<dynamically-discovered-role-2>", "..."],
"available_roles": ["product-manager", "product-owner", "scrum-master", "system-architect", "ui-designer", "ux-expert", "data-architect", "subject-matter-expert", "test-strategist"],
"consolidated_output": {
"synthesis_specification": ".workflow/WFS-{topic}/.brainstorming/synthesis-specification.md"
},
"synthesis_quality": {
"role_integration": "complete",
"requirement_coverage": "comprehensive",
"decision_transparency": "alternatives_documented",
"process_risks_identified": true,
"implementation_readiness": "ready"
},
"content_metrics": {
"roles_synthesized": 9,
"functional_requirements": 25,
"non_functional_requirements": 12,
"business_requirements": 8,
"implementation_phases": 3,
"risk_factors_identified": 8
"roles_synthesized": "<COUNT(participating_roles)>",
"functional_requirements": "<dynamic-count>",
"non_functional_requirements": "<dynamic-count>",
"business_requirements": "<dynamic-count>",
"architecture_decisions": "<dynamic-count>",
"controversial_points": "<dynamic-count>",
"diagrams_included": "<dynamic-count>",
"process_risks": "<dynamic-count>",
"team_skill_gaps": "<dynamic-count>",
"implementation_phases": "<dynamic-count>",
"risk_factors_identified": "<dynamic-count>"
}
}
}
}
```
**Example with actual values**:
```json
{
"phases": {
"BRAINSTORM": {
"status": "completed",
"participating_roles": ["product-manager", "system-architect", "ui-designer", "ux-expert", "scrum-master"],
"content_metrics": {
"roles_synthesized": 5,
"functional_requirements": 18,
"controversial_points": 2
}
}
}
@@ -311,28 +405,35 @@ Upon completion, update `workflow-session.json`:
### Required Synthesis Elements
- [ ] Integration of all available role analyses with comprehensive coverage
- [ ] Clear identification of consensus areas and disagreement points
- [ ] **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
- [ ] **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 and next steps
- [ ] **Balance**: Considers all role perspectives and addresses concerns
- [ ] **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
### Output Validation Criteria
- [ ] **Priority-Based**: Recommendations prioritized using multi-dimensional evaluation
- [ ] **Resource-Aware**: Implementation plans consider resource and time constraints
- [ ] **Risk-Managed**: Comprehensive risk assessment with mitigation strategies
- [ ] **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 resolves role perspective conflicts
- [ ] **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 are detailed enough for immediate execution
- [ ] **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