claude-code-workflow 6.2.3 → 6.2.5

package/.claude/commands/workflow/brainstorm/ux-expert.md

@@ -1,221 +0,0 @@
----
-name: ux-expert
-description: Generate or update ux-expert/analysis.md addressing guidance-specification discussion points for UX perspective
-argument-hint: "optional topic - uses existing framework if available"
-allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
----
-
-## 🎯 **UX Expert Analysis Generator**
-
-### Purpose
-**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 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
-
-### Analysis Scope
-- **User Research**: User personas, behavioral analysis, and needs assessment
-- **Information Architecture**: Content structure, navigation hierarchy, and mental models
-- **User Journey Mapping**: User flows, task analysis, and interaction models
-- **Usability Strategy**: Accessibility planning, cognitive load reduction, and user testing frameworks
-- **Wireframing**: Low-fidelity layouts and structural prototypes (not visual design)
-
-### Role Boundaries & Responsibilities
-
-#### **What This Role OWNS (Abstract User Experience & Research)**
-- **User Research & Personas**: Understanding target users, their goals, pain points, and behaviors
-- **Information Architecture**: Organizing content and defining navigation structures at a conceptual level
-- **User Journey Mapping**: Defining user flows, task sequences, and interaction models
-- **Wireframes & Low-Fidelity Prototypes**: Structural layouts showing information hierarchy (boxes and arrows, not colors/fonts)
-- **Usability Testing Strategy**: Planning user testing, A/B tests, and validation methods
-- **Accessibility Planning**: WCAG compliance strategy and inclusive design principles
-
-#### **What This Role DOES NOT Own (Defers to Other Roles)**
-- **Visual Design**: Colors, typography, spacing, visual style → Defers to **UI Designer**
-- **High-Fidelity Mockups**: Polished, pixel-perfect designs → Defers to **UI Designer**
-- **Component Implementation**: Design system components, CSS, animations → Defers to **UI Designer**
-
-#### **Handoff Points**
-- **TO UI Designer**: Provides wireframes, user flows, and information architecture that UI Designer will transform into high-fidelity visual designs
-- **FROM User Research**: May receive external research data to inform UX decisions
-- **TO Product Owner**: Provides user insights and validation results to inform feature prioritization
-
-## ⚙️ **Execution Protocol**
-
-### Phase 1: Session & Framework Detection
-```bash
-# Check active session and framework
-CHECK: find .workflow/active/ -name "WFS-*" -type d
-IF active_session EXISTS:
-    session_id = get_active_session()
-    brainstorm_dir = .workflow/active/WFS-{session}/.brainstorming/
-
-    CHECK: brainstorm_dir/guidance-specification.md
-    IF EXISTS:
-        framework_mode = true
-        load_framework = true
-    ELSE:
-        IF topic_provided:
-            framework_mode = false  # Create analysis without framework
-        ELSE:
-            ERROR: "No framework found and no topic provided"
-```
-
-### Phase 2: Analysis Mode Detection
-```bash
-# Determine execution mode
-IF framework_mode == true:
-    mode = "framework_based_analysis"
-    topic_ref = load_framework_topic()
-    discussion_points = extract_framework_points()
-ELSE:
-    mode = "standalone_analysis"
-    topic_ref = provided_topic
-    discussion_points = generate_basic_structure()
-```
-
-### Phase 3: Agent Execution with Flow Control
-**Framework-Based Analysis Generation**
-
-```bash
-Task(conceptual-planning-agent): "
-[FLOW_CONTROL]
-
-Execute ux-expert analysis for existing topic framework
-
-## Context Loading
-ASSIGNED_ROLE: ux-expert
-OUTPUT_LOCATION: .workflow/active/WFS-{session}/.brainstorming/ux-expert/
-ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"}
-
-## Flow Control Steps
-1. **load_topic_framework**
-   - Action: Load structured topic discussion framework
-   - Command: Read(.workflow/active/WFS-{session}/.brainstorming/guidance-specification.md)
-   - Output: topic_framework_content
-
-2. **load_role_template**
-   - Action: Load ux-expert planning template
-   - Command: bash($(cat ~/.claude/workflows/cli-templates/planning-roles/ux-expert.md))
-   - Output: role_template_guidelines
-
-3. **load_session_metadata**
-   - Action: Load session metadata and existing context
-   - Command: Read(.workflow/active/WFS-{session}/workflow-session.json)
-   - Output: session_context
-
-## Analysis Requirements
-**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 @../guidance-specification.md reference in analysis
-
-## Completion Criteria
-- 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
-"
-```
-
-## 📋 **TodoWrite Integration**
-
-### Workflow Progress Tracking
-```javascript
-TodoWrite({
-  todos: [
-    {
-      content: "Detect active session and locate topic framework",
-      status: "in_progress",
-      activeForm: "Detecting session and framework"
-    },
-    {
-      content: "Load guidance-specification.md and session metadata for context",
-      status: "pending",
-      activeForm: "Loading framework and session context"
-    },
-    {
-      content: "Execute ux-expert analysis using conceptual-planning-agent with FLOW_CONTROL",
-      status: "pending",
-      activeForm: "Executing ux-expert framework analysis"
-    },
-    {
-      content: "Generate analysis.md addressing all framework discussion points",
-      status: "pending",
-      activeForm: "Generating structured ux-expert analysis"
-    },
-    {
-      content: "Update workflow-session.json with ux-expert completion status",
-      status: "pending",
-      activeForm: "Updating session metadata"
-    }
-  ]
-});
-```
-
-## 📊 **Output Structure**
-
-### Framework-Based Analysis
-```
-.workflow/active/WFS-{session}/.brainstorming/ux-expert/
-└── analysis.md    # Structured analysis addressing guidance-specification.md discussion points
-```
-
-### Analysis Document Structure
-```markdown
-# UX Expert Analysis: [Topic from Framework]
-
-## Framework Reference
-**Topic Framework**: @../guidance-specification.md
-**Role Focus**: User Experience & Interface Design perspective
-
-## Discussion Points Analysis
-[Address each point from guidance-specification.md with UX design expertise]
-
-### Core Requirements (from framework)
-[User interface and interaction design requirements perspective]
-
-### Technical Considerations (from framework)
-[Design system implementation and technical feasibility considerations]
-
-### User Experience Factors (from framework)
-[Usability optimization, accessibility, and user-centered design analysis]
-
-### Implementation Challenges (from framework)
-[Design implementation challenges and progressive enhancement strategies]
-
-### Success Metrics (from framework)
-[UX metrics including usability testing, user satisfaction, and design KPIs]
-
-## UX Expert Specific Recommendations
-[Role-specific interface design patterns and usability optimization strategies]
-
----
-*Generated by ux-expert analysis addressing structured framework*
-```
-
-## 🔄 **Session Integration**
-
-### Completion Status Update
-```json
-{
-  "ux_expert": {
-    "status": "completed",
-    "framework_addressed": true,
-    "output_location": ".workflow/active/WFS-{session}/.brainstorming/ux-expert/analysis.md",
-    "framework_reference": "@../guidance-specification.md"
-  }
-}
-```
-
-### Integration 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

