mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-13 02:41:50 +08:00
Refactor workflow to replace synthesis-specification.md with role analysis documents
- Updated references in various workflow commands to utilize role analysis documents instead of synthesis-specification.md. - Modified CLI templates and command references to reflect the new architecture and document structure. - Introduced conflict-resolution command to analyze and resolve conflicts between implementation plans and existing codebase. - Deprecated synthesis role template and provided migration guidance for transitioning to the new role analysis approach.
This commit is contained in:
catlog22
@@ -1,229 +1,556 @@
|
||||
---
|
||||
name: artifacts
|
||||
description: Generate role-specific topic-framework.md dynamically based on selected roles
|
||||
argument-hint: "topic or challenge description for framework generation"
|
||||
allowed-tools: TodoWrite(*), Read(*), Write(*), Bash(*), Glob(*)
|
||||
description: Multi-phase clarification workflow generating confirmed guidance specification
|
||||
argument-hint: "topic or challenge description for clarification"
|
||||
allowed-tools: TodoWrite(*), Read(*), Write(*), AskUserQuestion(*), Bash(*), Glob(*)
|
||||
---
|
||||
|
||||
# Topic Framework Generator Command
|
||||
# Brainstorm Clarification Command
|
||||
|
||||
## Usage
|
||||
## 📖 Overview
|
||||
|
||||
### Purpose
|
||||
**Multi-phase interactive clarification workflow** that collects user decisions through intelligent questioning, generating a **confirmed guidance specification** (declarative statements) rather than open-ended questions (interrogative sentences).
|
||||
|
||||
### Core Philosophy Change
|
||||
- ❌ **OLD**: Generate guidance-specification.md with open questions ("What are...?", "How should...?")
|
||||
- ✅ **NEW**: Multi-step clarification → Generate guidance-specification.md with confirmed decisions
|
||||
|
||||
### User Intent Preservation
|
||||
Topic description is stored in session metadata and serves as authoritative reference throughout workflow lifecycle.
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Usage
|
||||
|
||||
### Basic Command
|
||||
```bash
|
||||
/workflow:brainstorm:artifacts "<topic>" [--roles "role1,role2,role3"]
|
||||
/workflow:brainstorm:artifacts "<topic>"
|
||||
```
|
||||
|
||||
**Recommended Structured Format**:
|
||||
### Recommended Structured Format
|
||||
```bash
|
||||
/workflow:brainstorm:artifacts "GOAL: [objective] SCOPE: [boundaries] CONTEXT: [background]" [--roles "..."]
|
||||
/workflow:brainstorm:artifacts "GOAL: [objective] SCOPE: [boundaries] CONTEXT: [background]"
|
||||
```
|
||||
|
||||
## Purpose
|
||||
**Generate dynamic topic-framework.md tailored to selected roles**. Creates role-specific discussion frameworks that address relevant perspectives. If no roles specified, generates comprehensive framework covering common analysis areas.
|
||||
|
||||
**⚠️ User Intent Preservation**: Topic description is stored in session metadata and serves as authoritative reference throughout workflow lifecycle.
|
||||
|
||||
## Role-Based Framework Generation
|
||||
|
||||
**Dynamic Generation**: Framework content adapts based on selected roles
|
||||
- **With roles**: Generate targeted discussion points for specified roles only
|
||||
- **Without roles**: Generate comprehensive framework covering all common areas
|
||||
|
||||
## Core Workflow
|
||||
|
||||
### Topic Framework Generation Process
|
||||
|
||||
**Phase 1: Session Management** ⚠️ FIRST STEP
|
||||
- **Active session detection**: Check `.workflow/.active-*` markers
|
||||
- **Session selection**: Prompt user if multiple active sessions found
|
||||
- **Auto-creation**: Create `WFS-[topic-slug]` only if no active session exists
|
||||
- **Framework check**: Check if `topic-framework.md` exists (update vs create mode)
|
||||
|
||||
**Phase 2: Role Analysis** ⚠️ NEW
|
||||
- **Parse roles parameter**: Extract roles from `--roles "role1,role2,role3"` if provided
|
||||
- **Role validation**: Verify each role is valid (matches available role commands)
|
||||
- **Store role list**: Save selected roles to session metadata for reference
|
||||
- **Default behavior**: If no roles specified, use comprehensive coverage
|
||||
|
||||
**Phase 3: Dynamic Topic Analysis**
|
||||
- **Scope definition**: Define topic boundaries and objectives
|
||||
- **Stakeholder identification**: Identify key users and stakeholders based on selected roles
|
||||
- **Requirements gathering**: Extract requirements relevant to selected roles
|
||||
- **Context collection**: Gather context appropriate for role perspectives
|
||||
|
||||
**Phase 4: Role-Specific Framework Generation**
|
||||
- **Discussion points creation**: Generate 3-5 discussion areas **tailored to selected roles**
|
||||
- **Role-targeted questions**: Create questions specifically for chosen roles
|
||||
- **Framework document**: Generate `topic-framework.md` with role-specific sections
|
||||
- **Validation check**: Ensure framework addresses all selected role perspectives
|
||||
|
||||
**Phase 5: Metadata Storage**
|
||||
- **Save role assignment**: Store selected roles in session metadata
|
||||
- **Framework versioning**: Track which roles framework addresses
|
||||
- **Update tracking**: Maintain role evolution if framework updated
|
||||
|
||||
## Implementation Standards
|
||||
|
||||
### Discussion-Driven Analysis
|
||||
**Interactive Approach**: Direct conversation and exploration without predefined role constraints
|
||||
|
||||
**Process Flow**:
|
||||
1. **Topic introduction**: Understanding scope and context
|
||||
2. **Exploratory questioning**: Open-ended investigation
|
||||
3. **Component identification**: Breaking down into manageable pieces
|
||||
4. **Relationship analysis**: Understanding connections and dependencies
|
||||
5. **Documentation generation**: Structured capture of insights
|
||||
|
||||
**Key Areas of Investigation**:
|
||||
- **Functional aspects**: What the topic needs to accomplish
|
||||
- **Technical considerations**: Implementation constraints and requirements
|
||||
- **User perspectives**: How different stakeholders are affected
|
||||
- **Business implications**: Cost, timeline, and strategic considerations
|
||||
- **Risk assessment**: Potential challenges and mitigation strategies
|
||||
|
||||
### Document Generation Standards
|
||||
|
||||
**Always Created**:
|
||||
- **discussion-summary.md**: Main conversation points and key insights
|
||||
- **component-analysis.md**: Detailed breakdown of topic components
|
||||
|
||||
## Document Generation
|
||||
|
||||
**Primary Output**: Single structured `topic-framework.md` document
|
||||
|
||||
**Document Structure**:
|
||||
### Example
|
||||
```bash
|
||||
/workflow:brainstorm:artifacts "GOAL: Build real-time collaboration platform SCOPE: Support 100 concurrent users CONTEXT: Existing monolithic architecture needs refactoring"
|
||||
```
|
||||
.workflow/WFS-[topic]/.brainstorming/
|
||||
└── topic-framework.md # ★ STRUCTURED FRAMEWORK DOCUMENT
|
||||
```
|
||||
|
||||
**Note**: `workflow-session.json` is located at `.workflow/WFS-[topic]/workflow-session.json` (session root), not inside `.brainstorming/`.
|
||||
|
||||
## Framework Template Structures
|
||||
|
||||
### Dynamic Role-Based Framework
|
||||
|
||||
Framework content adapts based on `--roles` parameter:
|
||||
|
||||
#### Option 1: Specific Roles Provided
|
||||
```markdown
|
||||
# [Topic] - Discussion Framework
|
||||
|
||||
## Topic Overview
|
||||
- **Scope**: [Topic boundaries relevant to selected roles]
|
||||
- **Objectives**: [Goals from perspective of selected roles]
|
||||
- **Context**: [Background focusing on role-specific concerns]
|
||||
- **Target Roles**: ui-designer, system-architect, subject-matter-expert
|
||||
|
||||
## Role-Specific Discussion Points
|
||||
|
||||
### For UI Designer
|
||||
1. **User Interface Requirements**
|
||||
- What interface components are needed?
|
||||
- What user interactions must be supported?
|
||||
- What visual design considerations apply?
|
||||
|
||||
2. **User Experience Challenges**
|
||||
- What are the key user journeys?
|
||||
- What accessibility requirements exist?
|
||||
- How to balance aesthetics with functionality?
|
||||
|
||||
### For System Architect
|
||||
1. **Architecture Decisions**
|
||||
- What architectural patterns fit this solution?
|
||||
- What scalability requirements exist?
|
||||
- How does this integrate with existing systems?
|
||||
|
||||
2. **Technical Implementation**
|
||||
- What technology stack is appropriate?
|
||||
- What are the performance requirements?
|
||||
- What dependencies must be managed?
|
||||
|
||||
### For Subject Matter Expert
|
||||
1. **Domain Expertise & Standards**
|
||||
- What industry standards and best practices apply?
|
||||
- What regulatory compliance requirements exist?
|
||||
- What domain-specific patterns should be followed?
|
||||
|
||||
2. **Technical Quality & Risk**
|
||||
- What technical debt considerations exist?
|
||||
- What scalability and maintenance implications apply?
|
||||
- What knowledge transfer and documentation is needed?
|
||||
|
||||
## Cross-Role Integration Points
|
||||
- How do UI decisions impact architecture?
|
||||
- How does architecture constrain UI possibilities?
|
||||
- What domain standards affect both UI and architecture?
|
||||
|
||||
## Framework Usage
|
||||
**For Role Agents**: Address your specific section + integration points
|
||||
**Reference Format**: @../topic-framework.md in your analysis.md
|
||||
**Update Process**: Use /workflow:brainstorm:artifacts to update
|
||||
|
||||
---
|
||||
*Generated for roles: ui-designer, system-architect, subject-matter-expert*
|
||||
*Last updated: [timestamp]*
|
||||
|
||||
## 🔄 Multi-Phase Workflow
|
||||
|
||||
### Workflow Diagram
|
||||
|
||||
```
|
||||
Phase 1: Intent Classification
|
||||
│ (Understand project type and focus)
|
||||
│ → 2-3 questions, 3 choices each
|
||||
↓
|
||||
Phase 2: Role Selection
|
||||
│ (Determine participating roles)
|
||||
│ → Recommend 3-5 roles, multiSelect
|
||||
↓
|
||||
Phase 3: Role-Specific Questions
|
||||
│ (Collect professional domain decisions)
|
||||
│ → 3-5 questions per role, 3 choices each
|
||||
↓
|
||||
Phase 4: Cross-Role Clarification
|
||||
│ (Ensure inter-role consistency)
|
||||
│ → 1-2 questions per role from related role perspectives
|
||||
↓
|
||||
Phase 5: Generate Guidance Specification
|
||||
│ (Create confirmed guidance document)
|
||||
└─→ guidance-specification.md (declarative statements)
|
||||
```
|
||||
|
||||
#### Option 2: No Roles Specified (Comprehensive)
|
||||
```markdown
|
||||
# [Topic] - Discussion Framework
|
||||
|
||||
## Topic Overview
|
||||
- **Scope**: [Comprehensive topic boundaries]
|
||||
- **Objectives**: [All-encompassing goals]
|
||||
- **Context**: [Full background and constraints]
|
||||
- **Stakeholders**: [All relevant parties]
|
||||
|
||||
## Core Discussion Areas
|
||||
|
||||
### 1. Requirements & Objectives
|
||||
- What are the fundamental requirements?
|
||||
- What are the critical success factors?
|
||||
- What constraints must be considered?
|
||||
|
||||
### 2. Technical & Architecture
|
||||
- What are the technical challenges?
|
||||
- What architectural decisions are needed?
|
||||
- What integration points exist?
|
||||
|
||||
### 3. User Experience & Design
|
||||
- Who are the primary users?
|
||||
- What are the key user journeys?
|
||||
- What usability requirements exist?
|
||||
|
||||
### 4. Security & Compliance
|
||||
- What security requirements exist?
|
||||
- What compliance considerations apply?
|
||||
- What data protection is needed?
|
||||
|
||||
### 5. Implementation & Operations
|
||||
- What are the implementation risks?
|
||||
- What resources are required?
|
||||
- How will this be maintained?
|
||||
|
||||
## Available Role Perspectives
|
||||
Framework supports analysis from any of these roles:
|
||||
- **Technical**: system-architect, data-architect, subject-matter-expert
|
||||
- **Product & Design**: ui-designer, ux-expert, product-manager, product-owner
|
||||
- **Agile & Quality**: scrum-master, test-strategist
|
||||
|
||||
---
|
||||
*Comprehensive framework - adaptable to any role*
|
||||
*Last updated: [timestamp]*
|
||||
|
||||
## 📋 Phase 1: Intent Classification
|
||||
|
||||
### Purpose
|
||||
Understand project type and focus areas to customize subsequent questions.
|
||||
|
||||
### Implementation
|
||||
Use **AskUserQuestion** tool to intelligently generate 2-3 classification questions based on user's topic description.
|
||||
|
||||
### Question Types (Intelligently Generated)
|
||||
1. **Project Type**: New feature / Optimization / Refactoring
|
||||
2. **Value Focus**: UX-driven / Technical capability / Business value
|
||||
3. **System Scale**: Small (MVP) / Medium / Large (Enterprise)
|
||||
|
||||
### Output
|
||||
- **intent_context**: Classification results
|
||||
- Stored in session metadata for Phase 2-4 customization
|
||||
|
||||
### Example Flow
|
||||
```javascript
|
||||
AskUserQuestion({
|
||||
questions: [{
|
||||
question: "What is the project type?",
|
||||
header: "Project Type",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{label: "New Feature Development", description: "Build new features or products from scratch"},
|
||||
{label: "System Optimization", description: "Improve performance, experience, or architecture"},
|
||||
{label: "Architecture Migration", description: "Technology stack upgrade or system migration"}
|
||||
]
|
||||
}]
|
||||
// ... Generate 2-3 classification questions similarly
|
||||
})
|
||||
```
|
||||
|
||||
## Role-Specific Content Generation
|
||||
---
|
||||
|
||||
### Available Roles and Their Focus Areas
|
||||
## 👥 Phase 2: Role Selection
|
||||
|
||||
### Purpose
|
||||
Determine which roles should participate in analysis.
|
||||
|
||||
### Implementation Steps
|
||||
|
||||
**1. Analyze Topic + Phase 1 Results**
|
||||
Intelligently recommend 3-5 relevant roles based on keywords.
|
||||
|
||||
**2. Role Recommendation Logic**
|
||||
- **Technical keywords** (architecture, system, performance, database)
|
||||
→ system-architect, data-architect, subject-matter-expert
|
||||
- **API/Backend keywords** (api, endpoint, rest, graphql, service)
|
||||
→ api-designer, system-architect, data-architect
|
||||
- **UX keywords** (user, ui, ux, design, experience)
|
||||
→ ui-designer, ux-expert, product-manager
|
||||
- **Business keywords** (business, process, workflow, cost)
|
||||
→ product-manager, product-owner
|
||||
- **Agile keywords** (sprint, scrum, team, delivery)
|
||||
→ scrum-master, product-owner
|
||||
|
||||
**3. Present to User**
|
||||
Use AskUserQuestion with multiSelect for role selection.
|
||||
|
||||
### Available Roles
|
||||
|
||||
**Technical**: `system-architect`, `data-architect`, `subject-matter-expert`, `api-designer`
|
||||
**Product & Design**: `ui-designer`, `ux-expert`, `product-manager`, `product-owner`
|
||||
**Agile & Quality**: `scrum-master`, `test-strategist`
|
||||
|
||||
**Detailed role descriptions**: See "Reference Information > Available Roles Reference"
|
||||
|
||||
### Output
|
||||
- **selected_roles**: List of user-selected roles
|
||||
- Stored in session metadata
|
||||
|
||||
---
|
||||
|
||||
## 🎓 Phase 3: Role-Specific Professional Questions
|
||||
|
||||
### Purpose
|
||||
Collect decisions for each role's professional domain.
|
||||
|
||||
### Implementation
|
||||
For each selected role, **intelligently generate 3-5 core questions** based on:
|
||||
- Role's professional expertise area
|
||||
- User's topic description
|
||||
- Phase 1 intent context
|
||||
|
||||
### Question Generation Rules
|
||||
1. **Exactly 3 options** per question (MECE principle)
|
||||
2. **Concrete and actionable** options
|
||||
3. **Avoid vague options** like "depends on situation"
|
||||
4. **Use AskUserQuestion** with multiSelect: false
|
||||
|
||||
### Role Question Focus Areas
|
||||
|
||||
**system-architect**:
|
||||
- Architecture style (microservices/monolith/hybrid)
|
||||
- Data consistency (strong/eventual/hybrid)
|
||||
- Performance priority (latency/throughput/resource)
|
||||
- Deployment model (cloud-native/VM/serverless)
|
||||
|
||||
**ui-designer**:
|
||||
- Visual style (minimalist/rich/professional)
|
||||
- Component complexity (simple/moderate/complex)
|
||||
- Design system maturity (full/basic/lightweight)
|
||||
- Responsive strategy (mobile-first/desktop-first/adaptive)
|
||||
|
||||
**ux-expert**:
|
||||
- User persona (novice/intermediate/expert)
|
||||
- Interaction complexity (simple/rich/professional)
|
||||
- Accessibility level (WCAG AA/AAA/basic)
|
||||
- Testing strategy (comprehensive/targeted/minimal)
|
||||
|
||||
**product-manager**:
|
||||
- MVP scope (minimal core/core+hooks/full feature set)
|
||||
- Timeline expectation (fast iteration/standard/robust)
|
||||
- Priority strategy (user value/technical debt/innovation)
|
||||
- Success metrics (usage/satisfaction/revenue)
|
||||
|
||||
**data-architect**:
|
||||
- Storage technology (relational/NoSQL/polyglot)
|
||||
- Data model complexity (simple/moderate/complex domain)
|
||||
- Analytics needs (basic/moderate/advanced)
|
||||
- Compliance requirements (GDPR/HIPAA/none)
|
||||
|
||||
**Other roles** (api-designer, product-owner, scrum-master, subject-matter-expert, test-strategist):
|
||||
Similar 3-5 questions tailored to their domains.
|
||||
|
||||
### Example: System Architect Questions
|
||||
|
||||
For topic "Build real-time collaboration platform":
|
||||
|
||||
```javascript
|
||||
AskUserQuestion({
|
||||
questions: [
|
||||
{
|
||||
question: "System architecture style preference?",
|
||||
header: "Architecture Style",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{label: "Microservices", description: "Independent service deployment, suitable for large teams"},
|
||||
{label: "Modular Monolith", description: "Single deployment unit, suitable for small to medium teams"},
|
||||
{label: "Hybrid Architecture", description: "Core monolith + partial microservices"}
|
||||
]
|
||||
}
|
||||
// ... Generate 3-5 questions similarly
|
||||
]
|
||||
})
|
||||
```
|
||||
|
||||
**Other roles**: Generate similarly based on professional domains (see "Role Question Focus Areas")
|
||||
|
||||
### Output
|
||||
- **role_decisions**: Map of {role: [answers]} for all selected roles
|
||||
- Stored in session metadata
|
||||
|
||||
---
|
||||
|
||||
## 🔗 Phase 4: Cross-Role Clarification Questions
|
||||
|
||||
### Purpose
|
||||
Ensure consistency across roles and identify potential conflicts.
|
||||
|
||||
### Implementation
|
||||
For each selected role, **intelligently generate 1-2 cross-role questions** from perspectives of 2-3 related roles.
|
||||
|
||||
### Cross-Role Relationship Matrix
|
||||
|
||||
| Current Role | Question from Role Perspectives | Question Topics |
|
||||
|---------|------------------|---------|
|
||||
| system-architect | ui-designer, product-manager, data-architect | Frontend stack, MVP scope, storage choice |
|
||||
| ui-designer | ux-expert, system-architect, product-owner | Design system, technical constraints, feature priority |
|
||||
| product-manager | system-architect, ux-expert, scrum-master | Technical feasibility, user pain points, delivery rhythm |
|
||||
| ux-expert | ui-designer, product-manager, subject-matter-expert | Visual style, user goals, industry norms |
|
||||
| data-architect | system-architect, subject-matter-expert, api-designer | Integration patterns, compliance requirements, API design |
|
||||
|
||||
### Example: Cross-Role Question
|
||||
|
||||
System-architect asking from ui-designer perspective:
|
||||
|
||||
```javascript
|
||||
AskUserQuestion({
|
||||
questions: [{
|
||||
question: "Frontend technology stack choice? (Impacts frontend-backend separation strategy)",
|
||||
header: "Frontend Stack",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{label: "Modern Framework (React/Vue)", description: "Requires dedicated frontend team"},
|
||||
{label: "Server-Side Rendering (Next.js)", description: "SEO-friendly"},
|
||||
{label: "Lightweight (jQuery)", description: "Backend-driven"}
|
||||
]
|
||||
}]
|
||||
// ... 1-2 cross-role questions per role
|
||||
})
|
||||
```
|
||||
|
||||
### Output
|
||||
- **cross_role_decisions**: Map of {role: {from_role: [answers]}}
|
||||
- Stored in session metadata
|
||||
|
||||
---
|
||||
|
||||
## 📄 Phase 5: Generate Guidance Specification
|
||||
|
||||
### Purpose
|
||||
Based on all user choices, generate a confirmed guidance document with **declarative statements**, not questions.
|
||||
|
||||
### Implementation
|
||||
1. **Consolidate all decisions**:
|
||||
- intent_context (Phase 1)
|
||||
- selected_roles (Phase 2)
|
||||
- role_decisions (Phase 3)
|
||||
- cross_role_decisions (Phase 4)
|
||||
|
||||
2. **Generate guidance-specification.md** with confirmed decisions
|
||||
|
||||
### Output Document Structure
|
||||
|
||||
See **"Output Specification"** section below for complete template.
|
||||
|
||||
### Output Location
|
||||
```
|
||||
.workflow/WFS-[topic]/.brainstorming/guidance-specification.md
|
||||
```
|
||||
|
||||
**Detailed file structure**: See "Reference Information > File Structure"
|
||||
|
||||
---
|
||||
|
||||
## 🔧 Implementation Details
|
||||
|
||||
### Session Management ⚠️ CRITICAL
|
||||
|
||||
**⚡ First Step**: Check `.workflow/.active-*` markers
|
||||
|
||||
**Logic**:
|
||||
- Multiple active sessions → Prompt user to select
|
||||
- Single active session → Use that session
|
||||
- No active session → Create new `WFS-[topic-slug]`
|
||||
|
||||
**Session Data Storage**:
|
||||
- Decision data: `workflow-session.json`
|
||||
- Output file: `.brainstorming/guidance-specification.md`
|
||||
|
||||
### Implementation Workflow
|
||||
|
||||
**Execution Flow**:
|
||||
1. **Session Management**: Detect or create session
|
||||
2. **Phase 1**: Intent classification (2-3 questions)
|
||||
3. **Phase 2**: Role selection (recommendations + multiSelect)
|
||||
4. **Phase 3**: Role professional questions (3-5 questions per role)
|
||||
5. **Phase 4**: Cross-role clarification (1-2 questions per role)
|
||||
6. **Phase 5**: Generate guidance-specification.md
|
||||
7. **Update Metadata**: Save all decisions to session
|
||||
|
||||
**TodoWrite tracking**: Update progress at each Phase
|
||||
|
||||
**Decision storage**: All user choices saved to `workflow-session.json`
|
||||
|
||||
---
|
||||
|
||||
## 🤖 Intelligent Question Generation
|
||||
|
||||
### Core Principle
|
||||
All questions are **intelligently generated by Claude** based on:
|
||||
- Role professional domain
|
||||
- User's topic description
|
||||
- Previous decision context
|
||||
- Phase 1 intent classification
|
||||
|
||||
**No Template Library Required**: Questions are dynamically created to fit specific task context.
|
||||
|
||||
### Question Generation Guidelines
|
||||
|
||||
**For Phase 3 (Role Questions)**:
|
||||
```
|
||||
INPUT: role + topic + intent_context
|
||||
OUTPUT: 3-5 questions, each with 3 MECE options
|
||||
|
||||
Example:
|
||||
- Role: system-architect
|
||||
- Topic: "Build real-time collaboration platform"
|
||||
- Intent: {type: "new_feature", scale: "medium", focus: "technical"}
|
||||
|
||||
Generated Questions:
|
||||
1. Architecture style? [Microservices/Modular Monolith/Hybrid]
|
||||
2. Real-time communication tech? [WebSocket/SSE/Polling]
|
||||
3. Data consistency? [Strong/Eventual/Hybrid]
|
||||
4. Deployment model? [Cloud-native/Traditional VM/Serverless]
|
||||
```
|
||||
|
||||
**For Phase 4 (Cross-Role Questions)**:
|
||||
```
|
||||
INPUT: current_role + related_role + role_decisions + topic
|
||||
OUTPUT: 1-2 questions from related_role perspective
|
||||
|
||||
Example:
|
||||
- Current: system-architect
|
||||
- Related: ui-designer
|
||||
- Topic: "Build real-time collaboration platform"
|
||||
- Context: ui-designer chose "Modern Framework (React)"
|
||||
|
||||
Generated Question:
|
||||
"Frontend technology stack choice? (Impacts frontend-backend separation strategy)"
|
||||
[Modern Framework/Server-Side Rendering/Lightweight]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ✅ Validation & Quality Assurance
|
||||
|
||||
### Output Validation
|
||||
|
||||
**Guidance Specification Must Contain**:
|
||||
- ✅ **All declarative statements**: No question marks in decision sections
|
||||
- ✅ **Clear decisions**: Every decision point has explicit choice
|
||||
- ✅ **Decision traceability**: Can trace back to user answers
|
||||
- ✅ **Cross-role consistency**: Conflicts resolved or noted
|
||||
- ✅ **Actionability**: Next steps are clear
|
||||
|
||||
### Validation Checklist
|
||||
|
||||
The generated guidance-specification.md must pass these checks:
|
||||
|
||||
✅ **No interrogative sentences**: Decision sections should not end with question marks
|
||||
✅ **Clear decisions**: Every decision point has explicit choice (not "TBD"/"Pending")
|
||||
✅ **Traceable**: Every decision can be traced back to user answers
|
||||
✅ **Cross-role consistency**: Cross-role decision count ≥ number of selected roles
|
||||
✅ **Actionable**: "Next steps" are clear and specific
|
||||
|
||||
**Automatic validation**: Execute checks after generation, prompt if issues found
|
||||
|
||||
---
|
||||
|
||||
## 📝 Output Specification
|
||||
|
||||
### Document Structure Overview
|
||||
|
||||
**Output file**: `.workflow/WFS-[topic]/.brainstorming/guidance-specification.md`
|
||||
|
||||
### Template Structure
|
||||
|
||||
```markdown
|
||||
# [Project] - Confirmed Guidance Specification
|
||||
|
||||
**Metadata**: [timestamp, type, focus, roles]
|
||||
|
||||
## 1. Project Positioning & Goals
|
||||
**CONFIRMED**: [objectives, success criteria]
|
||||
|
||||
## 2-5. Role-Specific Decisions
|
||||
Each participating role has one section containing:
|
||||
- **SELECTED**: [confirmed choices]
|
||||
- **Rationale**: [reasoning]
|
||||
- **Constraints/Impact**: [implications]
|
||||
- **Cross-Role Confirmed**: [dependencies]
|
||||
|
||||
## 6. Cross-Role Integration
|
||||
**CONFIRMED**: [API style, data format, auth, collaboration model]
|
||||
|
||||
## 7. Risks & Constraints
|
||||
**Identified**: [risks with mitigation, constraints]
|
||||
|
||||
## 8. Next Steps
|
||||
**Immediate Actions**: [action items]
|
||||
**Role Assignments**: [tasks per role]
|
||||
|
||||
## Appendix: Decision Tracking
|
||||
**Key Decisions**: [table]
|
||||
**Open Items**: [list]
|
||||
```
|
||||
|
||||
**Core principles**:
|
||||
- All decisions use declarative statements (CONFIRMED/SELECTED)
|
||||
- Every decision is traceable to user answers
|
||||
- Cross-role decisions ensure consistency
|
||||
- Next steps are clear and specific
|
||||
|
||||
---
|
||||
|
||||
## 🔄 Update Mechanism
|
||||
|
||||
### Existing Guidance Update
|
||||
|
||||
```bash
|
||||
IF guidance-specification.md EXISTS:
|
||||
SHOW current guidance summary to user
|
||||
ASK: "Guidance exists. Do you want to:"
|
||||
OPTIONS:
|
||||
1. "Regenerate completely" → Start full clarification flow
|
||||
2. "Update specific sections" → Target specific roles/decisions
|
||||
3. "Cancel" → Exit without changes
|
||||
ELSE:
|
||||
CREATE new guidance through full clarification
|
||||
```
|
||||
|
||||
**Update Strategies**:
|
||||
1. **Complete Regeneration**: Backup existing → Full clarification flow
|
||||
2. **Targeted Update**: Update specific role sections or cross-role decisions
|
||||
3. **Incremental Addition**: Add new roles or decision areas
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ Error Handling
|
||||
|
||||
| Error Type | Handling Strategy |
|
||||
|-----------|-------------------|
|
||||
| Session creation failed | Error details + retry option + check permissions |
|
||||
| AskUserQuestion timeout | Save progress + allow resumption + provide instructions |
|
||||
| Incomplete clarification | Mark open items + suggest follow-up clarification |
|
||||
| Conflicting decisions | Highlight conflicts + show disagreeing roles + suggest resolution |
|
||||
|
||||
---
|
||||
|
||||
## 🔗 Integration with Downstream Workflow
|
||||
|
||||
### Core Principles & Governance Rules
|
||||
|
||||
**GOVERNANCE_RULES** for guidance-specification.md output:
|
||||
|
||||
✅ **Declarative Statements Only**
|
||||
- All decisions MUST use CONFIRMED/SELECTED format
|
||||
- NO interrogative sentences (no "?" in decision sections)
|
||||
- NO open questions or TBD items in confirmed decisions
|
||||
|
||||
✅ **Decision Traceability**
|
||||
- Every decision MUST trace back to specific user answer
|
||||
- Cross-reference to Phase 1-4 clarification responses
|
||||
- Document rationale for each confirmed choice
|
||||
|
||||
✅ **Cross-Role Consistency**
|
||||
- Cross-role decisions count ≥ number of selected roles
|
||||
- Conflicts MUST be resolved or explicitly documented
|
||||
- Dependencies between roles clearly stated
|
||||
|
||||
✅ **Actionability Requirements**
|
||||
- Next steps MUST be concrete and specific
|
||||
- Role assignments clearly defined
|
||||
- Success criteria measurable and verifiable
|
||||
|
||||
✅ **Session Integrity**
|
||||
- All decisions stored in `workflow-session.json`
|
||||
- Topic description preserved as authoritative reference
|
||||
- Session lifecycle properly managed (active markers, metadata)
|
||||
|
||||
**CRITICAL**: Generated guidance is the **single source of truth** for all downstream workflow phases. Any ambiguity violates governance rules and MUST be resolved before proceeding.
|
||||
|
||||
---
|
||||
|
||||
### Next Steps After Guidance Generation
|
||||
|
||||
**Standard Workflow**:
|
||||
```bash
|
||||
/workflow:concept-clarify --session WFS-{session-id} # Optional: Further clarification
|
||||
/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
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📚 Reference Information
|
||||
|
||||
### File Structure
|
||||
```
|
||||
.workflow/WFS-[topic]/
|
||||
├── workflow-session.json # Session metadata with all decisions
|
||||
└── .brainstorming/
|
||||
├── guidance-specification.md # ★ PRIMARY OUTPUT (declarative statements)
|
||||
└── [role]/
|
||||
└── analysis.md # Role deepening analysis (generated later)
|
||||
```
|
||||
|
||||
### Available Roles Reference
|
||||
|
||||
**Technical Roles**:
|
||||
- `system-architect`: Architecture patterns, scalability, technology stack, integration
|
||||
- `data-architect`: Data modeling, processing workflows, analytics, storage
|
||||
- `subject-matter-expert`: Domain expertise, industry standards, compliance, best practices
|
||||
- `data-architect`: Data modeling, storage workflows, analytics, compliance
|
||||
- `subject-matter-expert`: Domain expertise, industry standards, best practices
|
||||
- `api-designer`: API design, versioning, contracts, authentication
|
||||
|
||||
**Product & Design Roles**:
|
||||
- `ui-designer`: User interface, visual design, interaction patterns, accessibility
|
||||
- `ux-expert`: User experience optimization, usability testing, interaction design, design systems
|
||||
- `ui-designer`: User interface, visual design, components, accessibility
|
||||
- `ux-expert`: User experience, usability testing, interaction design, design systems
|
||||
- `product-manager`: Business value, feature prioritization, market positioning, roadmap
|
||||
- `product-owner`: Backlog management, user stories, acceptance criteria, stakeholder alignment
|
||||
|
||||
@@ -231,143 +558,13 @@ Framework supports analysis from any of these roles:
|
||||
- `scrum-master`: Sprint planning, team dynamics, process optimization, delivery management
|
||||
- `test-strategist`: Testing strategies, quality assurance, test automation, validation approaches
|
||||
|
||||
### Dynamic Discussion Point Generation
|
||||
### Architecture Reference
|
||||
- **Workflow Architecture**: @~/.claude/workflows/workflow-architecture.md
|
||||
- **Clarification Plan**: @~/.claude/workflows/brainstorm-clarification-plan.md
|
||||
|
||||
**For each selected role, generate**:
|
||||
1. **2-3 core discussion areas** specific to that role's perspective
|
||||
2. **3-5 targeted questions** per discussion area
|
||||
3. **Cross-role integration points** showing how roles interact
|
||||
|
||||
**Example mapping**:
|
||||
```javascript
|
||||
// If roles = ["ui-designer", "system-architect"]
|
||||
Generate:
|
||||
- UI Designer section: UI Requirements, UX Challenges
|
||||
- System Architect section: Architecture Decisions, Technical Implementation
|
||||
- Integration Points: UI↔Architecture dependencies
|
||||
```
|
||||
|
||||
### Framework Generation Examples
|
||||
|
||||
#### Example 1: Architecture-Heavy Topic
|
||||
```bash
|
||||
/workflow:brainstorm:artifacts "Design scalable microservices platform" --roles "system-architect,data-architect,subject-matter-expert"
|
||||
```
|
||||
**Generated framework focuses on**:
|
||||
- Service architecture and communication patterns
|
||||
- Data flow and storage strategies
|
||||
- Domain standards and best practices
|
||||
|
||||
#### Example 2: User-Focused Topic
|
||||
```bash
|
||||
/workflow:brainstorm:artifacts "Improve user onboarding experience" --roles "ui-designer,ux-expert,product-manager"
|
||||
```
|
||||
**Generated framework focuses on**:
|
||||
- Onboarding flow and UI components
|
||||
- User experience optimization and usability
|
||||
- Business value and success metrics
|
||||
|
||||
#### Example 3: Agile Delivery Topic
|
||||
```bash
|
||||
/workflow:brainstorm:artifacts "Optimize sprint delivery process" --roles "scrum-master,product-owner,test-strategist"
|
||||
```
|
||||
**Generated framework focuses on**:
|
||||
- Sprint planning and team collaboration
|
||||
- Backlog management and prioritization
|
||||
- Quality assurance and testing strategies
|
||||
|
||||
#### Example 4: Comprehensive Analysis
|
||||
```bash
|
||||
/workflow:brainstorm:artifacts "Build real-time collaboration feature"
|
||||
```
|
||||
**Generated framework covers** all aspects (no roles specified)
|
||||
|
||||
## Session Management ⚠️ CRITICAL
|
||||
- **⚡ FIRST ACTION**: Check for all `.workflow/.active-*` markers before processing
|
||||
- **Multiple sessions support**: Different Claude instances can have different active sessions
|
||||
- **User selection**: If multiple active sessions found, prompt user to select which one to work with
|
||||
- **Auto-session creation**: `WFS-[topic-slug]` only if no active session exists
|
||||
- **Session continuity**: MUST use selected active session for all processing
|
||||
- **Context preservation**: All discussion and analysis stored in session directory
|
||||
- **Session isolation**: Each session maintains independent state
|
||||
|
||||
## Discussion Areas
|
||||
|
||||
### Core Investigation Topics
|
||||
- **Purpose & Goals**: What are we trying to achieve?
|
||||
- **Scope & Boundaries**: What's included and excluded?
|
||||
- **Success Criteria**: How do we measure success?
|
||||
- **Constraints**: What limitations exist?
|
||||
- **Stakeholders**: Who is affected or involved?
|
||||
|
||||
### Technical Considerations
|
||||
- **Requirements**: What must the solution provide?
|
||||
- **Dependencies**: What does it rely on?
|
||||
- **Integration**: How does it connect to existing systems?
|
||||
- **Performance**: What are the speed/scale requirements?
|
||||
- **Security**: What protection is needed?
|
||||
|
||||
### Implementation Factors
|
||||
- **Timeline**: When is it needed?
|
||||
- **Resources**: What people/budget/tools are available?
|
||||
- **Risks**: What could go wrong?
|
||||
- **Alternatives**: What other approaches exist?
|
||||
- **Migration**: How do we transition from current state?
|
||||
|
||||
## Update Mechanism ⚠️ SMART UPDATES
|
||||
|
||||
### Framework Update Logic
|
||||
```bash
|
||||
# Check existing framework
|
||||
IF topic-framework.md EXISTS:
|
||||
SHOW current framework to user
|
||||
ASK: "Framework exists. Do you want to:"
|
||||
OPTIONS:
|
||||
1. "Replace completely" → Generate new framework
|
||||
2. "Add discussion points" → Append to existing
|
||||
3. "Refine existing points" → Interactive editing
|
||||
4. "Cancel" → Exit without changes
|
||||
ELSE:
|
||||
CREATE new framework
|
||||
```
|
||||
|
||||
### Update Strategies
|
||||
|
||||
**1. Complete Replacement**
|
||||
- Backup existing framework as `topic-framework-[timestamp].md.backup`
|
||||
- Generate completely new framework
|
||||
- Preserve role-specific analysis points from previous version
|
||||
|
||||
**2. Incremental Addition**
|
||||
- Load existing framework
|
||||
- Identify new discussion areas through user interaction
|
||||
- Add new sections while preserving existing structure
|
||||
- Update framework usage instructions
|
||||
|
||||
**3. Refinement Mode**
|
||||
- Interactive editing of existing discussion points
|
||||
- Allow modification of scope, objectives, and questions
|
||||
- Preserve framework structure and role assignments
|
||||
- Update timestamp and version info
|
||||
|
||||
### Version Control
|
||||
- **Backup Creation**: Always backup before major changes
|
||||
- **Change Tracking**: Include change summary in framework footer
|
||||
- **Rollback Support**: Keep previous version accessible
|
||||
|
||||
## Error Handling
|
||||
- **Session creation failure**: Provide clear error message and retry option
|
||||
- **Discussion stalling**: Offer structured prompts to continue exploration
|
||||
- **Documentation issues**: Graceful handling of file creation problems
|
||||
- **Missing context**: Prompt for additional information when needed
|
||||
|
||||
## Reference Information
|
||||
|
||||
### File Structure Reference
|
||||
**Architecture**: @~/.claude/workflows/workflow-architecture.md
|
||||
**Session Management**: Standard workflow session protocols
|
||||
|
||||
### Integration Points
|
||||
- **Compatible with**: Other brainstorming commands in the same session
|
||||
- **Builds foundation for**: More detailed planning and implementation phases
|
||||
- **Outputs used by**: `/workflow:brainstorm:synthesis` command for cross-analysis integration
|
||||
### Related Commands
|
||||
- `/workflow:brainstorm:auto-parallel` - Parallel role analysis execution
|
||||
- `/workflow:brainstorm:synthesis` - Synthesize role analyses
|
||||
- `/workflow:brainstorm:[role]` - Individual role analysis commands
|
||||
- `/workflow:concept-clarify` - Further concept clarification
|
||||
- `/workflow:plan` - Generate implementation plan
|
||||
|
||||
Reference in New Issue
Block a user