mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-05 01:50:27 +08:00
docs: refine artifacts command documentation for clarity and structure
This commit is contained in:
catlog22
@@ -1,27 +1,21 @@
|
||||
---
|
||||
name: artifacts
|
||||
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(*)
|
||||
description: Interactive clarification generating confirmed guidance specification
|
||||
argument-hint: "topic or challenge description"
|
||||
allowed-tools: TodoWrite(*), Read(*), Write(*), AskUserQuestion(*), Glob(*)
|
||||
---
|
||||
|
||||
# Brainstorm Clarification Command
|
||||
## Overview
|
||||
|
||||
## 📖 Overview
|
||||
Five-phase interactive workflow collecting user decisions through intelligent questioning, generating **confirmed guidance specification** with declarative statements (no questions).
|
||||
|
||||
### 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).
|
||||
**Input**: User topic description
|
||||
**Output**: `.workflow/WFS-{topic}/.brainstorming/guidance-specification.md` (CONFIRMED/SELECTED format)
|
||||
**Key Process**: Intent classification → Role selection → Role questions → Cross-role clarification → Generate guidance document
|
||||
|
||||
### 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 stored in session metadata as authoritative reference throughout workflow lifecycle.
|
||||
|
||||
### User Intent Preservation
|
||||
Topic description is stored in session metadata and serves as authoritative reference throughout workflow lifecycle.
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Usage
|
||||
## Usage
|
||||
|
||||
### Basic Command
|
||||
```bash
|
||||
@@ -38,54 +32,50 @@ Topic description is stored in session metadata and serves as authoritative refe
|
||||
/workflow:brainstorm:artifacts "GOAL: Build real-time collaboration platform SCOPE: Support 100 concurrent users CONTEXT: Existing monolithic architecture needs refactoring"
|
||||
```
|
||||
|
||||
---
|
||||
## Task Tracking
|
||||
|
||||
## 🔄 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)
|
||||
```json
|
||||
[
|
||||
{"content": "Initialize session and check .workflow/.active-* markers", "status": "pending", "activeForm": "Initializing session"},
|
||||
{"content": "Phase 1: Generate and ask intent classification questions (2-3 questions)", "status": "pending", "activeForm": "Collecting intent classification"},
|
||||
{"content": "Phase 2: Recommend roles and collect user selection (3-5 roles, multiSelect)", "status": "pending", "activeForm": "Collecting role selection"},
|
||||
{"content": "Phase 3: Generate and ask role-specific questions (3-5 questions per role)", "status": "pending", "activeForm": "Collecting role-specific decisions"},
|
||||
{"content": "Phase 4: Generate and ask cross-role clarification questions (1-2 questions per role)", "status": "pending", "activeForm": "Collecting cross-role clarifications"},
|
||||
{"content": "Phase 5: Transform all answers to declarative statements and generate guidance-specification.md", "status": "pending", "activeForm": "Generating guidance document"},
|
||||
{"content": "Update workflow-session.json with all decisions and metadata", "status": "pending", "activeForm": "Updating session metadata"}
|
||||
]
|
||||
```
|
||||
|
||||
---
|
||||
## Execution Phases
|
||||
|
||||
## 📋 Phase 1: Intent Classification
|
||||
### Session Management (First Step)
|
||||
|
||||
### Purpose
|
||||
Understand project type and focus areas to customize subsequent questions.
|
||||
**⚡ CRITICAL**: Check `.workflow/.active-*` markers before starting
|
||||
|
||||
### Implementation
|
||||
Use **AskUserQuestion** tool to intelligently generate 2-3 classification questions based on user's topic description.
|
||||
**Logic**:
|
||||
- Multiple active sessions → Prompt user to select
|
||||
- Single active session → Use that session
|
||||
- No active session → Create new `WFS-[topic-slug]`
|
||||
|
||||
### 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)
|
||||
**Session Storage**:
|
||||
- Decision data: `workflow-session.json`
|
||||
- Output file: `.brainstorming/guidance-specification.md`
|
||||
|
||||
### Output
|
||||
- **intent_context**: Classification results
|
||||
- Stored in session metadata for Phase 2-4 customization
|
||||
### Phase 1: Intent Classification
|
||||
|
||||
### Example Flow
|
||||
**Purpose**: Understand project type and focus to customize subsequent questions
|
||||
|
||||
**Steps**:
|
||||
1. Generate 2-3 classification questions based on user topic
|
||||
2. Use AskUserQuestion to collect answers
|
||||
3. Store to `session.intent_context`
|
||||
|
||||
**Question Types** (intelligently generated):
|
||||
- **Project Type**: New feature / Optimization / Refactoring
|
||||
- **Value Focus**: UX-driven / Technical capability / Business value
|
||||
- **System Scale**: Small (MVP) / Medium / Large (Enterprise)
|
||||
|
||||
**Example**:
|
||||
```javascript
|
||||
AskUserQuestion({
|
||||
questions: [{
|
||||
@@ -98,69 +88,48 @@ AskUserQuestion({
|
||||
{label: "Architecture Migration", description: "Technology stack upgrade or system migration"}
|
||||
]
|
||||
}]
|
||||
// ... Generate 2-3 classification questions similarly
|
||||
// ... 2-3 questions total
|
||||
})
|
||||
```
|
||||
|
||||
---
|
||||
### Phase 2: Role Selection
|
||||
|
||||
## 👥 Phase 2: Role Selection
|
||||
**Purpose**: Determine which roles participate in analysis
|
||||
|
||||
### Purpose
|
||||
Determine which roles should participate in analysis.
|
||||
**Steps**:
|
||||
1. Analyze topic + Phase 1 results to recommend 3-5 relevant roles
|
||||
2. Use AskUserQuestion (multiSelect) to collect user selection
|
||||
3. Store to `session.selected_roles`
|
||||
|
||||
### Implementation Steps
|
||||
**Role Recommendation Logic** (keyword-based):
|
||||
- **Technical**: architecture, system, performance, database → system-architect, data-architect, subject-matter-expert
|
||||
- **API/Backend**: api, endpoint, rest, graphql, service → api-designer, system-architect, data-architect
|
||||
- **UX**: user, ui, ux, design, experience → ui-designer, ux-expert, product-manager
|
||||
- **Business**: business, process, workflow, cost → product-manager, product-owner
|
||||
- **Agile**: sprint, scrum, team, delivery → scrum-master, product-owner
|
||||
|
||||
**1. Analyze Topic + Phase 1 Results**
|
||||
Intelligently recommend 3-5 relevant roles based on keywords.
|
||||
**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
|
||||
|
||||
**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
|
||||
### Phase 3: Role-Specific Questions
|
||||
|
||||
**3. Present to User**
|
||||
Use AskUserQuestion with multiSelect for role selection.
|
||||
**Purpose**: Collect professional domain decisions for each role
|
||||
|
||||
### Available Roles
|
||||
**Steps**:
|
||||
FOR each role in selected_roles:
|
||||
1. Generate 3-5 core questions based on (role + topic + intent_context)
|
||||
2. Use AskUserQuestion to collect answers
|
||||
3. Store to `session.role_decisions[role]`
|
||||
|
||||
**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`
|
||||
**Question Rules**:
|
||||
- Exactly 3 options per question (MECE principle)
|
||||
- Concrete and actionable options
|
||||
- Avoid vague options like "depends on situation"
|
||||
- Use multiSelect: false
|
||||
|
||||
**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
|
||||
**Role Question Focus Areas**:
|
||||
|
||||
**system-architect**:
|
||||
- Architecture style (microservices/monolith/hybrid)
|
||||
@@ -192,13 +161,9 @@ For each selected role, **intelligently generate 3-5 core questions** based on:
|
||||
- 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":
|
||||
**Other roles** (api-designer, product-owner, scrum-master, subject-matter-expert, test-strategist): Similar 3-5 questions tailored to their domains.
|
||||
|
||||
**Example** (system-architect for "Build real-time collaboration platform"):
|
||||
```javascript
|
||||
AskUserQuestion({
|
||||
questions: [
|
||||
@@ -212,41 +177,32 @@ AskUserQuestion({
|
||||
{label: "Hybrid Architecture", description: "Core monolith + partial microservices"}
|
||||
]
|
||||
}
|
||||
// ... Generate 3-5 questions similarly
|
||||
// ... 3-5 questions total
|
||||
]
|
||||
})
|
||||
```
|
||||
|
||||
**Other roles**: Generate similarly based on professional domains (see "Role Question Focus Areas")
|
||||
### Phase 4: Cross-Role Clarification
|
||||
|
||||
### Output
|
||||
- **role_decisions**: Map of {role: [answers]} for all selected roles
|
||||
- Stored in session metadata
|
||||
**Purpose**: Ensure consistency across roles and identify potential conflicts
|
||||
|
||||
---
|
||||
**Steps**:
|
||||
FOR each role in selected_roles:
|
||||
1. Generate 1-2 cross-role questions from perspectives of 2-3 related roles
|
||||
2. Use AskUserQuestion to collect answers
|
||||
3. Store to `session.cross_role_decisions[role]`
|
||||
|
||||
## 🔗 Phase 4: Cross-Role Clarification Questions
|
||||
**Cross-Role Relationship Matrix**:
|
||||
|
||||
### 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 |
|
||||
|---------|------------------|---------|
|
||||
| Current Role | Question from Perspectives | 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:
|
||||
|
||||
**Example** (system-architect from ui-designer perspective):
|
||||
```javascript
|
||||
AskUserQuestion({
|
||||
questions: [{
|
||||
@@ -259,89 +215,166 @@ AskUserQuestion({
|
||||
{label: "Lightweight (jQuery)", description: "Backend-driven"}
|
||||
]
|
||||
}]
|
||||
// ... 1-2 cross-role questions per role
|
||||
// ... 1-2 questions per role
|
||||
})
|
||||
```
|
||||
|
||||
### Output
|
||||
- **cross_role_decisions**: Map of {role: {from_role: [answers]}}
|
||||
- Stored in session metadata
|
||||
### Phase 5: Generate Guidance Specification
|
||||
|
||||
---
|
||||
**Purpose**: Transform all user choices into confirmed guidance document with declarative statements
|
||||
|
||||
## 📄 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**:
|
||||
**Steps**:
|
||||
1. Load all decisions from session metadata:
|
||||
- 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
|
||||
2. Transform Q&A pairs to declarative statements:
|
||||
- Questions → Section headers
|
||||
- User answers → CONFIRMED/SELECTED statements
|
||||
- Rationale from option descriptions
|
||||
|
||||
### Output Document Structure
|
||||
3. Generate document structure (see Output Document Template below)
|
||||
|
||||
See **"Output Specification"** section below for complete template.
|
||||
4. Write to `.workflow/WFS-{topic}/.brainstorming/guidance-specification.md`
|
||||
|
||||
### Output Location
|
||||
```
|
||||
.workflow/WFS-[topic]/.brainstorming/guidance-specification.md
|
||||
```
|
||||
5. Validate output (see Validation Checklist below)
|
||||
|
||||
**Detailed file structure**: See "Reference Information > File Structure"
|
||||
**⚠️ CRITICAL CONSTRAINTS**:
|
||||
- ❌ NEVER skip AskUserQuestion in Phase 1-4
|
||||
- ❌ NEVER generate guidance-specification.md before Phase 5
|
||||
- ❌ NEVER use interrogative sentences in guidance-specification.md
|
||||
- ✅ ALWAYS collect user decisions through AskUserQuestion
|
||||
- ✅ ALWAYS transform Q&A pairs to declarative statements
|
||||
|
||||
## Output Document Template
|
||||
|
||||
**File**: `.workflow/WFS-{topic}/.brainstorming/guidance-specification.md`
|
||||
|
||||
```markdown
|
||||
# [Project Name] - Confirmed Guidance Specification
|
||||
|
||||
**Generated**: [timestamp]
|
||||
**Project Type**: [from Phase 1]
|
||||
**Value Focus**: [from Phase 1]
|
||||
**System Scale**: [from Phase 1]
|
||||
**Participating Roles**: [from Phase 2]
|
||||
|
||||
---
|
||||
|
||||
## 🔧 Implementation Details
|
||||
## 1. Project Positioning & Goals
|
||||
|
||||
### Session Management ⚠️ CRITICAL
|
||||
**CONFIRMED Objectives**:
|
||||
- [Objective 1 from user topic + Phase 1 answers]
|
||||
- [Objective 2]
|
||||
- [Objective 3]
|
||||
|
||||
**⚡ 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`
|
||||
**CONFIRMED Success Criteria**:
|
||||
- [Criterion 1 derived from Phase 1 answers]
|
||||
- [Criterion 2]
|
||||
|
||||
---
|
||||
|
||||
## 🤖 Intelligent Question Generation
|
||||
## 2. [Role 1] Decisions
|
||||
|
||||
### SELECTED Choices
|
||||
|
||||
**[Question 1 topic]**: [User's selected option]
|
||||
- **Rationale**: [From option description + Phase 1 context]
|
||||
- **Impact**: [Implications for project]
|
||||
|
||||
**[Question 2 topic]**: [User's selected option]
|
||||
- **Rationale**: [From option description]
|
||||
- **Constraints**: [Technical/business constraints]
|
||||
|
||||
[... remaining role-specific questions]
|
||||
|
||||
### Cross-Role Considerations
|
||||
|
||||
**[Cross-role question topic]**: [User's selected option]
|
||||
- **Affected Roles**: [Related roles from Phase 4]
|
||||
- **Dependencies**: [How this impacts other roles]
|
||||
|
||||
---
|
||||
|
||||
## 3-N. [Role 2-N] Decisions
|
||||
|
||||
[Same structure as Role 1 for each participating role]
|
||||
|
||||
---
|
||||
|
||||
## Cross-Role Integration
|
||||
|
||||
**CONFIRMED Integration Points**:
|
||||
- **API Style**: [Consolidated from api-designer + system-architect]
|
||||
- **Data Format**: [From data-architect + api-designer]
|
||||
- **Authentication**: [From system-architect + security considerations]
|
||||
- **Collaboration Model**: [From scrum-master + product-owner]
|
||||
|
||||
**CONFIRMED Consistency Validations**:
|
||||
- [Consistency check 1 from Phase 4 cross-role questions]
|
||||
- [Consistency check 2]
|
||||
|
||||
---
|
||||
|
||||
## Risks & Constraints
|
||||
|
||||
**Identified Risks** (from user choices):
|
||||
- **[Risk 1]**: [From Phase 3/4 answers] → Mitigation: [Approach]
|
||||
- **[Risk 2]**: [From Phase 3/4 answers] → Mitigation: [Approach]
|
||||
|
||||
**CONFIRMED Constraints**:
|
||||
- **Technical**: [From system-architect/data-architect answers]
|
||||
- **Business**: [From product-manager answers]
|
||||
- **Timeline**: [From Phase 1/product-manager answers]
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
**Immediate Actions**:
|
||||
1. [Action 1 derived from role decisions]
|
||||
2. [Action 2 derived from cross-role integration]
|
||||
3. [Action 3 for risk mitigation]
|
||||
|
||||
**Role Assignments**:
|
||||
- **[Role 1]**: [Specific tasks from their decisions]
|
||||
- **[Role 2]**: [Specific tasks from their decisions]
|
||||
|
||||
**Recommended Workflow**:
|
||||
```
|
||||
/workflow:concept-clarify --session WFS-{session-id} # Optional: Further clarification
|
||||
/workflow:plan --session WFS-{session-id} # Generate IMPL_PLAN.md and tasks
|
||||
/workflow:execute --session WFS-{session-id} # Start implementation
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Appendix: Decision Tracking
|
||||
|
||||
| Decision ID | Category | Question | Selected Option | Phase | Rationale |
|
||||
|-------------|----------|----------|-----------------|-------|-----------|
|
||||
| D-001 | Intent | Project Type | [Answer] | Phase 1 | [Rationale] |
|
||||
| D-002 | Roles | Participating Roles | [Roles] | Phase 2 | [Rationale] |
|
||||
| D-003 | [Role] | [Question] | [Answer] | Phase 3 | [Rationale] |
|
||||
| ... | ... | ... | ... | ... | ... |
|
||||
|
||||
**Open Items** (if any):
|
||||
- [Item 1 requiring follow-up]
|
||||
- [Item 2 requiring follow-up]
|
||||
```
|
||||
|
||||
## Question Generation Guidelines
|
||||
|
||||
### Core Principle
|
||||
All questions are **intelligently generated by Claude** based on:
|
||||
All questions **intelligently generated** by Claude based on:
|
||||
- Role professional domain
|
||||
- User's topic description
|
||||
- Previous decision context
|
||||
- Phase 1 intent classification
|
||||
- Previous decision context (Phase 1-4)
|
||||
- No template library required - dynamic generation
|
||||
|
||||
**No Template Library Required**: Questions are dynamically created to fit specific task context.
|
||||
|
||||
### Question Generation Guidelines
|
||||
|
||||
**For Phase 3 (Role Questions)**:
|
||||
### Phase 3 Generation Pattern
|
||||
```
|
||||
INPUT: role + topic + intent_context
|
||||
OUTPUT: 3-5 questions, each with 3 MECE options
|
||||
@@ -358,7 +391,7 @@ Generated Questions:
|
||||
4. Deployment model? [Cloud-native/Traditional VM/Serverless]
|
||||
```
|
||||
|
||||
**For Phase 4 (Cross-Role Questions)**:
|
||||
### Phase 4 Generation Pattern
|
||||
```
|
||||
INPUT: current_role + related_role + role_decisions + topic
|
||||
OUTPUT: 1-2 questions from related_role perspective
|
||||
@@ -374,116 +407,50 @@ Generated Question:
|
||||
[Modern Framework/Server-Side Rendering/Lightweight]
|
||||
```
|
||||
|
||||
---
|
||||
## Validation Checklist
|
||||
|
||||
## ✅ Validation & Quality Assurance
|
||||
The generated guidance-specification.md MUST pass these checks:
|
||||
|
||||
### 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
|
||||
✅ **No interrogative sentences**: Decision sections use CONFIRMED/SELECTED, not questions
|
||||
✅ **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
|
||||
✅ **Traceable**: Every decision traces back to specific user answer
|
||||
✅ **Cross-role consistency**: Cross-role decisions ≥ number of selected roles
|
||||
✅ **Actionable**: Next steps are concrete and specific
|
||||
✅ **Complete metadata**: All Phase 1-4 decisions stored in session
|
||||
|
||||
**Automatic validation**: Execute checks after generation, prompt if issues found
|
||||
**Validation Process**: Execute checks after Phase 5, prompt user 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
|
||||
## 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
|
||||
SHOW current guidance summary to user
|
||||
ASK: "Guidance exists. Do you want to:"
|
||||
OPTIONS:
|
||||
1. "Regenerate completely" → Backup existing → Full Phase 1-5 flow
|
||||
2. "Update specific sections" → Target specific roles/decisions → Partial re-run
|
||||
3. "Cancel" → Exit without changes
|
||||
ELSE:
|
||||
CREATE new guidance through full clarification
|
||||
CREATE new guidance through full Phase 1-5 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
|
||||
2. **Targeted Update**: Re-run Phase 3/4 for specific roles only
|
||||
3. **Incremental Addition**: Add new roles via Phase 2 → Phase 3 → Phase 4 for new roles
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ Error Handling
|
||||
## 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 |
|
||||
| Session creation failed | Show error details + retry option + check .workflow/ permissions |
|
||||
| AskUserQuestion timeout | Save progress to session + allow resumption from last completed Phase |
|
||||
| Incomplete clarification | Mark open items in guidance document + suggest follow-up `/workflow:concept-clarify` |
|
||||
| Conflicting decisions | Highlight conflicts in guidance document + show disagreeing roles + suggest resolution questions |
|
||||
|
||||
---
|
||||
|
||||
## 🔗 Integration with Downstream Workflow
|
||||
|
||||
### Core Principles & Governance Rules
|
||||
## Governance Rules
|
||||
|
||||
**GOVERNANCE_RULES** for guidance-specification.md output:
|
||||
|
||||
@@ -514,57 +481,16 @@ ELSE:
|
||||
|
||||
**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.
|
||||
|
||||
---
|
||||
## File Structure
|
||||
|
||||
### 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
|
||||
├── .active-brainstorming # Active session marker
|
||||
├── workflow-session.json # Session metadata with all decisions
|
||||
└── .brainstorming/
|
||||
├── guidance-specification.md # ★ PRIMARY OUTPUT (declarative statements)
|
||||
└── [role]/
|
||||
└── analysis.md # Role deepening analysis (generated later)
|
||||
├── guidance-specification.md # ★ PRIMARY OUTPUT (declarative statements)
|
||||
└── [role]/ # Role analysis directories (generated later by other commands)
|
||||
└── analysis.md
|
||||
```
|
||||
|
||||
### Available Roles Reference
|
||||
|
||||
**Technical Roles**:
|
||||
- `system-architect`: Architecture patterns, scalability, technology stack, integration
|
||||
- `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, 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
|
||||
|
||||
**Agile & Quality Roles**:
|
||||
- `scrum-master`: Sprint planning, team dynamics, process optimization, delivery management
|
||||
- `test-strategist`: Testing strategies, quality assurance, test automation, validation approaches
|
||||
|
||||
### Architecture Reference
|
||||
- **Workflow Architecture**: @~/.claude/workflows/workflow-architecture.md
|
||||
- **Clarification Plan**: @~/.claude/workflows/brainstorm-clarification-plan.md
|
||||
|
||||
### 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