claude-code-workflow 7.2.27 → 7.2.29

package/.codex/skills/team-ui-polish/roles/diagnostician/role.md

@@ -0,0 +1,164 @@
+---
+role: diagnostician
+prefix: DIAG
+inner_loop: false
+message_types: [diag_complete, diag_progress, error]
+---
+
+# Root Cause Diagnostician
+
+Deep-dive root cause analysis of discovered design problems. Classify severity, group systemic vs one-off issues, build fix dependency graph, and map each issue group to Impeccable fix strategies.
+
+## Phase 2: Context & Artifact Loading
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Scan report | <session>/scan/scan-report.md | Yes |
+| .msg/meta.json | <session>/wisdom/.msg/meta.json | Yes |
+| Fix strategies | specs/fix-strategies.md | Yes |
+| Design standards | specs/design-standards.md | Yes |
+
+1. Extract session path from task description
+2. Read scan report: parse per-dimension scores, issue inventory, systemic patterns
+3. Read specs/fix-strategies.md for issue-to-fix mapping
+4. Read specs/design-standards.md for target state reference
+
+## Phase 3: Root Cause Analysis
+
+### Step 1: Issue Classification
+
+For each issue in the scan report, classify:
+
+| Classification | Definition | Example |
+|---------------|------------|---------|
+| Systemic | Affects whole project, single root cause creates many symptoms | "No design token system" causes 15 hard-coded color issues |
+| One-off | Single component, isolated fix | Button missing hover state in one component |
+
+### Step 2: Root Cause Grouping
+
+Group issues by shared root cause. Common root cause patterns:
+
+| Root Cause | Typical Symptoms |
+|------------|-----------------|
+| No design token system | Hard-coded colors, inconsistent spacing, no theme support |
+| AI-generated template | Multiple AI slop tells (gradient text, glassmorphism, generic fonts) |
+| No typography system | Muddy hierarchy, arbitrary font sizes, no modular scale |
+| No spacing scale | Arbitrary spacing values, monotonous rhythm, no gap usage |
+| No motion system | Random durations, bad easing, no reduced-motion |
+| Missing state layer | No hover/focus/active/disabled/loading across components |
+| No responsive strategy | Fixed widths, missing breakpoints, small mobile targets |
+| No hierarchy design | Everything same weight, no squint test pass, size-only hierarchy |
+
+### Step 3: Priority Assignment
+
+For each root cause group:
+
+| Priority | Criteria |
+|----------|----------|
+| P0 | Contains any blocking issue (WCAG AA failure, missing focus, horizontal scroll, no viewport meta) |
+| P1 | Contains major issues (pure black/white, contrast near-fail, missing hover/loading) |
+| P2 | Contains minor issues (no OKLCH, overused fonts, monotonous spacing) |
+| P3 | Polish only (missing exit animation, no container queries, optical adjustments) |
+
+### Step 4: Fix Strategy Mapping
+
+For each root cause group, map to Impeccable fix strategy (from specs/fix-strategies.md):
+
+| Root Cause | Fix Strategy | Effort |
+|------------|-------------|--------|
+| No token system | Create token file, tokenize all values | systemic, high |
+| AI template aesthetic | Break templates, add intentional design | systemic, high |
+| No type system | Define modular scale, apply across project | systemic, medium |
+| No spacing scale | Define 4pt scale, replace arbitrary values | systemic, medium |
+| No motion system | Create motion tokens, fix easing/duration | systemic, medium |
+| Missing states | Add state CSS to each component | distributed, medium |
+| No responsive | Add media queries, fix widths/targets | distributed, high |
+| Individual issues | Component-level fixes | one-off, low |
+
+### Step 5: Fix Dependency Graph
+
+Build ordered dependency graph:
+
+```
+1. Design token system (if missing) -- everything else depends on this
+2. Color fixes (pure black/white, contrast) -- visual foundation
+3. Typography system -- content hierarchy
+4. Spacing scale -- layout foundation
+5. Anti-AI-slop cleanup -- requires tokens, colors, type to be in place
+6. Motion system -- independent
+7. Interaction states -- independent per component
+8. Visual hierarchy -- requires typography + spacing
+9. Responsive fixes -- last, tests everything together
+```
+
+Rules:
+- Token system MUST come before individual token consumption fixes
+- Color fixes before anti-slop (anti-slop fixes may adjust colors)
+- Typography before hierarchy (hierarchy depends on type scale)
+- Responsive fixes last (they validate all other fixes at different viewports)
+
+## Phase 4: Validate Diagnosis Completeness
+
+| Check | Pass Criteria |
+|-------|---------------|
+| All issues covered | Every issue from scan report appears in at least one root cause group |
+| No orphan issues | No issues without a root cause group |
+| Fix strategies assigned | Every root cause group has a fix strategy |
+| Dependencies valid | Dependency graph is acyclic |
+| Priority consistent | Group priority matches highest-severity issue in group |
+
+Output: `<session>/diagnosis/diagnosis-report.md`
+
+Report structure:
+
+```markdown
+# Diagnosis Report
+
+## Summary
+- Total issues: N (P0: X, P1: X, P2: X, P3: X)
+- Root cause groups: N
+- Systemic issues: N
+- One-off issues: N
+- Estimated effort: <low|medium|high>
+
+## Root Cause Groups (by priority)
+
+### [P0] <Root Cause Name>
+- **Type**: systemic | one-off
+- **Affected issues**: <count>
+- **Affected files**: <file list>
+- **Description**: <what is fundamentally wrong>
+- **Fix strategy**: <from fix-strategies.md>
+- **Effort**: <quick fix | medium | systemic change>
+- **Dependencies**: <which other fixes must come first>
+- **Issues in this group**:
+  | # | Location | Severity | Description |
+  |---|----------|----------|-------------|
+  | 1 | file:line | P0 | ... |
+
+### [P1] <Root Cause Name>
+...
+
+## Fix Dependency Graph
+<ordered list of fix phases>
+
+## Recommended Fix Order
+1. <fix phase 1>: <root cause groups to address>
+2. <fix phase 2>: <root cause groups to address>
+...
+
+## Metadata
+- Source: <session>/scan/scan-report.md
+- Original score: X/32
+- Timestamp: <ISO timestamp>
+```
+
+After writing the report, update session state:
+```
+mcp__ccw-tools__team_msg(session_id, role="diagnostician", type="diag_complete", content="Diagnosis complete. Root cause groups: N. Systemic: N. Fix phases: N.")
+```
+
+Then use `report_agent_job_result` to signal completion to coordinator:
+```
+report_agent_job_result({ result: "[diagnostician] DIAG-001 complete. Root cause groups: N (P0: X, P1: X, P2: X, P3: X). Systemic: N, One-off: N. Report: <session>/diagnosis/diagnosis-report.md" })
+```

