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

Refactor workflow to replace synthesis-specification.md with role analysis documents

Browse Source 
- 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
2025-10-24 11:08:15 +08:00
parent ef187d3a4b
commit 57fa379e45
35 changed files with 1835 additions and 1271 deletions
Download Patch File Download Diff File Expand all files Collapse all files

28
.claude/commands/workflow/brainstorm/api-designer.md
View File

@@ -1,6 +1,6 @@
---
name: api-designer
description: Generate or update api-designer/analysis.md addressing topic-framework discussion points
description: Generate or update api-designer/analysis.md addressing guidance-specification discussion points
argument-hint: "optional topic - uses existing framework if available"
allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
---
@@ -8,10 +8,10 @@ allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
## 🔌 **API Designer Analysis Generator**
### Purpose
**Specialized command for generating api-designer/analysis.md** that addresses topic-framework.md discussion points from backend API design perspective. Creates or updates role-specific analysis with framework references.
**Specialized command for generating api-designer/analysis.md** that addresses guidance-specification.md discussion points from backend API design perspective. Creates or updates role-specific analysis with framework references.
### Core Function
- **Framework-based Analysis**: Address each discussion point in topic-framework.md
- **Framework-based Analysis**: Address each discussion point in guidance-specification.md
- **API Design Focus**: RESTful/GraphQL API design, endpoint structure, and contract definition
- **Update Mechanism**: Create new or update existing analysis.md
- **Agent Delegation**: Use conceptual-planning-agent for analysis generation
@@ -51,7 +51,7 @@ IF active_session EXISTS:
session_id = get_active_session()
brainstorm_dir = .workflow/WFS-{session}/.brainstorming/
CHECK: brainstorm_dir/topic-framework.md
CHECK: brainstorm_dir/guidance-specification.md
IF EXISTS:
framework_mode = true
load_framework = true
@@ -78,20 +78,20 @@ ELSE:
```
### Phase 3: Agent Task Generation
**Framework-Based Analysis** (when topic-framework.md exists):
**Framework-Based Analysis** (when guidance-specification.md exists):
```bash
Task(subagent_type="conceptual-planning-agent",
prompt="Generate API designer analysis addressing topic framework
## Framework Integration Required
**MANDATORY**: Load and address topic-framework.md discussion points
**Framework Reference**: @{session.brainstorm_dir}/topic-framework.md
**MANDATORY**: Load and address guidance-specification.md discussion points
**Framework Reference**: @{session.brainstorm_dir}/guidance-specification.md
**Output Location**: {session.brainstorm_dir}/api-designer/analysis.md
## Analysis Requirements
1. **Load Topic Framework**: Read topic-framework.md completely
1. **Load Topic Framework**: Read guidance-specification.md completely
2. **Address Each Discussion Point**: Respond to all 5 framework sections from API design perspective
3. **Include Framework Reference**: Start analysis.md with @../topic-framework.md
3. **Include Framework Reference**: Start analysis.md with @../guidance-specification.md
4. **API Design Focus**: Emphasize endpoint structure, data contracts, versioning strategies
5. **Structured Response**: Use framework structure for analysis organization
@@ -106,7 +106,7 @@ Task(subagent_type="conceptual-planning-agent",
```markdown
# API Designer Analysis: [Topic]
**Framework Reference**: @../topic-framework.md
**Framework Reference**: @../guidance-specification.md
**Role Focus**: Backend API Design and Contract Definition
## Core Requirements Analysis
@@ -140,14 +140,14 @@ IF update_mode = "incremental":
## Current Analysis Context
**Existing Analysis**: @{session.brainstorm_dir}/api-designer/analysis.md
**Framework Reference**: @{session.brainstorm_dir}/topic-framework.md
**Framework Reference**: @{session.brainstorm_dir}/guidance-specification.md
## Update Requirements
1. **Preserve Structure**: Maintain existing analysis structure
2. **Add New Insights**: Integrate new API design insights and recommendations
3. **Framework Alignment**: Ensure continued alignment with topic framework
4. **API Updates**: Add new endpoint patterns, versioning strategies, documentation improvements
5. **Maintain References**: Keep @../topic-framework.md reference
5. **Maintain References**: Keep @../guidance-specification.md reference
## Update Instructions
- Read existing analysis completely
@@ -163,14 +163,14 @@ IF update_mode = "incremental":
### Output Files
```
.workflow/WFS-[topic]/.brainstorming/
├── topic-framework.md # Input: Framework (if exists)
├── guidance-specification.md # Input: Framework (if exists)
└── api-designer/
└── analysis.md # ★ OUTPUT: Framework-based analysis
```
### Analysis Structure
**Required Elements**:
- **Framework Reference**: @../topic-framework.md (if framework exists)
- **Framework Reference**: @../guidance-specification.md (if framework exists)
- **Role Focus**: Backend API Design and Contract Definition perspective
- **5 Framework Sections**: Address each framework discussion point
- **API Design Recommendations**: Endpoint-specific insights and solutions

877
.claude/commands/workflow/brainstorm/artifacts.md
View File

@@ -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

8
.claude/commands/workflow/brainstorm/auto-parallel.md
View File

@@ -173,7 +173,7 @@ Task(subagent_type="conceptual-planning-agent",
1. **load_topic_framework**
- Action: Load structured topic discussion framework
- Command: Read(.workflow/WFS-{topic}/.brainstorming/topic-framework.md)
- Command: Read(.workflow/WFS-{topic}/.brainstorming/guidance-specification.md)
- Output: topic_framework
- Fallback: Continue with session metadata if file not found
@@ -189,7 +189,7 @@ Task(subagent_type="conceptual-planning-agent",
### Implementation Context
**User Intent Authority**: Original user prompt from session_metadata.project is PRIMARY reference
**Topic Framework**: Use loaded topic-framework.md for structured analysis
**Topic Framework**: Use loaded guidance-specification.md for structured analysis
**Role Focus**: {role-name} domain expertise and perspective aligned with user intent
**Analysis Type**: Address framework discussion points from role perspective, filtered by user objectives
**Template Framework**: Combine role template with topic framework structure
@@ -208,13 +208,13 @@ Task(subagent_type="conceptual-planning-agent",
## Completion Requirements
1. Execute all flow control steps in sequence (load topic framework, role template, session metadata with user intent)
2. User Intent Alignment: Validate analysis aligns with original user objectives from session_metadata
3. Address Topic Framework: Respond to all discussion points in topic-framework.md from role perspective
3. Address Topic Framework: Respond to all discussion points in guidance-specification.md from role perspective
4. Filter by User Goals: Prioritize insights directly relevant to user's stated objectives
5. Apply role template guidelines within topic framework structure
6. Generate structured role analysis addressing framework points aligned with user intent
7. Create single comprehensive deliverable in OUTPUT_LOCATION:
- analysis.md (structured analysis addressing all topic framework points with role-specific insights filtered by user goals)
8. Include framework reference: @../topic-framework.md in analysis.md
8. Include framework reference: @../guidance-specification.md in analysis.md
9. Update workflow-session.json with completion status""",
description="Execute {role-name} brainstorming analysis")
```

28
.claude/commands/workflow/brainstorm/data-architect.md
View File

@@ -1,6 +1,6 @@
---
name: data-architect
description: Generate or update data-architect/analysis.md addressing topic-framework discussion points
description: Generate or update data-architect/analysis.md addressing guidance-specification discussion points
argument-hint: "optional topic - uses existing framework if available"
allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
---
@@ -8,10 +8,10 @@ allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
## 📊 **Data Architect Analysis Generator**
### Purpose
**Specialized command for generating data-architect/analysis.md** that addresses topic-framework.md discussion points from data architecture perspective. Creates or updates role-specific analysis with framework references.
**Specialized command for generating data-architect/analysis.md** that addresses guidance-specification.md discussion points from data architecture perspective. Creates or updates role-specific analysis with framework references.
### Core Function
- **Framework-based Analysis**: Address each discussion point in topic-framework.md
- **Framework-based Analysis**: Address each discussion point in guidance-specification.md
- **Data Architecture Focus**: Data models, pipelines, governance, and analytics perspective
- **Update Mechanism**: Create new or update existing analysis.md
- **Agent Delegation**: Use conceptual-planning-agent for analysis generation
@@ -52,7 +52,7 @@ IF active_session EXISTS:
session_id = get_active_session()
brainstorm_dir = .workflow/WFS-{session}/.brainstorming/
CHECK: brainstorm_dir/topic-framework.md
CHECK: brainstorm_dir/guidance-specification.md
IF EXISTS:
framework_mode = true
load_framework = true
@@ -93,7 +93,7 @@ ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"}
## Flow Control Steps
1. **load_topic_framework**
- Action: Load structured topic discussion framework
- Command: Read(.workflow/WFS-{session}/.brainstorming/topic-framework.md)
- Command: Read(.workflow/WFS-{session}/.brainstorming/guidance-specification.md)
- Output: topic_framework_content
2. **load_role_template**
@@ -107,17 +107,17 @@ ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"}
- Output: session_context
## Analysis Requirements
**Framework Reference**: Address all discussion points in topic-framework.md from data architecture perspective
**Framework Reference**: Address all discussion points in guidance-specification.md from data architecture perspective
**Role Focus**: Data models, pipelines, governance, analytics platforms
**Structured Approach**: Create analysis.md addressing framework discussion points
**Template Integration**: Apply role template guidelines within framework structure
## Expected Deliverables
1. **analysis.md**: Comprehensive data architecture analysis addressing all framework discussion points
2. **Framework Reference**: Include @../topic-framework.md reference in analysis
2. **Framework Reference**: Include @../guidance-specification.md reference in analysis
## Completion Criteria
- Address each discussion point from topic-framework.md with data architecture expertise
- Address each discussion point from guidance-specification.md with data architecture expertise
- Provide data model designs, pipeline architectures, and governance strategies
- Include scalability, performance, and quality considerations
- Reference framework document using @ notation for integration
@@ -136,7 +136,7 @@ TodoWrite({
activeForm: "Detecting session and framework"
},
{
content: "Load topic-framework.md and session metadata for context",
content: "Load guidance-specification.md and session metadata for context",
status: "pending",
activeForm: "Loading framework and session context"
},
@@ -164,7 +164,7 @@ TodoWrite({
### Framework-Based Analysis
```
.workflow/WFS-{session}/.brainstorming/data-architect/
└── analysis.md # Structured analysis addressing topic-framework.md discussion points
└── analysis.md # Structured analysis addressing guidance-specification.md discussion points
```
### Analysis Document Structure
@@ -172,11 +172,11 @@ TodoWrite({
# Data Architect Analysis: [Topic from Framework]
## Framework Reference
**Topic Framework**: @../topic-framework.md
**Topic Framework**: @../guidance-specification.md
**Role Focus**: Data Architecture perspective
## Discussion Points Analysis
[Address each point from topic-framework.md with data architecture expertise]
[Address each point from guidance-specification.md with data architecture expertise]
### Core Requirements (from framework)
[Data architecture perspective on requirements]
@@ -209,12 +209,12 @@ TodoWrite({
"status": "completed",
"framework_addressed": true,
"output_location": ".workflow/WFS-{session}/.brainstorming/data-architect/analysis.md",
"framework_reference": "@../topic-framework.md"
"framework_reference": "@../guidance-specification.md"
}
}
```
### Integration Points
- **Framework Reference**: @../topic-framework.md for structured discussion points
- **Framework Reference**: @../guidance-specification.md for structured discussion points
- **Cross-Role Synthesis**: Data architecture insights available for synthesis-report.md integration
- **Agent Autonomy**: Independent execution with framework guidance

28
.claude/commands/workflow/brainstorm/product-manager.md
View File

@@ -1,6 +1,6 @@
---
name: product-manager
description: Generate or update product-manager/analysis.md addressing topic-framework discussion points
description: Generate or update product-manager/analysis.md addressing guidance-specification discussion points
argument-hint: "optional topic - uses existing framework if available"
allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
---
@@ -8,10 +8,10 @@ allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
## 🎯 **Product Manager Analysis Generator**
### Purpose
**Specialized command for generating product-manager/analysis.md** that addresses topic-framework.md discussion points from product strategy perspective. Creates or updates role-specific analysis with framework references.
**Specialized command for generating product-manager/analysis.md** that addresses guidance-specification.md discussion points from product strategy perspective. Creates or updates role-specific analysis with framework references.
### Core Function
- **Framework-based Analysis**: Address each discussion point in topic-framework.md
- **Framework-based Analysis**: Address each discussion point in guidance-specification.md
- **Product Strategy Focus**: User needs, business value, and market positioning
- **Update Mechanism**: Create new or update existing analysis.md
- **Agent Delegation**: Use conceptual-planning-agent for analysis generation
@@ -32,7 +32,7 @@ IF active_session EXISTS:
session_id = get_active_session()
brainstorm_dir = .workflow/WFS-{session}/.brainstorming/
CHECK: brainstorm_dir/topic-framework.md
CHECK: brainstorm_dir/guidance-specification.md
IF EXISTS:
framework_mode = true
load_framework = true
@@ -73,7 +73,7 @@ ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"}
## Flow Control Steps
1. **load_topic_framework**
- Action: Load structured topic discussion framework
- Command: Read(.workflow/WFS-{session}/.brainstorming/topic-framework.md)
- Command: Read(.workflow/WFS-{session}/.brainstorming/guidance-specification.md)
- Output: topic_framework_content
2. **load_role_template**
@@ -87,17 +87,17 @@ ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"}
- Output: session_context
## Analysis Requirements
**Framework Reference**: Address all discussion points in topic-framework.md from product strategy perspective
**Framework Reference**: Address all discussion points in guidance-specification.md from product strategy perspective
**Role Focus**: User value, business impact, market positioning, product strategy
**Structured Approach**: Create analysis.md addressing framework discussion points
**Template Integration**: Apply role template guidelines within framework structure
## Expected Deliverables
1. **analysis.md**: Comprehensive product strategy analysis addressing all framework discussion points
2. **Framework Reference**: Include @../topic-framework.md reference in analysis
2. **Framework Reference**: Include @../guidance-specification.md reference in analysis
## Completion Criteria
- Address each discussion point from topic-framework.md with product management expertise
- Address each discussion point from guidance-specification.md with product management expertise
- Provide actionable business strategies and user value propositions
- Include market analysis and competitive positioning insights
- Reference framework document using @ notation for integration
@@ -116,7 +116,7 @@ TodoWrite({
activeForm: "Detecting session and framework"
},
{
content: "Load topic-framework.md and session metadata for context",
content: "Load guidance-specification.md and session metadata for context",
status: "pending",
activeForm: "Loading framework and session context"
},
@@ -144,7 +144,7 @@ TodoWrite({
### Framework-Based Analysis
```
.workflow/WFS-{session}/.brainstorming/product-manager/
└── analysis.md # Structured analysis addressing topic-framework.md discussion points
└── analysis.md # Structured analysis addressing guidance-specification.md discussion points
```
### Analysis Document Structure
@@ -152,11 +152,11 @@ TodoWrite({
# Product Manager Analysis: [Topic from Framework]
## Framework Reference
**Topic Framework**: @../topic-framework.md
**Topic Framework**: @../guidance-specification.md
**Role Focus**: Product Strategy perspective
## Discussion Points Analysis
[Address each point from topic-framework.md with product management expertise]
[Address each point from guidance-specification.md with product management expertise]
### Core Requirements (from framework)
[Product strategy perspective on user needs and requirements]
@@ -189,12 +189,12 @@ TodoWrite({
"status": "completed",
"framework_addressed": true,
"output_location": ".workflow/WFS-{session}/.brainstorming/product-manager/analysis.md",
"framework_reference": "@../topic-framework.md"
"framework_reference": "@../guidance-specification.md"
}
}
```
### Integration Points
- **Framework Reference**: @../topic-framework.md for structured discussion points
- **Framework Reference**: @../guidance-specification.md for structured discussion points
- **Cross-Role Synthesis**: Product strategy insights available for synthesis-report.md integration
- **Agent Autonomy**: Independent execution with framework guidance

28
.claude/commands/workflow/brainstorm/product-owner.md
View File

@@ -1,6 +1,6 @@
---
name: product-owner
description: Generate or update product-owner/analysis.md addressing topic-framework discussion points
description: Generate or update product-owner/analysis.md addressing guidance-specification discussion points
argument-hint: "optional topic - uses existing framework if available"
allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
---
@@ -8,10 +8,10 @@ allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
## 🎯 **Product Owner Analysis Generator**
### Purpose
**Specialized command for generating product-owner/analysis.md** that addresses topic-framework.md discussion points from product backlog and feature prioritization perspective. Creates or updates role-specific analysis with framework references.
**Specialized command for generating product-owner/analysis.md** that addresses guidance-specification.md discussion points from product backlog and feature prioritization perspective. Creates or updates role-specific analysis with framework references.
### Core Function
- **Framework-based Analysis**: Address each discussion point in topic-framework.md
- **Framework-based Analysis**: Address each discussion point in guidance-specification.md
- **Product Backlog Focus**: Feature prioritization, user stories, and acceptance criteria
- **Update Mechanism**: Create new or update existing analysis.md
- **Agent Delegation**: Use conceptual-planning-agent for analysis generation
@@ -32,7 +32,7 @@ IF active_session EXISTS:
session_id = get_active_session()
brainstorm_dir = .workflow/WFS-{session}/.brainstorming/
CHECK: brainstorm_dir/topic-framework.md
CHECK: brainstorm_dir/guidance-specification.md
IF EXISTS:
framework_mode = true
load_framework = true
@@ -73,7 +73,7 @@ ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"}
## Flow Control Steps
1. **load_topic_framework**
- Action: Load structured topic discussion framework
- Command: Read(.workflow/WFS-{session}/.brainstorming/topic-framework.md)
- Command: Read(.workflow/WFS-{session}/.brainstorming/guidance-specification.md)
- Output: topic_framework_content
2. **load_role_template**
@@ -87,17 +87,17 @@ ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"}
- Output: session_context
## Analysis Requirements
**Framework Reference**: Address all discussion points in topic-framework.md from product backlog and feature prioritization perspective
**Framework Reference**: Address all discussion points in guidance-specification.md from product backlog and feature prioritization perspective
**Role Focus**: Backlog management, stakeholder alignment, feature prioritization, acceptance criteria
**Structured Approach**: Create analysis.md addressing framework discussion points
**Template Integration**: Apply role template guidelines within framework structure
## Expected Deliverables
1. **analysis.md**: Comprehensive product ownership analysis addressing all framework discussion points
2. **Framework Reference**: Include @../topic-framework.md reference in analysis
2. **Framework Reference**: Include @../guidance-specification.md reference in analysis
## Completion Criteria
- Address each discussion point from topic-framework.md with product ownership expertise
- Address each discussion point from guidance-specification.md with product ownership expertise
- Provide actionable user stories and acceptance criteria definitions
- Include feature prioritization and stakeholder alignment strategies
- Reference framework document using @ notation for integration
@@ -116,7 +116,7 @@ TodoWrite({
activeForm: "Detecting session and framework"
},
{
content: "Load topic-framework.md and session metadata for context",
content: "Load guidance-specification.md and session metadata for context",
status: "pending",
activeForm: "Loading framework and session context"
},
@@ -144,7 +144,7 @@ TodoWrite({
### Framework-Based Analysis
```
.workflow/WFS-{session}/.brainstorming/product-owner/
└── analysis.md # Structured analysis addressing topic-framework.md discussion points
└── analysis.md # Structured analysis addressing guidance-specification.md discussion points
```
### Analysis Document Structure
@@ -152,11 +152,11 @@ TodoWrite({
# Product Owner Analysis: [Topic from Framework]
## Framework Reference
**Topic Framework**: @../topic-framework.md
**Topic Framework**: @../guidance-specification.md
**Role Focus**: Product Backlog & Feature Prioritization perspective
## Discussion Points Analysis
[Address each point from topic-framework.md with product ownership expertise]
[Address each point from guidance-specification.md with product ownership expertise]
### Core Requirements (from framework)
[User story formulation and backlog refinement perspective]
@@ -189,12 +189,12 @@ TodoWrite({
"status": "completed",
"framework_addressed": true,
"output_location": ".workflow/WFS-{session}/.brainstorming/product-owner/analysis.md",
"framework_reference": "@../topic-framework.md"
"framework_reference": "@../guidance-specification.md"
}
}
```
### Integration Points
- **Framework Reference**: @../topic-framework.md for structured discussion points
- **Framework Reference**: @../guidance-specification.md for structured discussion points
- **Cross-Role Synthesis**: Product ownership insights available for synthesis-report.md integration
- **Agent Autonomy**: Independent execution with framework guidance

28
.claude/commands/workflow/brainstorm/scrum-master.md
View File

@@ -1,6 +1,6 @@
---
name: scrum-master
description: Generate or update scrum-master/analysis.md addressing topic-framework discussion points
description: Generate or update scrum-master/analysis.md addressing guidance-specification discussion points
argument-hint: "optional topic - uses existing framework if available"
allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
---
@@ -8,10 +8,10 @@ allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
## 🎯 **Scrum Master Analysis Generator**
### Purpose
**Specialized command for generating scrum-master/analysis.md** that addresses topic-framework.md discussion points from agile process and team collaboration perspective. Creates or updates role-specific analysis with framework references.
**Specialized command for generating scrum-master/analysis.md** that addresses guidance-specification.md discussion points from agile process and team collaboration perspective. Creates or updates role-specific analysis with framework references.
### Core Function
- **Framework-based Analysis**: Address each discussion point in topic-framework.md
- **Framework-based Analysis**: Address each discussion point in guidance-specification.md
- **Agile Process Focus**: Sprint planning, team dynamics, and delivery optimization
- **Update Mechanism**: Create new or update existing analysis.md
- **Agent Delegation**: Use conceptual-planning-agent for analysis generation
@@ -32,7 +32,7 @@ IF active_session EXISTS:
session_id = get_active_session()
brainstorm_dir = .workflow/WFS-{session}/.brainstorming/
CHECK: brainstorm_dir/topic-framework.md
CHECK: brainstorm_dir/guidance-specification.md
IF EXISTS:
framework_mode = true
load_framework = true
@@ -73,7 +73,7 @@ ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"}
## Flow Control Steps
1. **load_topic_framework**
- Action: Load structured topic discussion framework
- Command: Read(.workflow/WFS-{session}/.brainstorming/topic-framework.md)
- Command: Read(.workflow/WFS-{session}/.brainstorming/guidance-specification.md)
- Output: topic_framework_content
2. **load_role_template**
@@ -87,17 +87,17 @@ ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"}
- Output: session_context
## Analysis Requirements
**Framework Reference**: Address all discussion points in topic-framework.md from agile process and team collaboration perspective
**Framework Reference**: Address all discussion points in guidance-specification.md from agile process and team collaboration perspective
**Role Focus**: Sprint planning, team dynamics, process optimization, delivery management
**Structured Approach**: Create analysis.md addressing framework discussion points
**Template Integration**: Apply role template guidelines within framework structure
## Expected Deliverables
1. **analysis.md**: Comprehensive agile process analysis addressing all framework discussion points
2. **Framework Reference**: Include @../topic-framework.md reference in analysis
2. **Framework Reference**: Include @../guidance-specification.md reference in analysis
## Completion Criteria
- Address each discussion point from topic-framework.md with scrum mastery expertise
- Address each discussion point from guidance-specification.md with scrum mastery expertise
- Provide actionable sprint planning and team facilitation strategies
- Include process optimization and impediment removal insights
- Reference framework document using @ notation for integration
@@ -116,7 +116,7 @@ TodoWrite({
activeForm: "Detecting session and framework"
},
{
content: "Load topic-framework.md and session metadata for context",
content: "Load guidance-specification.md and session metadata for context",
status: "pending",
activeForm: "Loading framework and session context"
},
@@ -144,7 +144,7 @@ TodoWrite({
### Framework-Based Analysis
```
.workflow/WFS-{session}/.brainstorming/scrum-master/
└── analysis.md # Structured analysis addressing topic-framework.md discussion points
└── analysis.md # Structured analysis addressing guidance-specification.md discussion points
```
### Analysis Document Structure
@@ -152,11 +152,11 @@ TodoWrite({
# Scrum Master Analysis: [Topic from Framework]
## Framework Reference
**Topic Framework**: @../topic-framework.md
**Topic Framework**: @../guidance-specification.md
**Role Focus**: Agile Process & Team Collaboration perspective
## Discussion Points Analysis
[Address each point from topic-framework.md with scrum mastery expertise]
[Address each point from guidance-specification.md with scrum mastery expertise]
### Core Requirements (from framework)
[Sprint planning and iteration breakdown perspective]
@@ -189,12 +189,12 @@ TodoWrite({
"status": "completed",
"framework_addressed": true,
"output_location": ".workflow/WFS-{session}/.brainstorming/scrum-master/analysis.md",
"framework_reference": "@../topic-framework.md"
"framework_reference": "@../guidance-specification.md"
}
}
```
### Integration Points
- **Framework Reference**: @../topic-framework.md for structured discussion points
- **Framework Reference**: @../guidance-specification.md for structured discussion points
- **Cross-Role Synthesis**: Agile process insights available for synthesis-report.md integration
- **Agent Autonomy**: Independent execution with framework guidance

28
.claude/commands/workflow/brainstorm/subject-matter-expert.md
View File

@@ -1,6 +1,6 @@
---
name: subject-matter-expert
description: Generate or update subject-matter-expert/analysis.md addressing topic-framework discussion points
description: Generate or update subject-matter-expert/analysis.md addressing guidance-specification discussion points
argument-hint: "optional topic - uses existing framework if available"
allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
---
@@ -8,10 +8,10 @@ allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
## 🎯 **Subject Matter Expert Analysis Generator**
### Purpose
**Specialized command for generating subject-matter-expert/analysis.md** that addresses topic-framework.md discussion points from domain knowledge and technical expertise perspective. Creates or updates role-specific analysis with framework references.
**Specialized command for generating subject-matter-expert/analysis.md** that addresses guidance-specification.md discussion points from domain knowledge and technical expertise perspective. Creates or updates role-specific analysis with framework references.
### Core Function
- **Framework-based Analysis**: Address each discussion point in topic-framework.md
- **Framework-based Analysis**: Address each discussion point in guidance-specification.md
- **Domain Expertise Focus**: Deep technical knowledge, industry standards, and best practices
- **Update Mechanism**: Create new or update existing analysis.md
- **Agent Delegation**: Use conceptual-planning-agent for analysis generation
@@ -32,7 +32,7 @@ IF active_session EXISTS:
session_id = get_active_session()
brainstorm_dir = .workflow/WFS-{session}/.brainstorming/
CHECK: brainstorm_dir/topic-framework.md
CHECK: brainstorm_dir/guidance-specification.md
IF EXISTS:
framework_mode = true
load_framework = true
@@ -73,7 +73,7 @@ ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"}
## Flow Control Steps
1. **load_topic_framework**
- Action: Load structured topic discussion framework
- Command: Read(.workflow/WFS-{session}/.brainstorming/topic-framework.md)
- Command: Read(.workflow/WFS-{session}/.brainstorming/guidance-specification.md)
- Output: topic_framework_content
2. **load_role_template**
@@ -87,17 +87,17 @@ ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"}
- Output: session_context
## Analysis Requirements
**Framework Reference**: Address all discussion points in topic-framework.md from domain expertise and technical standards perspective
**Framework Reference**: Address all discussion points in guidance-specification.md from domain expertise and technical standards perspective
**Role Focus**: Domain knowledge, technical standards, risk assessment, knowledge transfer
**Structured Approach**: Create analysis.md addressing framework discussion points
**Template Integration**: Apply role template guidelines within framework structure
## Expected Deliverables
1. **analysis.md**: Comprehensive domain expertise analysis addressing all framework discussion points
2. **Framework Reference**: Include @../topic-framework.md reference in analysis
2. **Framework Reference**: Include @../guidance-specification.md reference in analysis
## Completion Criteria
- Address each discussion point from topic-framework.md with subject matter expertise
- Address each discussion point from guidance-specification.md with subject matter expertise
- Provide actionable technical standards and best practices recommendations
- Include risk assessment and compliance considerations
- Reference framework document using @ notation for integration
@@ -116,7 +116,7 @@ TodoWrite({
activeForm: "Detecting session and framework"
},
{
content: "Load topic-framework.md and session metadata for context",
content: "Load guidance-specification.md and session metadata for context",
status: "pending",
activeForm: "Loading framework and session context"
},
@@ -144,7 +144,7 @@ TodoWrite({
### Framework-Based Analysis
```
.workflow/WFS-{session}/.brainstorming/subject-matter-expert/
└── analysis.md # Structured analysis addressing topic-framework.md discussion points
└── analysis.md # Structured analysis addressing guidance-specification.md discussion points
```
### Analysis Document Structure
@@ -152,11 +152,11 @@ TodoWrite({
# Subject Matter Expert Analysis: [Topic from Framework]
## Framework Reference
**Topic Framework**: @../topic-framework.md
**Topic Framework**: @../guidance-specification.md
**Role Focus**: Domain Expertise & Technical Standards perspective
## Discussion Points Analysis
[Address each point from topic-framework.md with subject matter expertise]
[Address each point from guidance-specification.md with subject matter expertise]
### Core Requirements (from framework)
[Domain-specific requirements and industry standards perspective]
@@ -189,12 +189,12 @@ TodoWrite({
"status": "completed",
"framework_addressed": true,
"output_location": ".workflow/WFS-{session}/.brainstorming/subject-matter-expert/analysis.md",
"framework_reference": "@../topic-framework.md"
"framework_reference": "@../guidance-specification.md"
}
}
```
### Integration Points
- **Framework Reference**: @../topic-framework.md for structured discussion points
- **Framework Reference**: @../guidance-specification.md for structured discussion points
- **Cross-Role Synthesis**: Domain expertise insights available for synthesis-report.md integration
- **Agent Autonomy**: Independent execution with framework guidance

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

@@ -1,55 +1,59 @@
---
name: synthesis
description: Generate synthesis-specification.md from topic-framework and role analyses with @ references using conceptual-planning-agent
description: Analyze role analyses, identify ambiguities through clarification, and update role documents intelligently using conceptual-planning-agent
argument-hint: "[optional: --session session-id]"
allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*), Edit(*), Glob(*), AskUserQuestion(*)
---
## 🧩 **Synthesis Document Generator**
## 🧩 **Role Analysis Clarification & Refinement**
### Core Function
**Specialized command for generating synthesis-specification.md** that integrates topic-framework.md and all role analysis.md files using @ reference system. Creates comprehensive implementation specification with cross-role insights.
**Specialized command for analyzing and refining role analysis documents** through intelligent clarification. Agent performs cross-role integration analysis, identifies ambiguities and gaps, interacts with user to clarify uncertainties, and intelligently updates relevant role analysis.md files.
**Dynamic Role Discovery**: Automatically detects which roles participated in brainstorming by scanning for `*/analysis.md` files. Synthesizes only actual participating roles, not predefined lists.
**Dynamic Role Discovery**: Automatically detects which roles participated in brainstorming by scanning for `*/analysis.md` files. Analyzes only actual participating roles, not predefined lists.
### Primary Capabilities
- **Dynamic Role Discovery**: Automatically identifies participating roles at runtime
- **Framework Integration**: Reference topic-framework.md discussion points across all discovered roles
- **Role Analysis Integration**: Consolidate all discovered role/analysis.md files using @ references
- **Cross-Framework Comparison**: Compare how each participating role addressed framework discussion points
- **@ Reference System**: Create structured references to source documents
- **Update Detection**: Smart updates when new role analyses are added
- **Flexible Participation**: Supports any subset of available roles (1 to 9+)
- **Cross-Role Integration Analysis**: Internal analysis of consistency, conflicts, and gaps across roles
- **Ambiguity Detection**: Systematic scanning using 8-category taxonomy (user intent, requirements, architecture, etc.)
- **Interactive Clarification**: Priority-based question queue (max 5 questions) with user interaction
- **Intelligent Document Update**: Agent autonomously determines which role documents to update based on clarification answers
- **User Intent Validation**: Ensures role analyses align with user's original goals
### Document Integration Model
**Three-Document Reference System**:
1. **topic-framework.md** → Structured discussion framework (input)
2. **[role]/analysis.md** → Role-specific analyses addressing framework (input)
3. **synthesis-specification.md** → Complete integrated specification (output)
**Role-Centric Architecture**:
1. **[role]/analysis.md** → Individual role analyses (input & output)
2. **guidance-specification.md** → Structured discussion framework (reference)
3. **User's Original Intent** → Primary alignment reference (from session metadata)
4. **Updated [role]/analysis.md** → Refined role analyses after clarification (output)
## ⚙️ **Execution Protocol**
### ⚠️ Agent Execution with Flow Control
**Execution Model**: Uses conceptual-planning-agent for synthesis generation with structured file loading.
### ⚠️ Agent Execution with Interactive Clarification
**Execution Model**: Uses conceptual-planning-agent for cross-role analysis, clarification generation, user interaction, and intelligent document updates.
**Rationale**:
- **Autonomous Execution**: Agent independently loads and processes all required documents
- **Flow Control**: Structured document loading ensures systematic analysis
- **Complex Cognitive Analysis**: Leverages agent's analytical capabilities for cross-role synthesis
- **Autonomous Analysis**: Agent independently loads and analyzes all role documents
- **Cognitive Complexity**: Leverages agent's capabilities for cross-role synthesis and ambiguity detection
- **Interactive Intelligence**: Agent manages question prioritization and document update decisions
- **Conceptual Focus**: Agent specializes in conceptual analysis and multi-perspective integration
**Agent Responsibility**: All file reading and synthesis generation performed by conceptual-planning-agent with FLOW_CONTROL instructions.
**Agent Responsibility**: All file reading, analysis, clarification interaction, and document updates performed by conceptual-planning-agent.
### 📋 Task Tracking Protocol
Initialize synthesis task tracking using TodoWrite at command start:
Initialize clarification task tracking using TodoWrite at command start:
```json
[
{"content": "Detect active session and validate topic-framework.md existence", "status": "in_progress", "activeForm": "Detecting session and validating framework"},
{"content": "Detect active session and validate role analyses existence", "status": "in_progress", "activeForm": "Detecting session and validating analyses"},
{"content": "Discover participating role analyses dynamically", "status": "pending", "activeForm": "Discovering role analyses"},
{"content": "Check existing synthesis and confirm user action", "status": "pending", "activeForm": "Checking update mechanism"},
{"content": "Execute synthesis generation using conceptual-planning-agent with FLOW_CONTROL", "status": "pending", "activeForm": "Executing agent-based synthesis generation"},
{"content": "Agent performs cross-role analysis and generates synthesis-specification.md", "status": "pending", "activeForm": "Agent analyzing and generating synthesis"},
{"content": "Update workflow-session.json with synthesis completion status", "status": "pending", "activeForm": "Updating session metadata"}
{"content": "Execute cross-role integration analysis using conceptual-planning-agent", "status": "pending", "activeForm": "Executing agent-based cross-role analysis"},
{"content": "Execute CLI-powered concept enhancement analysis", "status": "pending", "activeForm": "Executing concept enhancement analysis"},
{"content": "Present enhancement points and get user confirmation", "status": "pending", "activeForm": "Presenting enhancement points for user confirmation"},
{"content": "Apply selected enhancements to role analysis documents", "status": "pending", "activeForm": "Applying selected enhancements"},
{"content": "Agent performs ambiguity detection and generates clarification questions", "status": "pending", "activeForm": "Agent detecting ambiguities and generating questions"},
{"content": "Interactive clarification loop with user (max 5 questions)", "status": "pending", "activeForm": "Interactive clarification with user"},
{"content": "Agent intelligently updates relevant role analysis documents", "status": "pending", "activeForm": "Agent updating role documents"},
{"content": "Update workflow-session.json with clarification completion status", "status": "pending", "activeForm": "Updating session metadata"}
]
```
@@ -68,18 +72,23 @@ ELSE:
brainstorm_dir = .workflow/WFS-{session}/.brainstorming/
# Validate required documents
CHECK: brainstorm_dir/topic-framework.md
# Validate topic framework (optional but recommended)
CHECK: brainstorm_dir/guidance-specification.md
IF NOT EXISTS:
ERROR: "topic-framework.md not found. Run /workflow:brainstorm:artifacts first"
WARN: "guidance-specification.md not found. Analysis will rely on role documents only."
# Validate role analyses exist
role_analyses = Glob(brainstorm_dir/*/analysis*.md)
IF role_analyses is empty:
ERROR: "No role analysis files found. Run role brainstorming commands first."
EXIT
# Load user's original prompt from session metadata
session_metadata = Read(.workflow/WFS-{session}/workflow-session.json)
original_user_prompt = session_metadata.project || session_metadata.description
IF NOT original_user_prompt:
WARN: "No original user prompt found in session metadata"
original_user_prompt = "Not available"
original_user_intent = session_metadata.project || session_metadata.description
IF NOT original_user_intent:
WARN: "No original user intent found in session metadata"
original_user_intent = "Not available"
```
### Phase 2: Role Analysis Discovery
@@ -101,69 +110,57 @@ FIND_ANALYSES: [
# - data-architect
# - subject-matter-expert
# - test-strategist
# - api-designer
LOAD_DOCUMENTS: {
"original_user_prompt": original_user_prompt (from session metadata),
"topic_framework": topic-framework.md,
"original_user_intent": original_user_intent (from session metadata),
"topic_framework": guidance-specification.md (if exists),
"role_analyses": [dynamically discovered analysis*.md files],
"participating_roles": [extract role names from discovered directories],
"existing_synthesis": synthesis-specification.md (if exists)
"participating_roles": [extract role names from discovered directories]
}
# Note: Not all roles participate in every brainstorming session
# Only synthesize roles that actually produced analysis*.md files
# Only analyze roles that actually produced analysis*.md files
# Each role may have 1-3 analysis files: analysis.md OR analysis-1.md, analysis-2.md, analysis-3.md
# CRITICAL: Original user prompt MUST be primary reference for synthesis
# CRITICAL: Original user intent MUST be primary reference for validation
```
### Phase 3: Update Mechanism Check
```bash
# Check for existing synthesis
IF synthesis-specification.md EXISTS:
SHOW current synthesis summary to user
ASK: "Synthesis exists. Do you want to:"
OPTIONS:
1. "Regenerate completely" → Create new synthesis
2. "Update with new analyses" → Integrate new role analyses
3. "Preserve existing" → Exit without changes
ELSE:
CREATE new synthesis
```
### Phase 3: Agent Execution with Interactive Clarification
**Clarification & Update using conceptual-planning-agent**
### Phase 4: Agent Execution with Flow Control
**Synthesis Generation using conceptual-planning-agent**
Delegate synthesis generation to conceptual-planning-agent with structured file loading:
Delegate analysis, clarification, and update to conceptual-planning-agent:
```bash
Task(conceptual-planning-agent): "
[FLOW_CONTROL]
[INTERACTIVE_CLARIFICATION_WORKFLOW]
Execute comprehensive synthesis generation from topic framework and role analyses
Execute comprehensive cross-role analysis, ambiguity detection, user clarification, and intelligent document updates
## Context Loading
OUTPUT_FILE: synthesis-specification.md
OUTPUT_PATH: .workflow/WFS-{session}/.brainstorming/synthesis-specification.md
SESSION_ID: {session_id}
ANALYSIS_MODE: cross_role_synthesis
BRAINSTORM_DIR: .workflow/WFS-{session}/.brainstorming/
ANALYSIS_MODE: cross_role_clarification_and_update
MAX_QUESTIONS: 5
## ⚠️ CRITICAL: User Intent Authority
**ORIGINAL USER PROMPT IS THE PRIMARY REFERENCE**: {original_user_prompt}
All synthesis MUST align with user's original intent. Topic framework and role analyses are supplementary context.
**ORIGINAL USER INTENT IS THE PRIMARY REFERENCE**: {original_user_intent}
All analysis and updates MUST align with user's original intent. Topic framework and role analyses are supplementary context.
## Flow Control Steps
1. **load_original_user_prompt**
## Workflow Steps
### Step 1: Load All Context Documents
1. **load_original_user_intent**
- Action: Load user's original intent from session metadata
- Command: Read(.workflow/WFS-{session}/workflow-session.json)
- Extract: project field or description field
- Output: original_user_prompt (PRIMARY REFERENCE)
- Output: original_user_intent (PRIMARY REFERENCE)
- Priority: HIGHEST - This is the authoritative source of user intent
2. **load_topic_framework**
- Action: Load structured topic discussion framework
- Command: Read(.workflow/WFS-{session}/.brainstorming/topic-framework.md)
- Action: Load structured topic discussion framework (optional)
- Command: Read(.workflow/WFS-{session}/.brainstorming/guidance-specification.md) [if exists]
- Output: topic_framework_content
- Note: Validate alignment with original_user_prompt
- Note: Validate alignment with original_user_intent
3. **discover_role_analyses**
- Action: Dynamically discover all participating role analysis files (supports multiple files per role)
@@ -174,78 +171,347 @@ All synthesis MUST align with user's original intent. Topic framework and role a
4. **load_role_analyses**
- Action: Load all discovered role analysis documents
- Command: Read(each path from role_analysis_paths)
- Output: role_analyses_content
- Note: Filter insights relevant to original_user_prompt
- Output: role_analyses_content_map = {role_name: [analysis_content_1, analysis_content_2, ...]}
- Note: Maintain role-to-content mapping for intelligent updates
5. **check_existing_synthesis**
- Action: Check if synthesis-specification.md already exists
- Command: Read(.workflow/WFS-{session}/.brainstorming/synthesis-specification.md) [if exists]
- Output: existing_synthesis_content [optional]
### Step 2: Cross-Role Integration Analysis (Internal)
Perform internal cross-role analysis following these steps (DO NOT OUTPUT TO USER):
6. **load_synthesis_template**
- Action: Load synthesis role template for structure and guidelines
- Command: Read(~/.claude/workflows/cli-templates/planning-roles/synthesis-role.md)
- Output: synthesis_template_guidelines
1. **Consensus Identification**: Identify common themes and agreement areas across all participating roles
2. **Conflict Detection**: Document conflicting views and track which specific roles disagree on each point
3. **Gap Analysis**: Identify missing information, underspecified areas, and ambiguous points
4. **User Intent Alignment Check**: Validate all role analyses align with user's original intent
5. **Innovation Extraction**: Identify breakthrough ideas and cross-role synergy opportunities
## Synthesis Requirements
### Step 2.5: Concept Enhancement (CLI-Powered)
Execute CLI-powered concept enhancement analysis to identify improvement opportunities:
### ⚠️ PRIMARY REQUIREMENT: User Intent Alignment
**User's Original Goal is Supreme**: Synthesis MUST directly address {original_user_prompt}
**Intent Validation**: Every requirement, design decision, and recommendation must trace back to user's original intent
**Deviation Detection**: Flag any role analysis points that drift from user's stated goals
**Refocus Mechanism**: When role discussions diverge, explicitly refocus on original user prompt
**Traceability**: Each section should reference how it fulfills user's original intent
**Purpose**: Enhance role analyses with deeper architectural insights and best practices
### Core Integration
**Cross-Role Analysis**: Integrate all discovered role analyses with comprehensive coverage
**Framework Integration**: Address how each role responded to topic-framework.md discussion points
**User Intent Filter**: Prioritize insights that directly serve user's original prompt
**Decision Transparency**: Document both adopted solutions and rejected alternatives with rationale
**Process Integration**: Include team capability gaps, process risks, and collaboration patterns
**Visual Documentation**: Include key diagrams (architecture, data model, user journey) via Mermaid
**Priority Matrix**: Create quantified recommendation matrix aligned with user's goals
**Actionable Plan**: Provide phased implementation roadmap addressing user's original objectives
**CLI Execution**:
\`\`\`bash
cd .workflow/WFS-{session}/.brainstorming && gemini -p "
PURPOSE: Analyze role analyses for concept enhancement opportunities
TASK:
• Review all role analysis documents for architectural depth
• Identify underspecified design decisions
• Suggest concrete improvements with rationale
• Focus on technical feasibility and best practices
MODE: analysis
CONTEXT: @**/* @{session_metadata}
EXPECTED: Enhancement points list with specific recommendations
RULES: Focus on actionable improvements that add architectural value
" -m gemini-2.5-pro
\`\`\`
### Cross-Role Analysis Process (Agent Internal Execution)
Perform systematic cross-role analysis following these steps:
**Fallback**: If CLI unavailable, use Claude analysis with Read tool
1. **Data Collection**: Extract key insights, recommendations, concerns, and diagrams from each discovered role analysis
2. **Consensus Identification**: Identify common themes and agreement areas across all participating roles
3. **Disagreement Analysis**: Document conflicting views and track which specific roles disagree on each point
4. **Innovation Extraction**: Identify breakthrough ideas and cross-role synergy opportunities
5. **Priority Scoring**: Calculate multi-dimensional priority scores (impact, feasibility, effort, risk) for each recommendation
6. **Decision Matrix**: Create comprehensive evaluation matrix and sort recommendations by priority
**Enhancement Points Output**:
Generate list of enhancement opportunities:
\`\`\`markdown
### Enhancement Points
## Synthesis Quality Standards
Follow synthesis-specification.md structure defined in synthesis-role.md template:
- Use template structure for comprehensive document organization
- Apply analysis guidelines for cross-role synthesis process
- Include all required sections from template (Executive Summary, Key Designs, Requirements, etc.)
- Follow @ reference system for traceability to source role analyses
- Apply quality standards from template (completeness, visual clarity, decision transparency)
- Validate output against template's output validation checklist
**EP-001: {title}**
- **Affected Roles**: {role_list}
- **Category**: {Architecture | Design | Requirements | Risk}
- **Current State**: {what_exists_now}
- **Enhancement**: {what_to_add_or_improve}
- **Rationale**: {why_this_improves_quality}
- **Priority**: {Critical | High | Medium}
## Expected Deliverables
1. **synthesis-specification.md**: Complete integrated specification consolidating all role perspectives
2. **@ References**: Include cross-references to source role analyses
3. **Session Metadata Update**: Update workflow-session.json with synthesis completion status
**EP-002: {title}**
...
\`\`\`
**User Confirmation**:
Present enhancement points to user using AskUserQuestion:
- Show top 3-5 enhancement opportunities
- User selects which enhancements to apply
- User can skip all if satisfied with current analyses
**Apply Selected Enhancements**:
For each user-approved enhancement:
1. Identify affected role analysis files
2. Update relevant sections in analysis.md files
3. Add enhancement record to "## Enhancements" section
4. Maintain consistency across updated documents
**Enhancement Record Format**:
\`\`\`markdown
## Enhancements
### Session {date}
- **EP-001**: {title} - Applied to {section_name}
- Enhancement: {brief_description}
\`\`\`
### Step 3: Ambiguity & Coverage Scan (Internal)
Perform structured scan using this taxonomy. For each category, mark status: **Clear** / **Partial** / **Missing**.
**⚠️ User Intent Alignment** (HIGHEST PRIORITY):
- [ ] Role analyses alignment with original user intent
- [ ] Goal consistency between analyses and user's stated objectives
- [ ] Scope match with user's requirements
- [ ] Success criteria reflects user's expectations
- [ ] Any unexplained deviations from user intent
**Requirements Clarity**:
- [ ] Functional requirements specificity and measurability
- [ ] Non-functional requirements with quantified targets
- [ ] Business requirements with success metrics
- [ ] Acceptance criteria completeness
**Architecture & Design Clarity**:
- [ ] Architecture decisions with rationale
- [ ] Data model completeness (entities, relationships, constraints)
- [ ] Technology stack justification
- [ ] Integration points and API contracts
**User Experience & Interface**:
- [ ] User journey completeness
- [ ] Critical interaction flows
- [ ] Error/edge case handling
- [ ] Accessibility and localization considerations
**Implementation Feasibility**:
- [ ] Team capability vs. required skills
- [ ] External dependencies and failure modes
- [ ] Resource constraints (timeline, personnel)
- [ ] Technical constraints and tradeoffs
**Risk & Mitigation**:
- [ ] Critical risks identified
- [ ] Mitigation strategies defined
- [ ] Success factors clarity
- [ ] Monitoring and quality gates
**Process & Collaboration**:
- [ ] Role responsibilities and handoffs
- [ ] Collaboration patterns defined
- [ ] Timeline and milestone clarity
- [ ] Dependency management strategy
**Decision Traceability**:
- [ ] Controversial points documented
- [ ] Alternatives considered and rejected
- [ ] Decision rationale clarity
- [ ] Consensus vs. dissent tracking
**Terminology & Consistency**:
- [ ] Canonical terms defined
- [ ] Consistent naming across role analyses
- [ ] No unresolved placeholders (TODO, TBD, ???)
### Step 4: Generate Prioritized Question Queue (Internal)
Internally generate prioritized queue of candidate questions (maximum 5):
**Constraints**:
- Maximum 5 questions per session
- Each question must be answerable with:
* Multiple-choice (2-4 mutually exclusive options), OR
* Short answer (≤5 words)
- Only include questions whose answers materially impact:
* Architecture decisions
* Data modeling
* Task decomposition
* Risk mitigation
* Success criteria
- Ensure category coverage balance
- Favor clarifications that reduce downstream rework risk
**Prioritization Heuristic**:
```
priority_score = (impact_on_planning * 0.4) +
(uncertainty_level * 0.3) +
(risk_if_unresolved * 0.3)
```
**If zero high-impact ambiguities found**: Report success and proceed to Step 7 (Session Metadata Update).
### Step 5: Sequential Clarification Loop (Interactive with User)
Present **EXACTLY ONE** question at a time using AskUserQuestion tool:
**Question Format Template**:
```markdown
**Question {N}/5**: {Question text}
**Category**: {Category name from taxonomy}
**Impact**: {Brief impact description}
**Affects Roles**: {List of roles that will be updated based on answer}
| Option | Description |
|--------|-------------|
| A | {Option A description} |
| B | {Option B description} |
| C | {Option C description} |
| D | {Option D description} |
```
**Answer Handling**:
- Record answer in working memory with metadata: {question, answer, affected_roles, category}
- Store in clarification_results array for later batch processing
- Proceed to next question immediately (DO NOT update documents yet)
**Stop Conditions**:
- All critical ambiguities resolved
- User signals completion ("done", "no more", "proceed")
- Reached 5 questions
**Never reveal future queued questions in advance**.
### Step 6: Intelligent Document Update (Batch Processing)
After all questions answered, process all clarifications in batch:
**For each clarification in clarification_results**:
1. **Determine Affected Roles** (Intelligent Judgment):
- Analyze question category and answer content
- Determine which role documents need updates
- Example mapping:
* Architecture questions → system-architect, data-architect
* UX questions → ui-designer, ux-expert
* Requirements questions → product-manager, product-owner
* Process questions → scrum-master, product-manager
- Cross-cutting concerns may update multiple roles
2. **Create Clarifications Section** (If Not Exists):
```bash
FOR each affected role analysis file:
IF file NOT contains "## Clarifications":
Insert "## Clarifications" section after first heading
IF NOT contains "### Session YYYY-MM-DD":
Create "### Session {today's date}" under "## Clarifications"
APPEND: "- **Q**: {question} ({category})"
APPEND: " **A**: {answer}"
```
3. **Apply Clarification to Relevant Sections**:
```bash
CASE category:
User Intent Alignment → Update "## Overview" or "## Executive Summary"
Functional Requirements → Update "## Requirements" or "## Functional Specifications"
Architecture → Update "## Architecture" or "## Design" sections
User Experience → Update "## UI/UX" or "## User Experience" sections
Risk → Update "## Risks" or "## Risk Assessment" sections
Process → Update "## Process" or "## Implementation" sections
Data Model → Update "## Data Model" or "## Database" sections
Non-Functional → Update "## Non-Functional Requirements" or equivalent
```
4. **Remove Contradictions**:
```bash
IF clarification invalidates existing statement:
Replace statement instead of duplicating
Mark removed content with comment: <!-- Superseded by clarification {date} -->
```
5. **Maintain Consistency**:
- Update terminology throughout document if clarification defines canonical terms
- Remove placeholders (TODO, TBD, ???) that were addressed
- Ensure no contradictory statements remain
6. **Save Updates**:
```bash
FOR each modified role analysis file:
Write(file_path, updated_content)
```
### Step 7: Validation After Updates
Verify all updates meet quality standards:
- [ ] Clarifications section contains exactly one bullet per question per affected role
- [ ] Total asked questions ≤ 5
- [ ] Updated sections contain no lingering placeholders
- [ ] No contradictory earlier statements remain
- [ ] Markdown structure valid in all updated files
- [ ] Terminology consistent across all updated role analyses
- [ ] User intent alignment explicitly validated in affected documents
### Step 8: Completion Report
Generate comprehensive completion report for user:
```markdown
## ✅ Role Analysis Clarification Complete
**Session**: WFS-{session-id}
**Questions Asked**: {count}/5
**Role Documents Updated**: {list updated role names}
**Categories Clarified**: {list category names}
### Coverage Summary
| Category | Status | Notes |
|----------|--------|-------|
| User Intent Alignment | ✅ Resolved | Clarified {specific points} |
| Requirements Clarity | ✅ Clear | No ambiguities found |
| Architecture & Design | ⚠️ Partial | {specific gaps if any} |
| User Experience | ✅ Resolved | Updated UI/UX specs |
| Implementation Feasibility | ✅ Clear | Team capabilities validated |
| Risk & Mitigation | ✅ Resolved | Mitigation strategies defined |
| Process & Collaboration | ✅ Clear | Role handoffs clarified |
| Decision Traceability | ✅ Resolved | Alternatives documented |
| Terminology & Consistency | ✅ Resolved | Canonical terms defined |
**Legend**:
- ✅ Resolved: Was Partial/Missing, now addressed
- ✅ Clear: Already sufficient
- ⚠️ Partial: Some gaps remain (details below)
### Document Updates
| Role | Files Updated | Sections Modified |
|------|---------------|-------------------|
{For each updated role}
| {role_name} | {file_name} | {section_list} |
### Clarification Details
{For each clarification}
**Q{N}**: {question}
**A**: {answer}
**Updated Roles**: {affected_roles}
**Category**: {category}
### Recommendations
- ✅ **PROCEED to /workflow:plan**: Conceptual foundation is clear and refined
- OR ⚠️ **Address Outstanding Items First**: {list critical outstanding items if any}
- OR 🔄 **Run /workflow:brainstorm:synthesis Again**: If new information or roles added
### Next Steps
**Standard Workflow (Recommended)**:
```bash
/workflow:plan --session WFS-{session-id} # Generate IMPL_PLAN.md and tasks from role analyses
```
**TDD Workflow**:
```bash
/workflow:tdd-plan --session WFS-{session-id} \"Feature description\"
```
```
## Completion Criteria
- ⚠️ **USER INTENT ALIGNMENT**: Synthesis directly addresses user's original prompt
- All discovered role analyses integrated without gaps
- Framework discussion points addressed across all roles
- **Intent traceability**: Each major section references user's original goals
- Controversial points documented with dissenting roles identified
- Process concerns (team capabilities, risks, collaboration) captured
- Quantified priority recommendations aligned with user's objectives
- Actionable implementation plan addressing user's stated goals
- Comprehensive risk assessment with mitigation strategies
- **Deviation warnings**: Any significant departures from user intent flagged explicitly
- ⚠️ **USER INTENT ALIGNMENT**: Role analyses align with user's original intent
- All participating role analyses loaded and analyzed
- Cross-role integration analysis completed (consensus, conflicts, gaps identified)
- Ambiguity scan completed across all 9 categories
- Clarification questions prioritized (if needed)
- User interaction completed (max 5 questions)
- Affected role documents intelligently updated
- Clarifications section added to updated documents
- Contradictions removed, terminology consistent
- Session metadata updated with clarification results
## Execution Notes
- Dynamic role participation: Only synthesize roles that produced analysis.md files
- Update mechanism: If synthesis exists, prompt user for regenerate/update/preserve decision
- Timeout allocation: Complex synthesis task (60-90 min recommended)
- Dynamic role participation: Only analyze roles that produced analysis.md files
- Internal analysis: Cross-role synthesis performed internally, not shown to user
- Interactive clarification: Present one question at a time
- Intelligent updates: Agent determines affected roles based on answer context
- Batch processing: Update all affected documents after all questions answered
- Timeout allocation: Complex clarification task (60-90 min recommended)
- Reference @intelligent-tools-strategy.md for timeout guidelines
"
```
@@ -253,70 +519,65 @@ Follow synthesis-specification.md structure defined in synthesis-role.md templat
## 📊 **Output Specification**
### Output Location
The synthesis process creates **one consolidated document** that integrates all role perspectives:
The clarification process **refines existing role analysis documents** without creating new consolidated files:
```
.workflow/WFS-{topic-slug}/.brainstorming/
├── topic-framework.md # Input: Framework structure
├── [role]/analysis*.md # Input: Role analyses (supports analysis.md or analysis-1/2/3.md per role)
└── synthesis-specification.md # ★ OUTPUT: Complete integrated specification
├── guidance-specification.md # Input: Framework structure (reference)
├── [role]/analysis*.md # Input & OUTPUT: Role analyses
```
#### synthesis-specification.md Structure
#### Updated Role Analysis Structure
Each updated role analysis.md will contain:
**Document Purpose**: Defines **"WHAT"** to build - comprehensive requirements and design blueprint.
**Scope**: High-level features, requirements, and design specifications. Does NOT include executable task breakdown (that's IMPL_PLAN.md's responsibility).
**New Section - Clarifications**:
```markdown
## Clarifications
### Session 2025-01-15
- **Q**: {Question text} (Category: {category})
**A**: {Answer}
- **Q**: {Question text} (Category: {category})
**A**: {Answer}
```
**Updated Sections**: Existing sections refined based on clarifications:
- User intent alignment validated/corrected
- Requirements made more specific and measurable
- Architecture decisions clarified with rationale
- Ambiguities resolved, placeholders removed
- Terminology made consistent
**Template Reference**: Complete document structure and content guidelines available in `synthesis-role.md` template, including:
- Executive Summary with strategic overview
- Key Designs & Decisions (architecture diagrams, ADRs, user journeys)
- Controversial Points & Alternatives (decision transparency)
- Requirements & Acceptance Criteria (Functional, Non-Functional, Business)
- Design Specifications (UI/UX, Architecture, Domain Expertise)
- Process & Collaboration Concerns (team skills, risks, patterns, constraints)
- Implementation Roadmap (high-level phases)
- Risk Assessment & Mitigation strategies
**Agent Usage**: The conceptual-planning-agent loads this template to understand expected structure and quality standards.
## 🔄 **Session Integration**
### Streamlined Status Synchronization
Upon completion, update `workflow-session.json`:
**Dynamic Role Participation**: The `participating_roles` and `roles_synthesized` values are determined at runtime based on actual analysis.md files discovered.
**Dynamic Role Participation**: The `participating_roles` and `roles_updated` values are determined at runtime based on actual analysis.md files and clarification results.
```json
{
"phases": {
"BRAINSTORM": {
"status": "completed",
"synthesis_completed": true,
"status": "clarification_completed",
"clarification_completed": true,
"completed_at": "timestamp",
"participating_roles": ["<dynamically-discovered-role-1>", "<dynamically-discovered-role-2>", "..."],
"available_roles": ["product-manager", "product-owner", "scrum-master", "system-architect", "ui-designer", "ux-expert", "data-architect", "subject-matter-expert", "test-strategist"],
"consolidated_output": {
"synthesis_specification": ".workflow/WFS-{topic}/.brainstorming/synthesis-specification.md"
"available_roles": ["product-manager", "product-owner", "scrum-master", "system-architect", "ui-designer", "ux-expert", "data-architect", "subject-matter-expert", "test-strategist", "api-designer"],
"clarification_results": {
"questions_asked": <count>,
"categories_clarified": [<list of categories>],
"roles_updated": [<list of updated role names>],
"outstanding_items": []
},
"synthesis_quality": {
"role_integration": "complete",
"quality_metrics": {
"user_intent_alignment": "validated",
"requirement_coverage": "comprehensive",
"decision_transparency": "alternatives_documented",
"process_risks_identified": true,
"implementation_readiness": "ready"
},
"content_metrics": {
"roles_synthesized": "<COUNT(participating_roles)>",
"functional_requirements": "<dynamic-count>",
"non_functional_requirements": "<dynamic-count>",
"business_requirements": "<dynamic-count>",
"architecture_decisions": "<dynamic-count>",
"controversial_points": "<dynamic-count>",
"diagrams_included": "<dynamic-count>",
"process_risks": "<dynamic-count>",
"team_skill_gaps": "<dynamic-count>",
"implementation_phases": "<dynamic-count>",
"risk_factors_identified": "<dynamic-count>"
"ambiguity_resolution": "complete",
"terminology_consistency": "enforced",
"decision_transparency": "documented"
}
}
}
@@ -328,12 +589,13 @@ Upon completion, update `workflow-session.json`:
{
"phases": {
"BRAINSTORM": {
"status": "completed",
"status": "clarification_completed",
"participating_roles": ["product-manager", "system-architect", "ui-designer", "ux-expert", "scrum-master"],
"content_metrics": {
"roles_synthesized": 5,
"functional_requirements": 18,
"controversial_points": 2
"clarification_results": {
"questions_asked": 3,
"categories_clarified": ["Architecture & Design", "User Experience", "Risk & Mitigation"],
"roles_updated": ["system-architect", "ui-designer", "ux-expert"],
"outstanding_items": []
}
}
}
@@ -342,39 +604,45 @@ Upon completion, update `workflow-session.json`:
## ✅ **Quality Assurance**
Verify synthesis output meets these standards (detailed criteria in `synthesis-role.md` template):
Verify clarification output meets these standards:
### Content Completeness
- [ ] All discovered role analyses integrated without gaps
- [ ] Key designs documented (architecture diagrams, ADRs, user journeys via Mermaid)
- [ ] Controversial points captured with alternatives and rationale
- [ ] Process concerns included (team skills, risks, collaboration patterns)
- [ ] Requirements documented (Functional, Non-Functional, Business) with sources
- [ ] All participating role analyses loaded and analyzed
- [ ] Cross-role integration analysis completed (consensus, conflicts, gaps)
- [ ] Ambiguity scan completed across all 9 categories
- [ ] Clarification questions prioritized appropriately
- [ ] All clarifications documented in affected role documents
### Analysis Quality
- [ ] User intent alignment validated across all roles
- [ ] Cross-role synthesis identifies consensus and conflicts
- [ ] Decision transparency documents both adopted and rejected alternatives
- [ ] Priority recommendations with multi-dimensional evaluation
- [ ] Implementation roadmap with phased approach
- [ ] Risk assessment with mitigation strategies
- [ ] @ references to source role analyses throughout
- [ ] Ambiguities resolved through targeted clarification
- [ ] Intelligent role update decisions (correct roles updated)
- [ ] Terminology consistency enforced
- [ ] Contradictions removed from updated documents
### Document Quality
- [ ] Clarifications section properly formatted
- [ ] Updated sections reflect clarification answers
- [ ] No placeholders remain (TODO, TBD, ???)
- [ ] Markdown structure valid in all updated files
- [ ] Cross-references maintained
## 🚀 **Recommended Next Steps**
After synthesis completion, proceed to action planning:
After clarification completion, proceed to planning:
### Standard Workflow (Recommended)
```bash
/workflow:concept-clarify --session WFS-{session-id} # Optional: Clarify ambiguities
/workflow:plan --session WFS-{session-id} # Generate IMPL_PLAN.md and tasks
/workflow:plan --session WFS-{session-id} # Generate IMPL_PLAN.md and tasks from refined role analyses
/workflow:action-plan-verify --session WFS-{session-id} # Optional: Verify plan quality
/workflow:execute --session WFS-{session-id} # Start implementation
/workflow:execute --session WFS-{session-id} # Start implementation
```
### TDD Workflow
```bash
/workflow:concept-clarify --session WFS-{session-id} # Optional: Clarify ambiguities
/workflow:tdd-plan --session WFS-{session-id} "Feature description"
/workflow:action-plan-verify --session WFS-{session-id} # Optional: Verify plan quality
/workflow:execute --session WFS-{session-id}
```

28
.claude/commands/workflow/brainstorm/system-architect.md
View File

@@ -1,6 +1,6 @@
---
name: system-architect
description: Generate or update system-architect/analysis.md addressing topic-framework discussion points
description: Generate or update system-architect/analysis.md addressing guidance-specification discussion points
argument-hint: "optional topic - uses existing framework if available"
allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
---
@@ -8,10 +8,10 @@ allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
## 🏗️ **System Architect Analysis Generator**
### Purpose
**Specialized command for generating system-architect/analysis.md** that addresses topic-framework.md discussion points from system architecture perspective. Creates or updates role-specific analysis with framework references.
**Specialized command for generating system-architect/analysis.md** that addresses guidance-specification.md discussion points from system architecture perspective. Creates or updates role-specific analysis with framework references.
### Core Function
- **Framework-based Analysis**: Address each discussion point in topic-framework.md
- **Framework-based Analysis**: Address each discussion point in guidance-specification.md
- **Architecture Focus**: Technical architecture, scalability, and system design perspective
- **Update Mechanism**: Create new or update existing analysis.md
- **Agent Delegation**: Use conceptual-planning-agent for analysis generation
@@ -51,7 +51,7 @@ IF active_session EXISTS:
session_id = get_active_session()
brainstorm_dir = .workflow/WFS-{session}/.brainstorming/
CHECK: brainstorm_dir/topic-framework.md
CHECK: brainstorm_dir/guidance-specification.md
IF EXISTS:
framework_mode = true
load_framework = true
@@ -78,20 +78,20 @@ ELSE:
```
### Phase 3: Agent Task Generation
**Framework-Based Analysis** (when topic-framework.md exists):
**Framework-Based Analysis** (when guidance-specification.md exists):
```bash
Task(subagent_type="conceptual-planning-agent",
prompt="Generate system architect analysis addressing topic framework
## Framework Integration Required
**MANDATORY**: Load and address topic-framework.md discussion points
**Framework Reference**: @{session.brainstorm_dir}/topic-framework.md
**MANDATORY**: Load and address guidance-specification.md discussion points
**Framework Reference**: @{session.brainstorm_dir}/guidance-specification.md
**Output Location**: {session.brainstorm_dir}/system-architect/analysis.md
## Analysis Requirements
1. **Load Topic Framework**: Read topic-framework.md completely
1. **Load Topic Framework**: Read guidance-specification.md completely
2. **Address Each Discussion Point**: Respond to all 5 framework sections from system architecture perspective
3. **Include Framework Reference**: Start analysis.md with @../topic-framework.md
3. **Include Framework Reference**: Start analysis.md with @../guidance-specification.md
4. **Technical Focus**: Emphasize scalability, architecture patterns, technology decisions
5. **Structured Response**: Use framework structure for analysis organization
@@ -106,7 +106,7 @@ Task(subagent_type="conceptual-planning-agent",
```markdown
# System Architect Analysis: [Topic]
**Framework Reference**: @../topic-framework.md
**Framework Reference**: @../guidance-specification.md
**Role Focus**: System Architecture and Technical Design
## Core Requirements Analysis
@@ -140,14 +140,14 @@ IF update_mode = "incremental":
## Current Analysis Context
**Existing Analysis**: @{session.brainstorm_dir}/system-architect/analysis.md
**Framework Reference**: @{session.brainstorm_dir}/topic-framework.md
**Framework Reference**: @{session.brainstorm_dir}/guidance-specification.md
## Update Requirements
1. **Preserve Structure**: Maintain existing analysis structure
2. **Add New Insights**: Integrate new technical insights and recommendations
3. **Framework Alignment**: Ensure continued alignment with topic framework
4. **Technical Updates**: Add new architecture patterns, technology considerations
5. **Maintain References**: Keep @../topic-framework.md reference
5. **Maintain References**: Keep @../guidance-specification.md reference
## Update Instructions
- Read existing analysis completely
@@ -163,14 +163,14 @@ IF update_mode = "incremental":
### Output Files
```
.workflow/WFS-[topic]/.brainstorming/
├── topic-framework.md # Input: Framework (if exists)
├── guidance-specification.md # Input: Framework (if exists)
└── system-architect/
└── analysis.md # ★ OUTPUT: Framework-based analysis
```
### Analysis Structure
**Required Elements**:
- **Framework Reference**: @../topic-framework.md (if framework exists)
- **Framework Reference**: @../guidance-specification.md (if framework exists)
- **Role Focus**: System Architecture and Technical Design perspective
- **5 Framework Sections**: Address each framework discussion point
- **Technical Recommendations**: Architecture-specific insights and solutions

28
.claude/commands/workflow/brainstorm/ui-designer.md
View File

@@ -1,6 +1,6 @@
---
name: ui-designer
description: Generate or update ui-designer/analysis.md addressing topic-framework discussion points
description: Generate or update ui-designer/analysis.md addressing guidance-specification discussion points
argument-hint: "optional topic - uses existing framework if available"
allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
---
@@ -8,10 +8,10 @@ allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
## 🎨 **UI Designer Analysis Generator**
### Purpose
**Specialized command for generating ui-designer/analysis.md** that addresses topic-framework.md discussion points from UI/UX design perspective. Creates or updates role-specific analysis with framework references.
**Specialized command for generating ui-designer/analysis.md** that addresses guidance-specification.md discussion points from UI/UX design perspective. Creates or updates role-specific analysis with framework references.
### Core Function
- **Framework-based Analysis**: Address each discussion point in topic-framework.md
- **Framework-based Analysis**: Address each discussion point in guidance-specification.md
- **UI/UX Focus**: User experience, interface design, and accessibility perspective
- **Update Mechanism**: Create new or update existing analysis.md
- **Agent Delegation**: Use conceptual-planning-agent for analysis generation
@@ -53,7 +53,7 @@ IF active_session EXISTS:
session_id = get_active_session()
brainstorm_dir = .workflow/WFS-{session}/.brainstorming/
CHECK: brainstorm_dir/topic-framework.md
CHECK: brainstorm_dir/guidance-specification.md
IF EXISTS:
framework_mode = true
load_framework = true
@@ -94,7 +94,7 @@ ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"}
## Flow Control Steps
1. **load_topic_framework**
- Action: Load structured topic discussion framework
- Command: Read(.workflow/WFS-{session}/.brainstorming/topic-framework.md)
- Command: Read(.workflow/WFS-{session}/.brainstorming/guidance-specification.md)
- Output: topic_framework_content
2. **load_role_template**
@@ -108,17 +108,17 @@ ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"}
- Output: session_context
## Analysis Requirements
**Framework Reference**: Address all discussion points in topic-framework.md from UI/UX perspective
**Framework Reference**: Address all discussion points in guidance-specification.md from UI/UX perspective
**Role Focus**: User experience design, interface optimization, accessibility compliance
**Structured Approach**: Create analysis.md addressing framework discussion points
**Template Integration**: Apply role template guidelines within framework structure
## Expected Deliverables
1. **analysis.md**: Comprehensive UI/UX analysis addressing all framework discussion points
2. **Framework Reference**: Include @../topic-framework.md reference in analysis
2. **Framework Reference**: Include @../guidance-specification.md reference in analysis
## Completion Criteria
- Address each discussion point from topic-framework.md with UI/UX design expertise
- Address each discussion point from guidance-specification.md with UI/UX design expertise
- Provide actionable design recommendations and interface solutions
- Include accessibility considerations and WCAG compliance planning
- Reference framework document using @ notation for integration
@@ -137,7 +137,7 @@ TodoWrite({
activeForm: "Detecting session and framework"
},
{
content: "Load topic-framework.md and session metadata for context",
content: "Load guidance-specification.md and session metadata for context",
status: "pending",
activeForm: "Loading framework and session context"
},
@@ -165,7 +165,7 @@ TodoWrite({
### Framework-Based Analysis
```
.workflow/WFS-{session}/.brainstorming/ui-designer/
└── analysis.md # Structured analysis addressing topic-framework.md discussion points
└── analysis.md # Structured analysis addressing guidance-specification.md discussion points
```
### Analysis Document Structure
@@ -173,11 +173,11 @@ TodoWrite({
# UI Designer Analysis: [Topic from Framework]
## Framework Reference
**Topic Framework**: @../topic-framework.md
**Topic Framework**: @../guidance-specification.md
**Role Focus**: UI/UX Design perspective
## Discussion Points Analysis
[Address each point from topic-framework.md with UI/UX expertise]
[Address each point from guidance-specification.md with UI/UX expertise]
### Core Requirements (from framework)
[UI/UX perspective on requirements]
@@ -210,12 +210,12 @@ TodoWrite({
"status": "completed",
"framework_addressed": true,
"output_location": ".workflow/WFS-{session}/.brainstorming/ui-designer/analysis.md",
"framework_reference": "@../topic-framework.md"
"framework_reference": "@../guidance-specification.md"
}
}
```
### Integration Points
- **Framework Reference**: @../topic-framework.md for structured discussion points
- **Framework Reference**: @../guidance-specification.md for structured discussion points
- **Cross-Role Synthesis**: UI/UX insights available for synthesis-report.md integration
- **Agent Autonomy**: Independent execution with framework guidance

28
.claude/commands/workflow/brainstorm/ux-expert.md
View File

@@ -1,6 +1,6 @@
---
name: ux-expert
description: Generate or update ux-expert/analysis.md addressing topic-framework discussion points
description: Generate or update ux-expert/analysis.md addressing guidance-specification discussion points
argument-hint: "optional topic - uses existing framework if available"
allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
---
@@ -8,10 +8,10 @@ allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
## 🎯 **UX Expert Analysis Generator**
### Purpose
**Specialized command for generating ux-expert/analysis.md** that addresses topic-framework.md discussion points from user experience and interface design perspective. Creates or updates role-specific analysis with framework references.
**Specialized command for generating ux-expert/analysis.md** that addresses guidance-specification.md discussion points from user experience and interface design perspective. Creates or updates role-specific analysis with framework references.
### Core Function
- **Framework-based Analysis**: Address each discussion point in topic-framework.md
- **Framework-based Analysis**: Address each discussion point in guidance-specification.md
- **UX Design Focus**: User interface, interaction patterns, and usability optimization
- **Update Mechanism**: Create new or update existing analysis.md
- **Agent Delegation**: Use conceptual-planning-agent for analysis generation
@@ -53,7 +53,7 @@ IF active_session EXISTS:
session_id = get_active_session()
brainstorm_dir = .workflow/WFS-{session}/.brainstorming/
CHECK: brainstorm_dir/topic-framework.md
CHECK: brainstorm_dir/guidance-specification.md
IF EXISTS:
framework_mode = true
load_framework = true
@@ -94,7 +94,7 @@ ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"}
## Flow Control Steps
1. **load_topic_framework**
- Action: Load structured topic discussion framework
- Command: Read(.workflow/WFS-{session}/.brainstorming/topic-framework.md)
- Command: Read(.workflow/WFS-{session}/.brainstorming/guidance-specification.md)
- Output: topic_framework_content
2. **load_role_template**
@@ -108,17 +108,17 @@ ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"}
- Output: session_context
## Analysis Requirements
**Framework Reference**: Address all discussion points in topic-framework.md from user experience and interface design perspective
**Framework Reference**: Address all discussion points in guidance-specification.md from user experience and interface design perspective
**Role Focus**: UI design, interaction patterns, usability optimization, design systems
**Structured Approach**: Create analysis.md addressing framework discussion points
**Template Integration**: Apply role template guidelines within framework structure
## Expected Deliverables
1. **analysis.md**: Comprehensive UX design analysis addressing all framework discussion points
2. **Framework Reference**: Include @../topic-framework.md reference in analysis
2. **Framework Reference**: Include @../guidance-specification.md reference in analysis
## Completion Criteria
- Address each discussion point from topic-framework.md with UX design expertise
- Address each discussion point from guidance-specification.md with UX design expertise
- Provide actionable interface design and usability optimization strategies
- Include accessibility considerations and interaction pattern recommendations
- Reference framework document using @ notation for integration
@@ -137,7 +137,7 @@ TodoWrite({
activeForm: "Detecting session and framework"
},
{
content: "Load topic-framework.md and session metadata for context",
content: "Load guidance-specification.md and session metadata for context",
status: "pending",
activeForm: "Loading framework and session context"
},
@@ -165,7 +165,7 @@ TodoWrite({
### Framework-Based Analysis
```
.workflow/WFS-{session}/.brainstorming/ux-expert/
└── analysis.md # Structured analysis addressing topic-framework.md discussion points
└── analysis.md # Structured analysis addressing guidance-specification.md discussion points
```
### Analysis Document Structure
@@ -173,11 +173,11 @@ TodoWrite({
# UX Expert Analysis: [Topic from Framework]
## Framework Reference
**Topic Framework**: @../topic-framework.md
**Topic Framework**: @../guidance-specification.md
**Role Focus**: User Experience & Interface Design perspective
## Discussion Points Analysis
[Address each point from topic-framework.md with UX design expertise]
[Address each point from guidance-specification.md with UX design expertise]
### Core Requirements (from framework)
[User interface and interaction design requirements perspective]
@@ -210,12 +210,12 @@ TodoWrite({
"status": "completed",
"framework_addressed": true,
"output_location": ".workflow/WFS-{session}/.brainstorming/ux-expert/analysis.md",
"framework_reference": "@../topic-framework.md"
"framework_reference": "@../guidance-specification.md"
}
}
```
### Integration Points
- **Framework Reference**: @../topic-framework.md for structured discussion points
- **Framework Reference**: @../guidance-specification.md for structured discussion points
- **Cross-Role Synthesis**: UX design insights available for synthesis-report.md integration
- **Agent Autonomy**: Independent execution with framework guidance