package/.claude/commands/workflow/debug.md

@@ -1,321 +0,0 @@
----
-name: debug
-description: Interactive hypothesis-driven debugging with NDJSON logging, iterative until resolved
-argument-hint: "\"bug description or error message\""
-allowed-tools: TodoWrite(*), Task(*), AskUserQuestion(*), Read(*), Grep(*), Glob(*), Bash(*), Edit(*), Write(*)
----
-
-# Workflow Debug Command (/workflow:debug)
-
-## Overview
-
-Evidence-based interactive debugging command. Systematically identifies root causes through hypothesis-driven logging and iterative verification.
-
-**Core workflow**: Explore → Add Logging → Reproduce → Analyze Log → Fix → Verify
-
-## Usage
-
-```bash
-/workflow:debug <BUG_DESCRIPTION>
-
-# Arguments
-<bug-description>          Bug description, error message, or stack trace (required)
-```
-
-## Execution Process
-
-```
-Session Detection:
-   ├─ Check if debug session exists for this bug
-   ├─ EXISTS + debug.log has content → Analyze mode
-   └─ NOT_FOUND or empty log → Explore mode
-
-Explore Mode:
-   ├─ Locate error source in codebase
-   ├─ Generate testable hypotheses (dynamic count)
-   ├─ Add NDJSON logging instrumentation
-   └─ Output: Hypothesis list + await user reproduction
-
-Analyze Mode:
-   ├─ Parse debug.log, validate each hypothesis
-   └─ Decision:
-       ├─ Confirmed → Fix root cause
-       ├─ Inconclusive → Add more logging, iterate
-       └─ All rejected → Generate new hypotheses
-
-Fix & Cleanup:
-   ├─ Apply fix based on confirmed hypothesis
-   ├─ User verifies
-   ├─ Remove debug instrumentation
-   └─ If not fixed → Return to Analyze mode
-```
-
-## Implementation
-
-### Session Setup & Mode Detection
-
-```javascript
-const getUtc8ISOString = () => new Date(Date.now() + 8 * 60 * 60 * 1000).toISOString()
-
-const bugSlug = bug_description.toLowerCase().replace(/[^a-z0-9]+/g, '-').substring(0, 30)
-const dateStr = getUtc8ISOString().substring(0, 10)
-
-const sessionId = `DBG-${bugSlug}-${dateStr}`
-const sessionFolder = `.workflow/.debug/${sessionId}`
-const debugLogPath = `${sessionFolder}/debug.log`
-
-// Auto-detect mode
-const sessionExists = fs.existsSync(sessionFolder)
-const logHasContent = sessionExists && fs.existsSync(debugLogPath) && fs.statSync(debugLogPath).size > 0
-
-const mode = logHasContent ? 'analyze' : 'explore'
-
-if (!sessionExists) {
-  bash(`mkdir -p ${sessionFolder}`)
-}
-```
-
----
-
-### Explore Mode
-
-**Step 1.1: Locate Error Source**
-
-```javascript
-// Extract keywords from bug description
-const keywords = extractErrorKeywords(bug_description)
-// e.g., ['Stack Length', '未找到', 'registered 0']
-
-// Search codebase for error locations
-for (const keyword of keywords) {
-  Grep({ pattern: keyword, path: ".", output_mode: "content", "-C": 3 })
-}
-
-// Identify affected files and functions
-const affectedLocations = [...]  // from search results
-```
-
-**Step 1.2: Generate Hypotheses (Dynamic)**
-
-```javascript
-// Hypothesis categories based on error pattern
-const HYPOTHESIS_PATTERNS = {
-  "not found|missing|undefined|未找到": "data_mismatch",
-  "0|empty|zero|registered 0": "logic_error",
-  "timeout|connection|sync": "integration_issue",
-  "type|format|parse": "type_mismatch"
-}
-
-// Generate hypotheses based on actual issue (NOT fixed count)
-function generateHypotheses(bugDescription, affectedLocations) {
-  const hypotheses = []
-
-  // Analyze bug and create targeted hypotheses
-  // Each hypothesis has:
-  // - id: H1, H2, ... (dynamic count)
-  // - description: What might be wrong
-  // - testable_condition: What to log
-  // - logging_point: Where to add instrumentation
-
-  return hypotheses  // Could be 1, 3, 5, or more
-}
-
-const hypotheses = generateHypotheses(bug_description, affectedLocations)
-```
-
-**Step 1.3: Add NDJSON Instrumentation**
-
-For each hypothesis, add logging at the relevant location:
-
-**Python template**:
-```python
-# region debug [H{n}]
-try:
-    import json, time
-    _dbg = {
-        "sid": "{sessionId}",
-        "hid": "H{n}",
-        "loc": "{file}:{line}",
-        "msg": "{testable_condition}",
-        "data": {
-            # Capture relevant values here
-        },
-        "ts": int(time.time() * 1000)
-    }
-    with open(r"{debugLogPath}", "a", encoding="utf-8") as _f:
-        _f.write(json.dumps(_dbg, ensure_ascii=False) + "\n")
-except: pass
-# endregion
-```
-
-**JavaScript/TypeScript template**:
-```javascript
-// region debug [H{n}]
-try {
-  require('fs').appendFileSync("{debugLogPath}", JSON.stringify({
-    sid: "{sessionId}",
-    hid: "H{n}",
-    loc: "{file}:{line}",
-    msg: "{testable_condition}",
-    data: { /* Capture relevant values */ },
-    ts: Date.now()
-  }) + "\n");
-} catch(_) {}
-// endregion
-```
-
-**Output to user**:
-```
-## Hypotheses Generated
-
-Based on error "{bug_description}", generated {n} hypotheses:
-
-{hypotheses.map(h => `
-### ${h.id}: ${h.description}
-- Logging at: ${h.logging_point}
-- Testing: ${h.testable_condition}
-`).join('')}
-
-**Debug log**: ${debugLogPath}
-
-**Next**: Run reproduction steps, then come back for analysis.
-```
-
----
-
-### Analyze Mode
-
-```javascript
-// Parse NDJSON log
-const entries = Read(debugLogPath).split('\n')
-  .filter(l => l.trim())
-  .map(l => JSON.parse(l))
-
-// Group by hypothesis
-const byHypothesis = groupBy(entries, 'hid')
-
-// Validate each hypothesis
-for (const [hid, logs] of Object.entries(byHypothesis)) {
-  const hypothesis = hypotheses.find(h => h.id === hid)
-  const latestLog = logs[logs.length - 1]
-
-  // Check if evidence confirms or rejects hypothesis
-  const verdict = evaluateEvidence(hypothesis, latestLog.data)
-  // Returns: 'confirmed' | 'rejected' | 'inconclusive'
-}
-```
-
-**Output**:
-```
-## Evidence Analysis
-
-Analyzed ${entries.length} log entries.
-
-${results.map(r => `
-### ${r.id}: ${r.description}
-- **Status**: ${r.verdict}
-- **Evidence**: ${JSON.stringify(r.evidence)}
-- **Reason**: ${r.reason}
-`).join('')}
-
-${confirmedHypothesis ? `
-## Root Cause Identified
-
-**${confirmedHypothesis.id}**: ${confirmedHypothesis.description}
-
-Ready to fix.
-` : `
-## Need More Evidence
-
-Add more logging or refine hypotheses.
-`}
-```
-
----
-
-### Fix & Cleanup
-
-```javascript
-// Apply fix based on confirmed hypothesis
-// ... Edit affected files
-
-// After user verifies fix works:
-
-// Remove debug instrumentation (search for region markers)
-const instrumentedFiles = Grep({
-  pattern: "# region debug|// region debug",
-  output_mode: "files_with_matches"
-})
-
-for (const file of instrumentedFiles) {
-  // Remove content between region markers
-  removeDebugRegions(file)
-}
-
-console.log(`
-## Debug Complete
-
-- Root cause: ${confirmedHypothesis.description}
-- Fix applied to: ${modifiedFiles.join(', ')}
-- Debug instrumentation removed
-`)
-```
-
----
-
-## Debug Log Format (NDJSON)
-
-Each line is a JSON object:
-
-```json
-{"sid":"DBG-xxx-2025-12-18","hid":"H1","loc":"file.py:func:42","msg":"Check dict keys","data":{"keys":["a","b"],"target":"c","found":false},"ts":1734567890123}
-```
-
-| Field | Description |
-|-------|-------------|
-| `sid` | Session ID |
-| `hid` | Hypothesis ID (H1, H2, ...) |
-| `loc` | Code location |
-| `msg` | What's being tested |
-| `data` | Captured values |
-| `ts` | Timestamp (ms) |
-
-## Session Folder
-
-```
-.workflow/.debug/DBG-{slug}-{date}/
-├── debug.log          # NDJSON log (main artifact)
-└── resolution.md      # Summary after fix (optional)
-```
-
-## Iteration Flow
-
-```
-First Call (/workflow:debug "error"):
-   ├─ No session exists → Explore mode
-   ├─ Extract error keywords, search codebase
-   ├─ Generate hypotheses, add logging
-   └─ Await user reproduction
-
-After Reproduction (/workflow:debug "error"):
-   ├─ Session exists + debug.log has content → Analyze mode
-   ├─ Parse log, evaluate hypotheses
-   └─ Decision:
-       ├─ Confirmed → Fix → User verify
-       │   ├─ Fixed → Cleanup → Done
-       │   └─ Not fixed → Add logging → Iterate
-       ├─ Inconclusive → Add logging → Iterate
-       └─ All rejected → New hypotheses → Iterate
-
-Output:
-   └─ .workflow/.debug/DBG-{slug}-{date}/debug.log
-```
-
-## Error Handling
-
-| Situation | Action |
-|-----------|--------|
-| Empty debug.log | Verify reproduction triggered the code path |
-| All hypotheses rejected | Generate new hypotheses with broader scope |
-| Fix doesn't work | Iterate with more granular logging |
-| >5 iterations | Escalate to `/workflow:lite-fix` with evidence |