package/.codex/skills/team-ui-polish/roles/optimizer/role.md

@@ -0,0 +1,229 @@
+---
+role: optimizer
+prefix: OPT
+inner_loop: true
+message_types: [opt_complete, opt_progress, error]
+---
+
+# UI Optimizer -- Targeted Fix Application
+
+Apply targeted fixes following Impeccable design standards. Consumes diagnosis report and applies fixes in dependency order. Acts as Generator in the optimizer<->verifier Generator-Critic loop.
+
+## Phase 2: Context & Artifact Loading
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Scan report | <session>/scan/scan-report.md | Yes |
+| Diagnosis report | <session>/diagnosis/diagnosis-report.md | Yes |
+| .msg/meta.json | <session>/wisdom/.msg/meta.json | Yes |
+| Fix strategies | specs/fix-strategies.md | Yes |
+| Design standards | specs/design-standards.md | Yes |
+| Verification feedback | <session>/verification/verify-report.md | Only for GC fix tasks |
+
+1. Extract session path from task description
+2. Read diagnosis report: parse root cause groups, fix dependency graph, recommended fix order
+3. Read scan report: parse positive findings (things to preserve)
+4. Read specs/fix-strategies.md and specs/design-standards.md for fix reference
+5. Detect task type from subject: "OPT-001" -> initial optimization, "OPT-fix-*" -> GC fix round
+6. If GC fix task: read verification feedback for specific regressions to fix
+
+## Phase 3: Apply Fixes
+
+Follow the fix dependency graph from diagnosis report. Apply fixes in order, one category at a time. After each category, self-validate before proceeding.
+
+**CRITICAL**: Preserve positive findings from scan report. Do not break what already works.
+
+---
+
+### Fix Category 1: Anti-AI-Slop Fixes
+
+Target: Root cause groups tagged with anti-patterns dimension.
+
+| Issue | Fix |
+|-------|-----|
+| Generic fonts (Inter, Roboto, Open Sans) | Replace with distinctive alternatives: Instrument Sans, Plus Jakarta Sans, Fraunces, DM Sans, Manrope, Space Grotesk, Geist |
+| Gradient text | Convert to solid accent color. Remove `background-clip: text` + gradient |
+| Identical card grids | Vary card sizes, add featured/hero card, break symmetry. Not everything needs to be a card |
+| Glassmorphism decoration | Remove `backdrop-filter: blur()` unless serving real purpose (e.g., overlays). Replace glow borders with subtle shadows |
+| Hero metric template | Redesign with intentional layout. Vary metric sizes by importance. Remove gradient accents |
+| Nested cards | Flatten: remove inner card borders, use spacing + subtle dividers instead |
+| Everything centered | Add left-alignment for body text. Use asymmetric layouts. Vary alignment per section |
+| All buttons primary | Create button hierarchy: 1 primary, ghost/outline for secondary, text links for tertiary |
+| Same spacing everywhere | Introduce spacing rhythm: tighter within groups, generous between sections |
+| Bounce/elastic easing | Replace with exponential curves: `cubic-bezier(0.25, 1, 0.5, 1)` (ease-out-quart) |
+
+---
+
+### Fix Category 2: Color Fixes
+
+Target: Root cause groups tagged with color dimension.
+
+| Issue | Fix |
+|-------|-----|
+| Pure black (#000) | Replace with tinted near-black: `oklch(0.15 0.01 <brand-hue>)` or `#0a0a0a`-range tinted |
+| Pure white (#fff) | Replace with tinted near-white: `oklch(0.98 0.005 <brand-hue>)` or `#fafaf8`-range tinted |
+| Untinted grays | Add brand hue tint: `oklch(L 0.005-0.01 <brand-hue>)` for each gray step |
+| Gray on colored bg | Replace with shade of background color or use `color-mix()` / transparency |
+| Contrast failures | Increase lightness difference until WCAG AA met (4.5:1 text, 3:1 large text, 3:1 UI) |
+| No OKLCH | Convert key palette colors to `oklch()`. Especially for generating tints/shades |
+| Accent overuse | Reduce accent to ~10% of page. Convert excess accent to neutral or secondary |
+| No semantic roles | Create token structure: `--color-primary`, `--color-neutral-*`, `--color-success/warning/error`, `--color-surface-*` |
+| Hard-coded colors | Extract to CSS custom properties. Create design token file if none exists |
+
+---
+
+### Fix Category 3: Typography Fixes
+
+Target: Root cause groups tagged with typography dimension.
+
+| Issue | Fix |
+|-------|-----|
+| Overused fonts | Replace with distinctive alternatives. Body: Plus Jakarta Sans, Instrument Sans, DM Sans. Display: Fraunces, Space Grotesk, Manrope |
+| Muddy hierarchy | Establish clear modular scale. Remove intermediate sizes. Target: 5-7 distinct sizes |
+| No modular scale | Define scale with ratio (1.25 major third, 1.333 perfect fourth, 1.5 perfect fifth). Base: 16px |
+| Small body text | Set minimum `font-size: 1rem` (16px) for body. 14px only for captions/metadata |
+| Bad line length | Add `max-width: 65ch` to prose containers. Min 45ch, max 75ch |
+| Inconsistent line-height | Establish system: 1.5 for body, 1.2-1.3 for headings, 1.6-1.7 for small text |
+| No fluid sizing | Add `clamp()` for h1-h3: e.g., `font-size: clamp(1.75rem, 1.2rem + 2vw, 3rem)` |
+| Missing font-display | Add `font-display: swap` to all @font-face declarations |
+
+---
+
+### Fix Category 4: Spacing & Layout Fixes
+
+Target: Root cause groups tagged with spacing dimension.
+
+| Issue | Fix |
+|-------|-----|
+| Arbitrary spacing | Replace with nearest value on 4pt scale: 4, 8, 12, 16, 24, 32, 48, 64, 96px |
+| No spacing scale | Create CSS custom properties: `--space-1: 0.25rem` through `--space-12: 6rem` |
+| Monotonous spacing | Vary spacing: tighter within component groups (8-12px), generous between sections (48-96px) |
+| Card overuse | Remove card wrapper from items that do not need distinct containment. Use spacing + dividers |
+| Nested cards | Flatten inner cards. Remove inner borders. Use spacing or subtle background tint |
+| Fixed widths | Replace `width: Npx` with `max-width` + `width: 100%` or grid/flex |
+| Small touch targets | Set `min-height: 44px; min-width: 44px` on all interactive elements |
+| Margin for siblings | Replace `margin-top/bottom` between siblings with `gap` on flex/grid parent |
+
+---
+
+### Fix Category 5: Motion Fixes
+
+Target: Root cause groups tagged with motion dimension.
+
+| Issue | Fix |
+|-------|-----|
+| Layout property animation | Replace `width/height/top/left/margin/padding` transitions with `transform` + `opacity` |
+| Bad easing | Replace `ease`, `linear`, `ease-in-out` with `cubic-bezier(0.25, 1, 0.5, 1)` (ease-out-quart) |
+| Bounce/elastic | Replace with exponential: `cubic-bezier(0.25, 1, 0.5, 1)` for enter, `cubic-bezier(0.5, 0, 0.75, 0)` for exit |
+| No reduced-motion | Add: `@media (prefers-reduced-motion: reduce) { *, *::before, *::after { animation-duration: 0.01ms !important; transition-duration: 0.01ms !important; } }` |
+| No motion tokens | Create: `--duration-instant: 100ms`, `--duration-fast: 150ms`, `--duration-normal: 250ms`, `--duration-slow: 400ms`, `--duration-entrance: 500ms` |
+| Uncapped stagger | Cap at 10 items visible, total stagger <= 500ms. Use `animation-delay: min(calc(var(--i) * 50ms), 500ms)` |
+| Premature will-change | Remove from CSS. Add via JS on `pointerenter`/`focusin`, remove on `animationend`/`transitionend` |
+
+---
+
+### Fix Category 6: Interaction State Fixes
+
+Target: Root cause groups tagged with interaction dimension.
+
+| Issue | Fix |
+|-------|-----|
+| Missing hover | Add `:hover` with subtle background change or opacity shift. Use `@media (hover: hover)` to scope |
+| Missing focus | Add `:focus-visible` with focus ring: `outline: 2px solid var(--color-primary); outline-offset: 2px` |
+| outline: none | Replace with `:focus-visible` pattern. Only `:focus:not(:focus-visible) { outline: none }` |
+| No focus-visible | Replace `:focus` styles with `:focus-visible`. Add polyfill if browser support needed |
+| Missing active | Add `:active` with `transform: scale(0.97)` or darker background |
+| Missing disabled | Add `[disabled], [aria-disabled="true"]` with `opacity: 0.5; cursor: not-allowed; pointer-events: none` |
+| Missing loading | Add loading state: spinner/skeleton + `aria-busy="true"` + disable submit button |
+| Missing error/success | Add form validation styles: red border + error message for error, green check for success |
+| Placeholder as label | Add visible `<label>` element. Keep placeholder as hint only. Use `aria-labelledby` if needed |
+| Focus ring quality | Ensure: 2px solid accent, offset 2px, 3:1 contrast ratio against background |
+
+---
+
+### Fix Category 7: Visual Hierarchy Fixes
+
+Target: Root cause groups tagged with hierarchy dimension.
+
+| Issue | Fix |
+|-------|-----|
+| Fails squint test | Increase size/weight/color contrast of primary element. Reduce visual weight of secondary elements |
+| Primary action unclear | Make primary CTA largest, highest contrast, most saturated. Only 1 primary per viewport |
+| Size-only hierarchy | Add weight (bold vs regular) + color (saturated vs muted) + space (more surrounding space = more important) |
+| No information grouping | Use proximity principle: tighter spacing within groups, larger gaps between groups |
+| Visual competition | Reduce visual weight of competing elements. Mute colors, reduce size, decrease contrast |
+| No 3:1 ratio | Ensure h1 is at least 3x body size. Each heading level should be 1.25-1.5x the next |
+| Decoration over content | Reduce or remove decorative elements. Mute icon colors. Remove background decorations |
+
+---
+
+### Fix Category 8: Responsive Fixes
+
+Target: Root cause groups tagged with responsive dimension.
+
+| Issue | Fix |
+|-------|-----|
+| Fixed widths | Replace with `max-width` + `width: 100%`, or `min()`, or grid `fr` units |
+| Horizontal scroll | Find overflow source. Add `overflow-x: hidden` on body only as last resort. Fix root cause |
+| Hidden content | Restructure for mobile instead of hiding. Use accordion, tabs, or progressive disclosure |
+| No container queries | Add `container-type: inline-size` on component wrappers. Use `@container` for component-level responsive |
+| Small mobile text | Set minimum 14px (0.875rem) for all text on mobile. Prefer 16px for body |
+| Tiny mobile targets | Set `min-height: 44px` on all interactive elements. Add padding if needed |
+| No breakpoints | Add: `@media (min-width: 640px)`, `(min-width: 768px)`, `(min-width: 1024px)`, `(min-width: 1280px)` |
+| Broken images | Add `img { max-width: 100%; height: auto }`. Use `object-fit` for fixed aspect ratios |
+
+---
+
+## Phase 4: Self-Validation & Output
+
+1. After all fixes applied, validate:
+
+| Check | Pass Criteria |
+|-------|---------------|
+| Code compiles | No syntax errors in modified files |
+| Lint passes | No new lint errors introduced |
+| No positive findings broken | Items from scan report "Positive Findings" section still intact |
+| Fix log complete | Every applied fix documented |
+
+2. Write fix log: `<session>/optimization/fix-log.md`
+
+```markdown
+# Optimization Fix Log
+
+## Summary
+- Fixes applied: N
+- Files modified: N
+- Categories addressed: <list>
+- GC round: <1 | fix-N>
+
+## Fixes Applied
+
+### Category: <category name>
+| # | File | Line | Before | After | Issue Ref |
+|---|------|------|--------|-------|-----------|
+| 1 | path/to/file.css | 42 | `color: #000` | `color: oklch(0.15 0.01 250)` | P1-Color-3 |
+
+### Category: <next category>
+...
+
+## Files Modified
+- `path/to/file.css`: <summary of changes>
+- `path/to/file.tsx`: <summary of changes>
+
+## Preserved (not modified)
+- <positive findings that were intentionally kept>
+
+## Metadata
+- Source diagnosis: <session>/diagnosis/diagnosis-report.md
+- Timestamp: <ISO timestamp>
+```
+
+3. Update session state and signal completion:
+```
+mcp__ccw-tools__team_msg(session_id, role="optimizer", type="opt_complete", content="Optimization complete. Fixes applied: N. Files modified: N. Categories: <list>.")
+```
+
+Then use `report_agent_job_result` to signal completion to coordinator:
+```
+report_agent_job_result({ result: "[optimizer] OPT-001 complete. Applied N fixes across N files. Categories: <list>. Log: <session>/optimization/fix-log.md" })
+```