Team Ux Improve

Team UX Improve

Systematic UX improvement pipeline: scan -> diagnose -> design -> implement -> test. Built on team-worker agent architecture — all worker roles share a single agent definition with role-specific Phase 2-4 loaded from roles/<role>/role.md.

Architecture

Skill(skill="team-ux-improve", args="<project-path> [--framework react|vue]")
                    |
         SKILL.md (this file) = Router
                    |
     +--------------+--------------+
     |                             |
  no --role flag              --role <name>
     |                             |
  Coordinator                  Worker
  roles/coordinator/role.md    roles/<name>/role.md
     |
     +-- analyze → dispatch → spawn workers → STOP
                                    |
                    +-------+-------+-------+-------+
                    v       v       v       v       v
           [team-worker agents, each loads roles/<role>/role.md]
          scanner  diagnoser  designer  implementer  tester

Role Registry

Utility Member Registry

Coordinator-only: Utility members can only be spawned by Coordinator. Workers CANNOT call Agent() to spawn utility members.

Role Router

Parse $ARGUMENTS:

• Has --role <name> → Read roles/<name>/role.md, execute Phase 2-4
• No --role → @roles/coordinator/role.md, execute entry router

Shared Constants

• Session prefix: ux-improve
• Session path: .workflow/.team/ux-improve-<timestamp>/
• CLI tools: ccw cli --mode analysis (read-only), ccw cli --mode write (modifications)
• Message bus: mcp__ccw-tools__team_msg(session_id=<session-id>, ...)
• Max test iterations: 5

Worker Spawn Template

Coordinator spawns workers using this template:

Agent({
  subagent_type: "team-worker",
  description: "Spawn <role> worker for <task-id>",
  team_name: "ux-improve",
  name: "<role>",
  run_in_background: true,
  prompt: `## Role Assignment
role: <role>
role_spec: <skill_root>/roles/<role>/role.md
session: <session-folder>
session_id: <session-id>
team_name: ux-improve
requirement: <task-description>
inner_loop: <true|false>

## Progress Milestones
session_id: <session-id>
Report progress via team_msg at natural phase boundaries (context loaded -> core work done -> verification).
Report blockers immediately via team_msg type="blocker".
Report completion via team_msg type="task_complete" after final SendMessage.

Read role_spec file (@<skill_root>/roles/<role>/role.md) to load Phase 2-4 domain instructions.
Execute built-in Phase 1 (task discovery) -> role Phase 2-4 -> built-in Phase 5 (report).`
})

User Commands

Specs Reference

• specs/pipelines.md — Pipeline definitions and task registry
• specs/design-standards.md — Impeccable visual design standards
• specs/anti-patterns.md — AI slop detection catalog (20 items)
• specs/heuristics.md — Nielsen's 10 usability heuristics evaluation framework

Session Directory

.workflow/.team/ux-improve-<timestamp>/
├── .msg/
│   ├── messages.jsonl      # Team message bus
│   └── meta.json           # Pipeline config + role state snapshot
├── artifacts/              # Role deliverables
│   ├── scan-report.md      # Scanner output
│   ├── diagnosis.md        # Diagnoser output
│   ├── design-guide.md     # Designer output
│   ├── fixes/              # Implementer output
│   └── test-report.md      # Tester output
├── explorations/           # Explorer cache
│   └── cache-index.json
└── wisdom/                 # Session knowledge base
    ├── contributions/      # Worker contributions (write-only for workers)
    ├── principles/
    ├── patterns/
    └── anti-patterns/

Error Handling

Analyze Task

Parse user task -> detect UX improvement scope -> assess complexity -> determine pipeline configuration.

CONSTRAINT: Text-level analysis only. NO source code reading, NO codebase exploration.

Signal Detection

Framework Detection

Complexity Scoring

Results: 1-2 Low (targeted fix), 3-4 Medium (standard pipeline), 5+ High (full pipeline)

Scope Determination

Output

Write scope context to coordinator memory:

{
  "pipeline_mode": "standard",
  "project_path": "<detected-or-provided-path>",
  "framework": "<react|vue|angular|auto>",
  "scope": "<detected-scope>",
  "issue_signals": ["interaction", "feedback", "state"],
  "complexity": { "score": 0, "level": "Low|Medium|High" }
}

Dispatch Command

Purpose

Create task chains based on execution mode. Generate structured task descriptions with PURPOSE/TASK/CONTEXT/EXPECTED/CONSTRAINTS format.

---

Phase 2: Context Loading

1. Load session ID from coordinator context 2. Load project path and framework from meta.json 3. Determine pipeline mode (standard)

---

Phase 3: Task Chain Creation

Task Description Template

Every task description uses structured format for clarity:

TaskCreate({
  subject: "<TASK-ID>",
  description: "PURPOSE: <what this task achieves> | Success: <measurable completion criteria>
TASK:
  - <step 1: specific action>
  - <step 2: specific action>
  - <step 3: specific action>
CONTEXT:
  - Session: <session-folder>
  - Scope: <scope>
  - Upstream artifacts: <artifact-1.md>, <artifact-2.md>
  - Key files: <file1>, <file2> (if applicable)
  - State: via team_msg(operation="get_state", role=<upstream-role>)
EXPECTED: <deliverable path> + <quality criteria>
CONSTRAINTS: <scope limits, focus areas>
---
InnerLoop: <true|false>
<additional-metadata-fields>"
})
TaskUpdate({ taskId: "<TASK-ID>", addBlockedBy: [<dependency-list>], owner: "<role>" })

Standard Pipeline Tasks

SCAN-001: UI Component Scanning

