From acc792907cb3adf2bacc762a969e576c42279481 Mon Sep 17 00:00:00 2001
From: catlog22 <catlog22@github.com>
Date: Fri, 24 Oct 2025 16:35:09 +0800
Subject: [PATCH] docs: refine artifacts command documentation for clarity and
 structure

---
 .../commands/workflow/brainstorm/artifacts.md | 582 ++++++++----------
 1 file changed, 254 insertions(+), 328 deletions(-)

diff --git a/.claude/commands/workflow/brainstorm/artifacts.md b/.claude/commands/workflow/brainstorm/artifacts.md
index 4925b77a..178ed159 100644
--- a/.claude/commands/workflow/brainstorm/artifacts.md
+++ b/.claude/commands/workflow/brainstorm/artifacts.md
@@ -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