TaskCreate({
  subject: "SCAN-001",
  description: "PURPOSE: Scan UI components to identify interaction issues (unresponsive buttons, missing feedback, state not refreshing) | Success: Complete issue report with file:line references and severity classification
TASK:
  - Detect framework (React/Vue) from project structure
  - Scan UI components for interaction patterns using ACE search and file analysis
  - Identify missing feedback mechanisms (loading states, error handling, success confirmation)
  - Detect unresponsive actions (event binding issues, async handling problems)
  - Check state update patterns (mutation vs reactive updates)
CONTEXT:
  - Session: <session-folder>
  - Scope: Project path: <project-path>, Framework: <framework>
  - File patterns: **/*.tsx, **/*.vue, **/*.jsx
  - Focus: UI components with user interactions
EXPECTED: artifacts/scan-report.md with structured issue list (severity: High/Medium/Low, file:line, description, category)
CONSTRAINTS: Focus on interaction issues only, exclude styling/layout problems
---
InnerLoop: false"
})
TaskUpdate({ taskId: "SCAN-001", owner: "scanner" })

DIAG-001: Root Cause Diagnosis

TaskCreate({
  subject: "DIAG-001",
  description: "PURPOSE: Diagnose root causes of identified UI issues | Success: Complete diagnosis report with fix recommendations for each issue
TASK:
  - Load scan report from artifacts/scan-report.md
  - Analyze state management patterns (direct mutation vs reactive updates)
  - Trace event binding and propagation
  - Check async handling (promises, callbacks, error catching)
  - Identify framework-specific anti-patterns
  - Use CLI for complex multi-file analysis when needed
CONTEXT:
  - Session: <session-folder>
  - Scope: Issues from scan report
  - Upstream artifacts: artifacts/scan-report.md
  - State: via team_msg(operation="get_state", role="scanner")
EXPECTED: artifacts/diagnosis.md with root cause analysis (issue ID, root cause, pattern type, fix recommendation)
CONSTRAINTS: Focus on actionable root causes, provide specific fix strategies
---
InnerLoop: false"
})
TaskUpdate({ taskId: "DIAG-001", addBlockedBy: ["SCAN-001"], owner: "diagnoser" })

DESIGN-001: Solution Design

TaskCreate({
  subject: "DESIGN-001",
  description: "PURPOSE: Design feedback mechanisms and state management solutions for identified issues | Success: Complete implementation guide with code patterns and examples
TASK:
  - Load diagnosis report from artifacts/diagnosis.md
  - Design feedback mechanisms (loading/error/success states) for each issue
  - Design state management patterns (useState/ref, reactive updates)
  - Design input control improvements (file selectors, validation)
  - Generate framework-specific code patterns (React/Vue)
  - Use CLI for complex multi-component solutions when needed
CONTEXT:
  - Session: <session-folder>
  - Scope: Issues from diagnosis report
  - Upstream artifacts: artifacts/diagnosis.md
  - Framework: <framework>
  - State: via team_msg(operation="get_state", role="diagnoser")
EXPECTED: artifacts/design-guide.md with implementation guide (issue ID, solution design, code patterns, state management examples, UI binding templates)
CONSTRAINTS: Solutions must be framework-appropriate, provide complete working examples
---
InnerLoop: false"
})
TaskUpdate({ taskId: "DESIGN-001", addBlockedBy: ["DIAG-001"], owner: "designer" })

IMPL-001: Code Implementation

TaskCreate({
  subject: "IMPL-001",
  description: "PURPOSE: Generate fix code with proper state management, event handling, and UI feedback bindings | Success: All fixes implemented and validated
TASK:
  - Load design guide from artifacts/design-guide.md
  - Extract implementation tasks from design guide
  - Generate fix code with proper state management (useState/ref)
  - Add event handlers with error catching
  - Implement UI feedback bindings (loading/error/success)
  - Use CLI for complex multi-file changes, direct Edit/Write for simple changes
  - Validate syntax and file existence after each fix
CONTEXT:
  - Session: <session-folder>
  - Scope: Fixes from design guide
  - Upstream artifacts: artifacts/design-guide.md
  - Framework: <framework>
  - State: via team_msg(operation="get_state", role="designer")
  - Context accumulator: Load from prior IMPL tasks (inner loop)
EXPECTED: artifacts/fixes/ directory with all fix files, implementation summary in artifacts/fixes/README.md
CONSTRAINTS: Maintain existing code style, ensure backward compatibility, validate all changes
---
InnerLoop: true"
})
TaskUpdate({ taskId: "IMPL-001", addBlockedBy: ["DESIGN-001"], owner: "implementer" })

TEST-001: Test Validation

TaskCreate({
  subject: "TEST-001",
  description: "PURPOSE: Generate and run tests to verify fixes (loading states, error handling, state updates) | Success: Pass rate >= 95%, all critical fixes validated
TASK:
  - Detect test framework (Jest/Vitest) from project
  - Get changed files from implementer state
  - Load test strategy from design guide
  - Generate test cases for loading states, error handling, state updates
  - Run tests and parse results
  - If pass rate < 95%, use CLI to generate fixes (max 5 iterations)
  - Generate test report with pass/fail counts, coverage, fix iterations
CONTEXT:
  - Session: <session-folder>
  - Scope: Fixes from implementer
  - Upstream artifacts: artifacts/fixes/, artifacts/design-guide.md
  - Framework: <framework>
  - State: via team_msg(operation="get_state", role="implementer")
EXPECTED: artifacts/test-report.md with test results (pass/fail counts, coverage metrics, fix iterations, remaining issues)
CONSTRAINTS: Pass rate threshold: 95%, max fix iterations: 5
---
InnerLoop: false"
})
TaskUpdate({ taskId: "TEST-001", addBlockedBy: ["IMPL-001"], owner: "tester" })

---

Phase 4: Validation

1. Verify all tasks created successfully 2. Check task dependency chain is valid (no cycles) 3. Verify all task owners match Role Registry 4. Confirm task prefixes match role frontmatter 5. Output task count and dependency graph

Monitor Pipeline

Event-driven pipeline coordination. Beat model: coordinator wake -> process -> spawn -> STOP.

Constants

• SPAWN_MODE: background
• ONE_STEP_PER_INVOCATION: true
• FAST_ADVANCE_AWARE: true
• WORKER_AGENT: team-worker
• MAX_TEST_ITERATIONS: 5

Handler Router

handleCallback

Worker completed. Process and advance.

1. Parse message to identify role and task ID:

2. Check if progress update (inner loop) or final completion 3. Progress update -> update session state, STOP 4. Completion -> mark task done:

   TaskUpdate({ taskId: "<task-id>", status: "completed" })

5. Remove from active_workers, record completion in session

6. Check for checkpoints:

• TEST-001 completes -> Validation Gate:

Read test results from .msg/meta.json

7. -> handleSpawnNext

handleCheck

Read-only status report, then STOP.

Worker Progress (from message bus):

Before generating status output, read worker milestones:

const progressMsgs = mcp__ccw-tools__team_msg({
  operation: "list", session_id: sessionId, type: "progress", last: 50
})
const blockerMsgs = mcp__ccw-tools__team_msg({
  operation: "list", session_id: sessionId, type: "blocker", last: 10
})

// Aggregate latest milestone per task
const taskProgress = {}
for (const msg of (progressMsgs.result?.messages || [])) {
  const tid = msg.data?.task_id
  if (tid && (!taskProgress[tid] || msg.ts > taskProgress[tid].ts)) {
    taskProgress[tid] = { phase: msg.data.phase, pct: msg.data.progress_pct, ts: msg.ts }
  }
}

Include in status output:

• Per-worker latest milestone (phase + progress_pct) next to task status
• Active blockers section (if any blockerMsgs found)

Pipeline Status (standard):
  [DONE]  SCAN-001    (scanner)     -> artifacts/scan-report.md
  [DONE]  DIAG-001    (diagnoser)   -> artifacts/diagnosis.md
  [RUN]   DESIGN-001  (designer)    -> designing solutions...
  [WAIT]  IMPL-001    (implementer) -> blocked by DESIGN-001
  [WAIT]  TEST-001    (tester)      -> blocked by IMPL-001

Session: <session-id>
Commands: 'resume' to advance | 'check' to refresh

Output status -- do NOT advance pipeline.

handleResume

1. Audit task list for inconsistencies:

• Tasks stuck in "in_progress" -> reset to "pending"
• Tasks with completed blockers but still "pending" -> include in spawn list

2. -> handleSpawnNext

handleSpawnNext

Find ready tasks, spawn workers, STOP.

1. Collect: completedSubjects, inProgressSubjects, readySubjects (pending + all blockedBy completed) 2. No ready + work in progress -> report waiting, STOP 3. No ready + nothing in progress -> handleComplete 4. Has ready -> for each: a. Check inner loop role with active worker -> skip (worker picks up) b. TaskUpdate -> in_progress c. team_msg log -> task_unblocked d. Spawn team-worker:

Agent({
  subagent_type: "team-worker",
  description: "Spawn <role> worker for <task-id>",
  team_name: "ux-improve",
  name: "<role>",
  run_in_background: true,
  prompt: `## Role Assignment
role: <role>
role_spec: ~  or <project>/.claude/skills/team-ux-improve/roles/<role>/role.md
session: <session-folder>
session_id: <session-id>
team_name: ux-improve
requirement: <task-description>
inner_loop: <true|false>

## Progress Milestones
session_id: <session-id>
Report progress via team_msg at natural phase boundaries (context loaded -> core work done -> verification).
Report blockers immediately via team_msg type="blocker".
Report completion via team_msg type="task_complete" after final SendMessage.

Read role_spec file to load Phase 2-4 domain instructions.
Execute built-in Phase 1 (task discovery) -> role Phase 2-4 -> built-in Phase 5 (report).`
})

Stage-to-role mapping:

Inner loop roles: implementer (inner_loop: true) Single-task roles: scanner, diagnoser, designer, tester (inner_loop: false)

5. Add to active_workers, update session, output summary, STOP

handleComplete

Pipeline done. Generate report and completion action.

1. Verify all tasks (including any fix-verify iterations) have status "completed" 2. If any tasks not completed -> handleSpawnNext 3. If all completed -> transition to coordinator Phase 5

handleAdapt

Capability gap reported mid-pipeline.

1. Parse gap description 2. Check if existing role covers it -> redirect 3. Role count < 5 -> generate dynamic role spec 4. Create new task, spawn worker 5. Role count >= 5 -> merge or pause

Fast-Advance Reconciliation

On every coordinator wake: 1. Read team_msg entries with type="fast_advance" 2. Sync active_workers with spawned successors 3. No duplicate spawns

Coordinator Role

UX Improvement Team coordinator. Orchestrate pipeline: analyze -> dispatch -> spawn -> monitor -> report. Systematically discovers and fixes UI/UX interaction issues.

Identity

• Name: coordinator | Tag: [coordinator]
• Responsibility: Analyze task -> Create team -> Dispatch tasks -> Monitor progress -> Report results

Boundaries

MUST

• All output (SendMessage, team_msg, logs) must carry [coordinator] identifier
• Use team-worker agent type for all worker spawns (NOT general-purpose)
• Parse project_path and framework from arguments
• Dispatch tasks with proper dependency chains and blockedBy
• Monitor worker progress via message bus and route messages
• Handle wisdom initialization and consolidation
• Maintain session state persistence

MUST NOT

• Execute worker domain logic directly (scanning, diagnosing, designing, implementing, testing)
• Spawn workers without creating tasks first
• Skip completion action
• Modify source code directly -- delegate to implementer
• Omit [coordinator] identifier in any output

Command Execution Protocol

When coordinator needs to execute a command (analyze, dispatch, monitor):

1. Read commands/<command>.md 2. Follow the workflow defined in the command 3. Commands are inline execution guides, NOT separate agents 4. Execute synchronously, complete before proceeding

Entry Router

For callback/check/resume/adapt/complete: load @commands/monitor.md, execute matched handler, STOP.

Phase 0: Session Resume Check

1. Scan .workflow/.team/ux-improve-*/.msg/meta.json for active/paused sessions 2. No sessions -> Phase 1 3. Single session -> reconcile (audit TaskList, reset in_progress->pending, rebuild team, kick first ready task) 4. Multiple -> AskUserQuestion for selection

Phase 1: Requirement Clarification

TEXT-LEVEL ONLY. No source code reading.

1. Parse $ARGUMENTS for project path and framework flag:

• <project-path> (required)
• --framework react|vue (optional, auto-detect if omitted)

2. If project path missing -> AskUserQuestion for path 3. Delegate to @commands/analyze.md -> output scope context 4. Store: project_path, framework, pipeline_mode, issue_signals

Phase 2: Create Team + Initialize Session

1. Resolve workspace paths (MUST do first):

• project_root = result of Bash({ command: "pwd" })
• skill_root = <project_root>/.claude/skills/team-ux-improve

2. Generate session ID: ux-improve-<timestamp> 3. Create session folder structure:

   .workflow/.team/ux-improve-<timestamp>/
   ├── .msg/
   ├── artifacts/
   ├── explorations/
   └── wisdom/contributions/

4. Wisdom Initialization: Copy <skill_root>/wisdom/ to <session>/wisdom/ 5. Initialize .msg/meta.json via team_msg state_update with pipeline metadata 6. TeamCreate(team_name="ux-improve") 7. Do NOT spawn workers yet - deferred to Phase 4

Phase 3: Create Task Chain

Delegate to @commands/dispatch.md. Standard pipeline:

SCAN-001 -> DIAG-001 -> DESIGN-001 -> IMPL-001 -> TEST-001

Phase 4: Spawn-and-Stop

Delegate to @commands/monitor.md#handleSpawnNext: 1. Find ready tasks (pending + blockedBy resolved) 2. Spawn team-worker agents (see SKILL.md Spawn Template) 3. Output status summary 4. STOP

Phase 5: Report + Completion Action

1. Read session state -> collect all results 2. List deliverables:

3. Wisdom Consolidation: Check <session>/wisdom/contributions/ for worker contributions

• If contributions exist -> AskUserQuestion to merge to permanent wisdom
• If approved -> copy to <skill_root>/wisdom/

4. Calculate: completed_tasks, total_issues_found, issues_fixed, test_pass_rate 5. Output pipeline summary with [coordinator] prefix 6. Execute completion action:

   AskUserQuestion({
     questions: [{ question: "Pipeline complete. What next?", header: "Completion", options: [
       { label: "Archive & Clean", description: "Archive session and clean up team resources" },
       { label: "Keep Active", description: "Keep session for follow-up work" },
       { label: "Export Results", description: "Export deliverables to specified location" }
     ]}]
   })

Error Handling

UX Designer

Design feedback mechanisms (loading/error/success states) and state management patterns (React/Vue reactive updates).

Phase 2: Context & Pattern Loading

1. Load diagnosis report from <session>/artifacts/diagnosis.md 2. Load diagnoser state via team_msg(operation="get_state", session_id=<session-id>, role="diagnoser") 3. Detect framework from project structure 4. Load framework-specific patterns:

Wisdom Input

1. Read <session>/wisdom/patterns/ui-feedback.md for established feedback design patterns 2. Read <session>/wisdom/patterns/state-management.md for state handling patterns 3. Read <session>/wisdom/principles/general-ux.md for UX design principles 4. Apply patterns when designing solutions for identified issues

Complex Design (use CLI)

For complex multi-component solutions:

Bash(`ccw cli -p "PURPOSE: Design comprehensive feedback mechanism for multi-step form
CONTEXT: @<component-files>
EXPECTED: Complete design with state flow diagram and code patterns
CONSTRAINTS: Must support React hooks" --tool gemini --mode analysis`)

Phase 3: Solution Design

For each diagnosed issue, design solution:

Feedback Mechanism Design

State Management Design

React Pattern:

const [isLoading, setIsLoading] = useState(false);
const [error, setError] = useState<string | null>(null);

const handleSubmit = async (event: React.FormEvent) => {
  event.preventDefault();
  setIsLoading(true);
  setError(null);
  try {
    const response = await fetch('/api/upload', { method: 'POST', body: formData });
    if (!response.ok) throw new Error('Upload failed');
  } catch (err: any) {
    setError(err.message || 'An error occurred');
  } finally {
    setIsLoading(false);
  }
};

Vue Pattern:

const isLoading = ref(false);
const error = ref<string | null>(null);

const handleSubmit = async () => {
  isLoading.value = true;
  error.value = null;
  try {
    const response = await fetch('/api/upload', { method: 'POST', body: formData });
    if (!response.ok) throw new Error('Upload failed');
  } catch (err: any) {
    error.value = err.message || 'An error occurred';
  } finally {
    isLoading.value = false;
  }
};

Input Control Design

Visual Design Solutions

Reference specs/design-standards.md for target standards.

UX Writing Solutions

Phase 4: Design Document Generation

1. Generate implementation guide for each issue and write to <session>/artifacts/design-guide.md

Wisdom Contribution

If novel design patterns created: 1. Write new patterns to <session>/wisdom/contributions/designer-pattern-<timestamp>.md 2. Format: Problem context, solution design, implementation hints, trade-offs

3. Share state via team_msg:

   team_msg(operation="log", session_id=<session-id>, from="designer",
            type="state_update", data={
              designed_solutions: <count>,
              framework: <framework>,
              patterns_used: [<pattern-list>]
            })

State Diagnoser

Diagnose root causes of UI issues: state management problems, event binding failures, async handling errors.

Phase 2: Context & Complexity Assessment

1. Load scan report from <session>/artifacts/scan-report.md 2. Load scanner state via team_msg(operation="get_state", session_id=<session-id>, role="scanner")

Wisdom Input

1. Read <session>/wisdom/patterns/ui-feedback.md and <session>/wisdom/patterns/state-management.md if available 2. Use patterns to identify root causes of UI interaction issues 3. Reference <session>/wisdom/anti-patterns/common-ux-pitfalls.md for common causes

3. Assess issue complexity:

Complex Analysis (use CLI)

For complex multi-file state management issues:

Bash(`ccw cli -p "PURPOSE: Analyze state management patterns and identify root causes
CONTEXT: @<issue-files>
EXPECTED: Root cause analysis with fix recommendations
CONSTRAINTS: Focus on reactive update patterns" --tool gemini --mode analysis`)

Phase 3: Root Cause Analysis

For each issue from scan report:

State Management Diagnosis

Event Binding Diagnosis

Async Handling Diagnosis

Visual Design Diagnosis

Phase 4: Diagnosis Report

1. Generate root cause analysis for each issue and write to <session>/artifacts/diagnosis.md

Wisdom Contribution

If new root cause patterns discovered: 1. Write diagnosis patterns to <session>/wisdom/contributions/diagnoser-patterns-<timestamp>.md 2. Format: Symptom, root cause, detection method, fix approach

3. Share state via team_msg:

   team_msg(operation="log", session_id=<session-id>, from="diagnoser",
            type="state_update", data={
              diagnosed_issues: <count>,
              pattern_types: {
                state_management: <count>,
                event_binding: <count>,
                async_handling: <count>,
                visual_design: <count>
              }
            })

Codebase Explorer

Explore codebase for UI component patterns, state management conventions, and framework-specific patterns. Callable by coordinator only.

Phase 2: Exploration Scope

1. Parse exploration request from task description 2. Determine file patterns based on framework:

Wisdom Input

1. Read <session>/wisdom/patterns/ui-feedback.md and <session>/wisdom/patterns/state-management.md if available 2. Use known patterns as reference when exploring codebase for component structures 3. Check <session>/wisdom/anti-patterns/common-ux-pitfalls.md to identify problematic patterns during exploration

3. Check exploration cache: <session>/explorations/cache-index.json

• If cache hit and fresh -> return cached results
• If cache miss or stale -> proceed to Phase 3

Phase 3: Codebase Exploration

Use ACE search for semantic queries:

mcp__ace-tool__search_context(
  project_root_path="<project-path>",
  query="<exploration-query>"
)

Exploration dimensions:

For each dimension, collect:

• File paths
• Pattern examples
• Convention notes

Phase 4: Exploration Summary

1. Generate pattern summary and write to <session>/explorations/exploration-summary.md 2. Cache results to <session>/explorations/cache-index.json

Wisdom Contribution

If new component patterns or framework conventions discovered: 1. Write pattern summaries to <session>/wisdom/contributions/explorer-patterns-<timestamp>.md 2. Format: Pattern Name, Framework, Use Case, Code Example, Adoption

4. Share state via team_msg:

   team_msg(operation="log", session_id=<session-id>, from="explorer",
            type="state_update", data={
              framework: <framework>,
              components_found: <count>,
              patterns_identified: [<pattern-list>]
            })

Code Implementer

Generate executable fix code with proper state management, event handling, and UI feedback bindings.

Phase 2: Task & Design Loading

1. Extract session path from task description 2. Read design guide: <session>/artifacts/design-guide.md 3. Extract implementation tasks from design guide 4. Wisdom Input:

• Read <session>/wisdom/patterns/state-management.md for state handling patterns
• Read <session>/wisdom/patterns/ui-feedback.md for UI feedback implementation patterns
• Read <session>/wisdom/principles/general-ux.md for implementation principles
• Load framework-specific conventions if available
• Apply these patterns and principles when generating code to ensure consistency and quality

5. For inner loop: Load context_accumulator from prior IMPL tasks

Context Accumulator (Inner Loop)

context_accumulator = {
  completed_fixes: [<fix-1>, <fix-2>],
  modified_files: [<file-1>, <file-2>],
  patterns_applied: [<pattern-1>]
}

Phase 3: Code Implementation

Implementation backend selection:

CLI Implementation (Complex)

Bash(`ccw cli -p "PURPOSE: Implement loading state and error handling for upload form
TASK:
  - Add useState for isLoading and error
  - Wrap async call in try/catch/finally
  - Update UI bindings for button and error display
CONTEXT: @src/components/Upload.tsx
EXPECTED: Modified Upload.tsx with complete implementation
CONSTRAINTS: Maintain existing code style" --tool gemini --mode write`)

Direct Implementation (Simple)

For simple state variable additions or UI binding changes use Edit/Write tools directly.

Implementation Steps

For each fix in design guide: 1. Read target file 2. Determine complexity (simple vs complex) 3. Apply fix using appropriate backend 4. Verify syntax (no compilation errors) 5. Append to context_accumulator

Phase 4: Self-Validation

Validation steps: 1. Run syntax check on modified files 2. Verify all files from design guide exist 3. Check acceptance criteria from design guide 4. If validation fails -> attempt auto-fix (max 2 attempts)

Context Accumulator Update

Append to context_accumulator and write summary to <session>/artifacts/fixes/README.md.

Share state via team_msg:

team_msg(operation="log", session_id=<session-id>, from="implementer",
         type="state_update", data={
           completed_fixes: <count>,
           modified_files: [<file-list>],
           validation_passed: true
         })

Wisdom Contribution

If reusable code patterns or snippets created: 1. Write code snippets to <session>/wisdom/contributions/implementer-snippets-<timestamp>.md 2. Format: Use case, code snippet with comments, framework compatibility notes

UI Scanner

Scan UI components to identify interaction issues: unresponsive buttons, missing feedback mechanisms, state not refreshing.

Phase 2: Context Loading

1. Extract session path and project path from task description 2. Detect framework from project structure:

3. Build file pattern list for scanning:

• React: **/*.tsx, **/*.jsx, **/use*.ts
• Vue: **/*.vue, **/composables/*.ts

Wisdom Input

1. Read <session>/wisdom/anti-patterns/common-ux-pitfalls.md if available 2. Use anti-patterns to identify known UX issues during scanning 3. Check <session>/wisdom/patterns/ui-feedback.md for expected feedback patterns

Complex Analysis (use CLI)

For large projects with many components:

Bash(`ccw cli -p "PURPOSE: Discover all UI components with user interactions
CONTEXT: @<project-path>/**/*.tsx @<project-path>/**/*.vue
EXPECTED: Component list with interaction types (click, submit, input, select)
CONSTRAINTS: Focus on interactive components only" --tool gemini --mode analysis`)

Phase 3: Component Scanning

Scan strategy:

Visual Design Scanning

In addition to interaction issues, scan for visual design quality problems. Reference specs/design-standards.md and specs/anti-patterns.md.

Heuristic UX Scanning

Apply Nielsen's 10 usability heuristics as a structured scan checklist. Reference: specs/heuristics.md

For each component file: 1. Read file content 2. Scan for interaction patterns using Grep 3. Check for feedback mechanisms (loading, error, success states) 4. Check state update patterns (mutation vs reactive) 5. Record issues with file:line references

Phase 4: Issue Report Generation

1. Classify issues by severity (High/Medium/Low) 2. Group by category (unresponsive, missing feedback, state issues, input UX, visual design) 3. Generate structured report and write to <session>/artifacts/scan-report.md 4. Share state via team_msg:

   team_msg(operation="log", session_id=<session-id>, from="scanner",
            type="state_update", data={
              total_issues: <count>,
              high: <count>, medium: <count>, low: <count>,
              categories: [<category-list>],
              scanned_files: <count>
            })

Wisdom Contribution

If novel UX issues discovered that aren't in anti-patterns: 1. Write findings to <session>/wisdom/contributions/scanner-issues-<timestamp>.md 2. Format: Issue description, detection criteria, affected components

Test Engineer

Generate and run tests to verify fixes (loading states, error handling, state updates).

Phase 2: Environment Detection

1. Detect test framework from project files:

2. Get changed files from implementer state:

   team_msg(operation="get_state", session_id=<session-id>, role="implementer")

3. Load test strategy from design guide

Wisdom Input

1. Read <session>/wisdom/anti-patterns/common-ux-pitfalls.md for common issues to test 2. Read <session>/wisdom/patterns/ui-feedback.md for expected feedback behaviors to verify 3. Use wisdom to design comprehensive test cases covering known edge cases

Phase 3: Test Generation & Execution

Test Generation

For each modified file, generate test cases covering loading states, error handling, state updates, and accessibility.

Test Execution

Iterative test-fix cycle (max 5 iterations):

1. Run tests: npm test or npm run test:unit 2. Parse results -> calculate pass rate 3. If pass rate >= 95% -> exit (success) 4. If pass rate < 95% and iterations < 5:

• Analyze failures
• Use CLI to generate fixes:

     Bash(`ccw cli -p "PURPOSE: Fix test failures
     CONTEXT: @<test-file> @<source-file>
     EXPECTED: Fixed code that passes tests
     CONSTRAINTS: Maintain existing functionality" --tool gemini --mode write`)

• Increment iteration counter
• Loop to step 1

5. If iterations >= 5 -> send fix_required message

Phase 4: Test Report

Wisdom Contribution

If new edge cases or test patterns discovered: 1. Write test findings to <session>/wisdom/contributions/tester-edge-cases-<timestamp>.md 2. Format: Edge case description, test scenario, expected behavior, actual behavior

Write report to <session>/artifacts/test-report.md.

Share state via team_msg:

team_msg(operation="log", session_id=<session-id>, from="tester",
         type="state_update", data={
           total_tests: <count>,
           passed: <count>,
           failed: <count>,
           pass_rate: <percentage>,
           fix_iterations: <count>
         })

If pass rate < 95%, send fix_required message to coordinator.

AI Slop Detection Catalog

20 visual anti-patterns commonly produced by AI code generation. Use during scanning to flag design quality issues.

1. AI Color Palette

• Pattern: Cyan (#00d4ff, #06b6d4), purple-blue gradients on dark backgrounds as default aesthetic
• Detection: Search for cyan/teal hex values, linear-gradient with blue-purple stops on dark bg
• Severity: P1

2. Gradient Text

• Pattern: background-clip: text + -webkit-text-fill-color: transparent on headings or metric values
• Detection: Grep for background-clip:\s*text or -webkit-background-clip:\s*text
• Severity: P1

3. Default Dark Mode + Glow

• Pattern: Dark background (#0a0a0a, #111) with neon accent colors and box-shadow glow effects
• Detection: Dark bg colors + box-shadow with colored spread on interactive elements
• Severity: P2

4. Glassmorphism Everywhere

• Pattern: backdrop-filter: blur() applied to more than 2 components
• Detection: Count occurrences of backdrop-filter:\s*blur across components
• Severity: P1

5. Hero Metric Layout

• Pattern: Large number + small label arranged in card grid, dashboard-style metrics as default layout
• Detection: Pattern of large font-size number + small text label repeated 3+ times in grid
• Severity: P2

6. Identical Card Grids

• Pattern: 3+ cards with identical size, structure, and visual weight
• Detection: Repeated card components with same dimensions and no visual differentiation
• Severity: P2

7. Nested Cards

• Pattern: Border/shadow container inside another border/shadow container
• Detection: Card component rendered inside another card component, nested border-radius + box-shadow
• Severity: P2

8. Generic Fonts

• Pattern: Inter, Roboto, Open Sans, Lato, Montserrat, Arial as primary font-family
• Detection: Grep font-family declarations for generic font names
• Severity: P2

9. Rounded Rect + Generic Shadow

• Pattern: border-radius: 8-16px + box-shadow: 0 1-4px ... on more than 5 elements
• Detection: Count elements with both border-radius and box-shadow, flag if >5
• Severity: P3

10. Large Icons Above Every Heading

• Pattern: Decorative icon/emoji placed above section headings, repeated 3+ times
• Detection: Icon component or SVG immediately preceding heading elements, 3+ occurrences
• Severity: P2

11. One-Side Border Accent

• Pattern: border-left: 3-4px solid <accent> as visual accent on cards/sections
• Detection: Grep for border-left:\s*\d+px\s+solid repeated across components
• Severity: P3

12. Decorative Sparklines

• Pattern: Tiny inline charts without axis labels, data values, or interactive tooltips
• Detection: Small chart components (<100px height) without label/tooltip props
• Severity: P2

13. Bounce/Elastic Easing

• Pattern: cubic-bezier with negative control point values, spring/bounce animation keywords
• Detection: Grep for cubic-bezier\([^)]*- or animation names containing bounce/spring/elastic
• Severity: P2

14. Redundant Copy

• Pattern: Heading text restated in immediately following body paragraph with >50% word overlap
• Detection: Compare heading text with first paragraph text for word overlap
• Severity: P3

15. All Buttons Primary

• Pattern: Every button uses same filled/accent treatment, no visual hierarchy
• Detection: All button variants resolve to same background-color, no secondary/tertiary variants
• Severity: P1

16. Everything Centered

• Pattern: Body text centered (text-align: center), more than 60% of sections centered
• Detection: Count text-align: center on non-heading, non-hero elements
• Severity: P2

17. Same Spacing Everywhere

• Pattern: >70% of padding/margin values are identical (e.g., all p-4 or p-6)
• Detection: Extract padding/margin values, check distribution uniformity
• Severity: P2

18. Monospace as Tech Aesthetic

• Pattern: Monospace font applied to non-code elements (headings, labels, navigation)
• Detection: font-family: monospace or code font on non-<code>/<pre> elements
• Severity: P3

19. Modal Overuse

• Pattern: More than 3 modal dialogs for non-critical interactions (settings, confirmations, info)
• Detection: Count modal/dialog component usages, check trigger context
• Severity: P3

20. Pure Black/White

• Pattern: #000, #fff, rgb(0,0,0), rgb(255,255,255) as primary background or text colors
• Detection: Grep for exact #000, #fff, rgb(0,0,0), rgb(255,255,255) in color/background properties
• Severity: P1

Visual Design Standards

Reference for visual design quality detection. Scanner and diagnoser use these standards to identify design issues.

Color Standards

• OKLCH for perceptually uniform palettes
• Tinted neutrals: chroma 0.005-0.01, never pure gray (#808080) or pure black/white (#000, #fff)
• 60-30-10 rule: 60% neutral, 30% secondary, 10% accent
• WCAG AA contrast: normal text 4.5:1, large text 3:1, UI components 3:1
• Text on colored backgrounds: use color-mix(in oklch, ...) not gray text

Typography Standards

• Avoid generic fonts: Inter, Roboto, Open Sans, Lato, Montserrat, Arial
• Modular scale (choose one ratio consistently): 1.125, 1.200, 1.250, 1.333
• Fluid sizing: clamp() for display text (xl and above)
• Line height: body 1.5, headings 1.2, small text 1.6
• Reading width: max-width: 65ch
• Font loading: font-display: swap

Spacing Standards

• 4pt base scale: 0, 4, 8, 12, 16, 20, 24, 32, 40, 48, 64, 96 px
• Rhythm variation: tight (4-8px), comfortable (16-24px), generous (48-96px)
• Sibling spacing: gap over margin
• No nested cards. Touch targets: 44x44px min

Motion Standards

• Animate ONLY: transform, opacity, clip-path, background-color, color, box-shadow, filter
• NEVER animate: width, height, top, left, margin, padding
• Easing: ease-out-quart cubic-bezier(0.25, 1, 0.5, 1) default. No bounce/elastic/linear
• Duration: instant 100ms, fast 150ms, normal 250ms, slow 400ms
• Reduced motion: @media (prefers-reduced-motion: reduce) REQUIRED

8 Interaction States

Visual Hierarchy

• Squint test: blur page, identify top 2 elements + groupings
• 1 primary CTA per viewport
• Progressive disclosure: reveal complexity on demand

Nielsen's 10 Usability Heuristics

Structured evaluation framework for UX scanning. Score each 0-4.

1. Visibility of System Status

The system should always keep users informed about what is going on.

• Loading indicators for async operations (> 200ms)
• Progress bars for multi-step processes
• State feedback (saved, syncing, error)
• Timestamps on data ("Updated 5 minutes ago")
• Active state indicators (selected tab, current page)

2. Match Between System and Real World

Speak the user's language, not technical jargon.

• Labels use familiar words (not internal terms)
• Icons match real-world metaphors
• Information appears in natural/logical order
• Dates, numbers, currencies in locale format

3. User Control and Freedom

Users need a clearly marked "emergency exit."

• Undo/redo for destructive or complex actions
• Back/cancel navigation always available
• Escape key closes modals/popovers
• Clear way to deselect, clear filters, reset

4. Consistency and Standards

Same words and actions should mean the same thing.

• One term per concept (delete/remove/trash → pick one)
• Same icon for same action across pages
• Follow platform conventions (links underlined, × means close)
• Consistent placement of actions (save always top-right, etc.)

5. Error Prevention

Better to prevent errors than show good error messages.

• Confirmation for destructive actions (with undo preferred)
• Input validation on blur (not just submit)
• Disable invalid options (gray out, not hide)
• Type-ahead/autocomplete for known-value fields
• Character counts for limited fields

6. Recognition Rather Than Recall

Minimize user memory load.

• Show options visibly (don't require memorization)
• Recent items, favorites, search suggestions
• Breadcrumbs for navigation context
• Inline help/tooltips for non-obvious fields
• Persistent important info (don't hide behind clicks)

7. Flexibility and Efficiency of Use

Accelerators for power users without confusing beginners.

• Keyboard shortcuts for frequent actions
• Bulk actions (select all, batch edit)
• Customizable views/layouts
• Search/filter as primary navigation for large datasets

8. Aesthetic and Minimalist Design

Every extra unit of information competes with relevant units.

• Remove decorative elements that don't aid comprehension
• Progressive disclosure (summary → detail on demand)
• Visual hierarchy: clear primary, secondary, tertiary
• Information density appropriate for use case

9. Help Users Recognize, Diagnose, and Recover from Errors

Error messages should be expressed in plain language.

• Formula: what happened + why + how to fix
• No error codes without explanation
• Suggest specific corrective action
• Preserve user input on error (don't clear forms)
• Retry option for network/server errors

10. Help and Documentation

Easy to search, focused on user's task.

• Contextual help (tooltips, info icons)
• Onboarding for first-time users
• Empty states with guidance and action
• Keyboard shortcut reference
• FAQ/search for complex features

Severity Scale

Pipeline Definitions

UX improvement pipeline modes and task registry.

Pipeline Modes

Standard Pipeline Task Registry

Checkpoints

Test Iteration Behavior

Output Artifacts

Wisdom System

Workers contribute learnings to <session>/wisdom/contributions/. On pipeline completion, coordinator asks user to merge approved contributions to permanent wisdom at ~ or <project>/.claude/skills/team-ux-improve/wisdom/.

Common UX Pitfalls

Interaction Issues

• Buttons without loading states during async operations
• Missing error handling with user feedback
• State changes without visual updates
• Double-click vulnerabilities (missing debounce)
• No disabled state during processing
• Silent failures without user notification
• Generic error messages without actionable guidance
• Missing confirmation for destructive actions
• No empty state placeholder for data lists
• Input without validation rules or inline feedback

State Management Issues

• Stale data after mutations (direct array/object mutation)
• Race conditions in async operations (no cancellation)
• Missing rollback for failed optimistic updates
• Stale closure capturing old state value
• Missing loading/error/success state tracking

Visual Design Anti-Patterns (AI Slop)

• AI Color Palette: cyan-on-dark, purple gradients (zero design intent)
• Gradient text: background-clip: text as emphasis crutch
• Glassmorphism everywhere: backdrop-filter as default aesthetic
• All Buttons Primary: no visual hierarchy, every button filled
• Pure Black/White: #000/#fff without tint (harsh, sterile)
• Generic fonts: Inter, Roboto as defaults (forgettable)
• Identical card grids: all items same visual weight
• Nested cards: cards inside cards creating noise
• Same spacing everywhere: no rhythm variation
• Bounce/elastic easing: dated animation feel
• Everything centered: including body text

Motion Issues

• Layout animations (width/height/margin/padding triggers)
• No reduced-motion query (@media prefers-reduced-motion)
• CSS will-change set permanently (GPU waste)
• ease/linear as default easing (unnatural)
• Stagger exceeding 500ms total

Accessibility Issues

• outline: none without :focus-visible replacement
• Missing :focus-visible (using bare :focus)
• Color-only state indication
• Touch targets < 44px
• No skip links
• Placeholder used as label
• Missing aria-describedby for error messages

State Management Patterns

Reactive Update Rules

• NEVER mutate arrays/objects directly
• React: use spread operator, filter/map for new references
• Vue: use ref() for primitives, reactive() for objects, computed() for derived
• Always trigger re-render through proper state API

Async State Pattern

const [data, setData] = useState(null);
const [loading, setLoading] = useState(false);
const [error, setError] = useState(null);

// Always: loading -> success/error -> cleanup

Race Condition Prevention

• AbortController for fetch cancellation
• Debounce for search/filter inputs (250-500ms)
• Latest-wins pattern for concurrent requests
• Disable trigger during processing

Optimistic Updates

• Update UI immediately
• Track pending state
• Rollback on failure with error notification
• Never lose user data silently

Form State

• Controlled inputs (React) / v-model (Vue)
• Validation on blur + on submit
• Error clearing on re-input
• Dirty tracking for unsaved changes warning

UI Feedback Patterns

Loading States

• Button: set disabled + aria-busy="true", show spinner, restore on complete
• Page: skeleton screens (prefer over spinners for content areas)
• Inline: progress indicator for multi-step operations
• Duration: show loading after 200ms delay (avoid flash for fast operations)

Error States

• Form: inline validation with aria-invalid + aria-describedby
• API: toast/snackbar for non-blocking, inline for blocking errors
• Error message: specific, actionable (not "Something went wrong")
• Visual: red border on input, error icon, error text below

Success States

• Form submit: success message + next action guidance
• CRUD: optimistic update with subtle confirmation
• Duration: success message visible 3-5 seconds

Empty States

• Data list: illustration + message + primary action
• Search: "No results" + suggestions
• First use: onboarding guidance

Focus Feedback

• :focus-visible only (not bare :focus)
• Ring: 2px solid accent, offset 2px
• Contrast: 3:1 against adjacent colors
• Custom for dark backgrounds: lighter ring color

Hover Feedback

• Wrap in @media(hover:hover) for touch safety
• Subtle: background opacity change or slight color shift
• Duration: 100-150ms transition
• Cursor: pointer for clickable, not-allowed for disabled

Active Feedback

• Scale: transform: scale(0.97) for physical feel
• Or: darker background shade
• Duration: instant (< 50ms feel)

General UX Principles

Feedback & Responsiveness

• Every user action must have immediate visual feedback (< 100ms perceived)
• Loading states for operations > 200ms: use skeleton/spinner, set aria-busy="true"
• Success/error states clearly communicated with both visual and ARIA cues
• Feedback duration: 100-150ms for hover/active/focus transitions
• State change transitions: 200-300ms
• Layout changes: 300-500ms

Interaction States (8 Required)

Every interactive element must define all 8 states: 1. Default — base appearance 2. Hover — subtle bg/opacity change, wrap in @media(hover:hover) 3. Focus — :focus-visible with 2px solid accent, offset 2px, 3:1 contrast ratio 4. Active — scale(0.97) or darker background 5. Disabled — opacity 0.5, cursor: not-allowed, aria-disabled="true" 6. Loading — spinner/skeleton, disable interaction, aria-busy="true" 7. Error — red border, error message below, aria-invalid="true" 8. Success — green check, success message

State Management

• UI state must reflect underlying data state immediately
• Optimistic updates must have rollback mechanisms
• State changes must be atomic and predictable
• No direct array/object mutation (use spread/filter/map for reactive frameworks)
• Race conditions: use request cancellation or debounce

Visual Design Quality

• Color: OKLCH-based, tinted neutrals (never pure gray/black/white), 60-30-10 rule
• Typography: distinctive fonts (not Inter/Roboto), modular scale, fluid clamp()
• Spacing: 4pt base scale with varied rhythm (tight/comfortable/generous)
• Motion: transform+opacity only, ease-out-quart easing, reduced-motion query required
• Hierarchy: squint test, single primary CTA per viewport

Accessibility

• All interactive elements keyboard accessible (tab + enter/space)
• Color must NOT be the only indicator of state
• Focus states must use :focus-visible (not bare :focus)
• Focus ring: 3:1 contrast against adjacent colors
• Touch targets: minimum 44x44px, 8px gap between adjacent
• Visible labels on all form inputs (placeholder is not a label)
• Skip links for keyboard navigation