wicked-garden 12.27.0

package/skills/product/synthesize/refs/prioritization.md

@@ -0,0 +1,193 @@
+---
+phase_relevance: ["clarify", "design", "review"]
+archetype_relevance: ["*"]
+---
+# Prioritization Framework
+
+Detailed framework for translating customer voice into feature priorities.
+
+## Priority Scoring Formula
+
+```
+Priority Score = (Customer_Impact × Urgency × Frequency) / Effort
+
+Where:
+- Customer_Impact: 1-5 (how much it matters to customers)
+- Urgency: 1-5 (time sensitivity)
+- Frequency: 1-5 (how often mentioned)
+- Effort: 1-5 (implementation complexity)
+```
+
+## Customer Impact Scale
+
+**5 - Critical**: Blocking work, causing churn
+- "Can't complete my job without this"
+- Active cancellations mentioned
+- Security or data loss issues
+
+**4 - High**: Major friction, competitive disadvantage
+- "This is very frustrating"
+- Competitors have it, we don't
+- Workarounds are painful
+
+**3 - Medium**: Clear improvement, efficiency gain
+- "Would make my work easier"
+- Multiple steps could be one
+- Quality of life improvement
+
+**2 - Low**: Nice to have, minor convenience
+- "Would be cool if..."
+- Edge case enhancement
+- Aesthetic preference
+
+**1 - Minimal**: Vanity feature, individual preference
+- Single user request
+- Already have workaround
+- No clear benefit
+
+## Urgency Scale
+
+**5 - Immediate**: Losing customers now
+- Churn happening
+- Escalations from leadership
+- Legal/compliance risk
+
+**4 - High**: Competitive pressure
+- Competitors launched similar
+- Market expectation
+- Sales blocker
+
+**3 - Medium**: Growing concern
+- Increasing frequency
+- Multiple segments affected
+- Strategic alignment
+
+**2 - Low**: Future consideration
+- On roadmap
+- Nice strategic fit
+- Minor competitive gap
+
+**1 - None**: No time pressure
+- Evergreen request
+- No external forcing function
+- Can wait indefinitely
+
+## Frequency Scale
+
+**5 - Very High**: >100 mentions
+**4 - High**: 50-100 mentions
+**3 - Medium**: 20-49 mentions
+**2 - Low**: 5-19 mentions
+**1 - Minimal**: <5 mentions
+
+Adjust based on total feedback volume (normalize).
+
+## Effort Scale
+
+**5 - Very High**: Major system change, >1 quarter
+**4 - High**: Significant work, 4-8 weeks
+**3 - Medium**: Standard feature, 2-4 weeks
+**2 - Low**: Small enhancement, 1-2 weeks
+**1 - Minimal**: Quick fix, <1 week
+
+## Example Calculations
+
+### Example 1: Mobile Performance Issues
+
+```
+Customer_Impact: 5 (users can't complete tasks)
+Urgency: 4 (competitors have better mobile)
+Frequency: 4 (65 mentions in Q1)
+Effort: 3 (requires optimization work, not rebuild)
+
+Score = (5 × 4 × 4) / 3 = 26.7
+
+Priority: P0 (Critical)
+```
+
+### Example 2: Dark Mode Request
+
+```
+Customer_Impact: 2 (aesthetic preference)
+Urgency: 1 (no time pressure)
+Frequency: 3 (25 mentions over 6 months)
+Effort: 2 (CSS changes, relatively quick)
+
+Score = (2 × 1 × 3) / 2 = 3.0
+
+Priority: P3 (Low)
+```
+
+### Example 3: Bulk Actions Feature
+
+```
+Customer_Impact: 4 (significant time savings for power users)
+Urgency: 3 (productivity enhancement)
+Frequency: 3 (30 mentions from enterprise segment)
+Effort: 3 (new UI, backend changes)
+
+Score = (4 × 3 × 3) / 3 = 12.0
+
+Priority: P1 (High)
+```
+
+## Priority Levels
+
+**P0 - Critical**: Score >20, or any churn risk
+- Address immediately
+- Communicate timeline to customers
+- Fast-track through development
+
+**P1 - High**: Score 10-20
+- Next 1-2 sprints
+- Include in quarterly roadmap
+- Update requesting customers
+
+**P2 - Medium**: Score 5-10
+- Roadmap consideration
+- Batch with similar work
+- Acknowledge to customers
+
+**P3 - Low**: Score <5
+- Backlog item
+- Revisit if frequency increases
+- Polite decline or defer
+
+## Segment Weighting
+
+Adjust impact based on customer segment:
+
+```
+Enterprise: 2× multiplier (higher revenue, strategic)
+Growth: 1.5× multiplier (expansion potential)
+SMB: 1× multiplier (baseline)
+Free/Trial: 0.5× multiplier (not yet revenue)
+```
+
+## Quick Win Identification
+
+Quick wins have:
+- Score >8 (meaningful impact)
+- Effort ≤2 (quick implementation)
+- Clear customer benefit
+
+These should be called out separately for morale and momentum.
+
+## Validation Questions
+
+Before finalizing recommendation:
+
+1. **Is this a real need or symptom?**
+   - Feature request might mask underlying UX issue
+
+2. **Will this solve the actual problem?**
+   - Validate with customer examples
+
+3. **Are we building for the vocal minority?**
+   - Check segment distribution
+
+4. **What's the opportunity cost?**
+   - What else could we build instead?
+
+5. **Is there a simpler solution?**
+   - Configuration change, documentation, existing feature

package/skills/product/ux-review/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: ux-review
+description: |
+  Use when evaluating UX quality — user flows, information architecture, user research synthesis,
+  personas, and usability assessment. Also covers generative UX flow design from requirements.
+  NOT for visual design consistency (use visual-review) or accessibility code audits (use product/accessibility).
+phase_relevance: ["clarify", "design", "review"]
+archetype_relevance: ["*"]
+---
+
+# UX Review Skill
+
+UX and design quality thinking embedded throughout delivery.
+
+## Core Concept
+
+Good UX is how we build trust. Don't wait for polish phase—design with users in mind from the start.
+
+## Four Focus Areas
+
+| Area | Expert | Focus |
+|------|--------|-------|
+| **User Flows** | UX Designer | Experience design, interactions, IA |
+| **Visual Design** | UI Reviewer | Consistency, components, design system |
+| **Accessibility** | A11y Expert | WCAG, keyboard, screen readers |
+| **User Research** | User Researcher | Needs, personas, journeys |
+
+## Commands
+
+| Command | Purpose |
+|---------|---------|
+| `/wicked-garden:product:ux-review` | Run UX review (auto-detect focus) |
+| `/wicked-garden:product:ux-review --focus flows` | User flow analysis |
+| `/wicked-garden:product:ux-review --focus ui` | Visual design review |
+| `/wicked-garden:product:ux-review --focus a11y` | Accessibility audit |
+| `/wicked-garden:product:ux-review --focus research` | User research |
+| `/wicked-garden:product:ux-review --focus all` | Comprehensive review |
+
+## Usage
+
+```bash
+# Auto-detect what to review
+/wicked-garden:product:ux-review src/components/Dashboard
+
+# Focus on accessibility
+/wicked-garden:product:ux-review src/components/Form --focus a11y
+
+# User research on requirements
+/wicked-garden:product:ux-review outcome.md --focus research
+
+# Comprehensive review
+/wicked-garden:product:ux-review src/app --focus all
+
+# Quick triage
+/wicked-garden:product:ux-review src/components --quick
+```
+
+## Output
+
+Review produces:
+- **Issues**: Critical / Major / Minor findings
+- **Recommendations**: Specific, actionable improvements
+- **Evidence**: Screenshots, code snippets, WCAG citations
+- **Tasks**: Issues tracked via native TaskCreate for follow-up
+
+## Review Types
+
+### User Flow Review
+- Happy path clarity
+- Error handling
+- User mental models
+- Interaction patterns
+- Information architecture
+
+### Visual Design Review
+- Color consistency
+- Typography scale
+- Spacing system
+- Component patterns
+- Responsive design
+- Visual polish
+
+### Accessibility Audit
+- WCAG 2.1 Level AA compliance
+- Keyboard navigation
+- Screen reader support
+- Semantic HTML
+- ARIA patterns
+- Color contrast
+
+### User Research
+- User needs discovery
+- Persona creation
+- Journey mapping
+- Problem validation
+- Jobs to Be Done
+
+## Integration
+
+Works with:
+- **wicked-crew**: Auto-suggested after phases
+- **Read tool**: Analyze screenshots directly; capture via browser automation if available
+- **Native tasks**: Issue tracking via TaskCreate with `metadata.event_type="task"`
+- **wicked-brain:memory**: Design system memory
+- **wicked-garden:search**: Pattern discovery
+
+## Phase Integration
+
+| Phase | Suggested Review | Expert |
+|-------|------------------|--------|
+| Clarify | User research | User Researcher |
+| Design | User flows + IA | UX Designer |
+| Build | A11y + UI consistency | A11y Expert + UI Reviewer |
+| Review | Comprehensive review | All experts |
+
+## Quick Checks
+
+For fast feedback:
+
+```bash
+# Quick a11y scan
+/wicked-garden:product:ux-review {file} --focus a11y --quick
+
+# Quick UI consistency
+/wicked-garden:product:ux-review {file} --focus ui --quick
+
+# Quick flow check
+/wicked-garden:product:ux-review {file} --focus flows --quick
+```
+
+## Common Findings
+
+**UX**: Unclear flows, missing error states, confusing navigation
+**UI**: Color/typography/spacing inconsistencies, missing states
+**A11y**: Missing alt text, poor contrast, no keyboard access
+**Research**: Assumed needs, missing personas, unmapped journeys
+
+## Output Artifacts
+
+- `ux-review.md` - Findings and recommendations
+- `personas/`, `journeys/` - Research artifacts
+- `a11y-report.md` - Accessibility results
+- Native tasks for tracking (TaskCreate with `metadata.event_type="task"`)
+
+## Best Practices
+
+1. Review early - catch issues in design phase
+2. Focus on users - always ask "how does this help?"
+3. Be specific - give actionable recommendations
+4. Cite standards - reference WCAG, design system
+5. Track issues - use native TaskCreate for follow-through
+
+## Getting Started
+
+```bash
+# Comprehensive quick review
+/wicked-garden:product:ux-review src/ --focus all --quick
+
+# Accessibility deep dive
+/wicked-garden:product:ux-review src/components --focus a11y
+
+# User research
+/wicked-garden:product:ux-review outcome.md --focus research
+```

package/skills/product/visual-direction/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: visual-direction
+description: |
+  Figure out what a section of content *should be* visually before reaching for any
+  implementation pattern. Answers five structured questions — content structure,
+  audience mental model, desired action, physical artifact metaphor, and the stupid-question
+  test — then produces a one-paragraph visual brief for the implementer.
+
+  Use when: designing a new section, evaluating a proposed visual treatment, or catching
+  the nearest-neighbor trap (copying the adjacent project's pattern without asking if it fits).
+
+  NOT for: accessibility audits (use product:a11y), visual consistency review (use product:ux-review),
+  or wireframing (use product:mockup).
+phase_relevance: ["clarify", "design", "review"]
+archetype_relevance: ["*"]
+---
+
+# Visual Direction Skill
+
+Reason from content structure to visual form — not from available patterns to first fit.
+
+## The Problem This Solves
+
+The nearest-neighbor trap: when Project B is being designed and Project A nearby used a
+pattern that worked (sidebar + sticky stage + crawling tick), the agent reaches for that
+pattern without asking whether Project B's content warrants it. A pattern that was right
+for A's content may be actively wrong for B's.
+
+**Real example:** A marketing site redesign for wicked-garden kept applying the
+wicked-interactive conveyor pattern (sticky stage, left sidebar ledger, yellow tick) to
+sections where it didn't fit. The "No cloud / No black box" refusals are philosophical
+statements — they want to be big typographic text, not a scroll-pinned station list. The
+tools section is a pipeline — it wants to be a session log showing the system working, not
+a sidebar tour. It took three rounds of user pushback before the agent stopped copying and
+started reasoning from the content itself.
+
+## The Five Questions (answer in order)
+
+### Q1 — What IS this content?
+Not "what should it look like" — what is its intrinsic structure?
+
+| Content type | Examples |
+|---|---|
+| Timeline | Steps, stages, history, before/after |
+| Principles / manifesto | Philosophical statements, refusals, beliefs |
+| Pipeline | Tools in sequence, data flow, system working |
+| Comparison | Options side by side, trade-offs |
+| Catalog | Items browsed, filtered, selected |
+| Narrative | A story with a beginning, tension, resolution |
+| Metric / dashboard | Numbers, status, health |
+
+Name the type before doing anything else.
+
+### Q2 — What does the audience already think in?
+Match the metaphor to their mental model, not yours.
+
+| Audience | Natural mental models |
+|---|---|
+| Developers | Logs, diffs, terminal output, config files |
+| Executives | Dashboards, summaries, traffic lights |
+| Designers | Grids, layers, component libraries |
+| End users | Shopping, browsing, reading |
+| Ops / SRE | Alerts, runbooks, timelines |
+
+If the proposed visual form would feel alien to the intended audience, it's wrong.
+
+### Q3 — What action do we want the user to take?
+The visual treatment — including motion — should serve the action, not decorate the section.
+
+| Desired action | Visual implication |
+|---|---|
+| Trust it | Calm, credible, evidence-based — not flashy |
+| Install it | Clear path, no obstacles, quick scan |
+| Understand it | Progressive disclosure, not all at once |
+| Feel it | Emotion first, detail second |
+| Choose it | Comparison-friendly, scannable differences |
+
+Animation that doesn't serve the desired action is noise.
+
+### Q4 — If this content were a physical artifact, what form would it take?
+Bypass the pattern library entirely. Name the physical object.
+
+Examples: a receipt, a log printout, a map, a library shelf, a garden, a contract, a
+command-line session, a newspaper front page, a sticky note wall, a timeline on a wall,
+a warning label.
+
+The physical artifact test often surfaces the right visual form faster than any pattern catalog.
+
+### Q5 — The Stupid-Question Test
+Would presenting this content in the proposed form feel obviously wrong to someone who
+just read it carefully?
+
+Run the test explicitly: "If someone read all of [content] and then saw it rendered as
+[proposed form], would they laugh or wince?"
+
+Examples of failing the stupid-question test:
+- Four philosophical "No X" manifestos rendered as fake browser tabs
+- A system pipeline tour rendered as a customer testimonial carousel
+- A comparison of two tools rendered as a hero animation
+- A timeline of events rendered as a card grid
+
+## Output: The Visual Brief
+
+After answering all five questions, produce a one-paragraph visual brief in this form:
+
+```
+Visual Brief — [Section Name]
+
+Content type: [name from Q1]. Audience mental model: [from Q2]. The section wants the
+user to [action from Q3]. Physical artifact: [from Q4]. Proposed treatment: [one sentence
+on form + motion]. Nearest-neighbor risk: [name the pattern being avoided and why it
+doesn't fit]. Animation role: [one sentence on what motion does or "no animation — the
+content is static"].
+```
+
+This brief is the handoff to the implementer. Do not skip to implementation without it.
+
+## Anti-Patterns to Name Explicitly
+
+- **Conveyor misuse**: Sticky stage + sidebar ledger is a navigation pattern for sequential
+  steps a user progresses through. Don't apply it to content that isn't a progression.
+- **Tab misuse**: Tabs imply interchangeable peers. Don't use them for content that has
+  an inherent order or a single message.
+- **Carousel misuse**: Carousels hide content. Only use when content is genuinely optional
+  and browsable, not when you want to make a list of items look impressive.
+- **Animation decoration**: Motion that fires on scroll without serving a conceptual purpose
+  (showing assembly, revealing sequence, indicating change) is decoration. Name it as such
+  and remove it.
+
+## Integration
+
+- **After this skill**: hand the visual brief to `product:mockup` for a wireframe, or
+  directly to an implementer with the brief as the spec.
+- **Before this skill**: `product:ux` to establish user flows, or `product:strategy` to
+  establish what the section is trying to accomplish.
+- **If the stupid-question test fails**: return to Q1. The content type is probably
+  misidentified.

package/skills/product/visual-review/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: visual-review
+description: |
+  Use when auditing visual design for consistency — design system adherence, spacing tokens, typography
+  scale, color palette, component patterns, and responsive polish. Structured checklist + scoring.
+  NOT for UX flows or user research (use ux-review) or accessibility code audits (use product/accessibility).
+portability: portable
+phase_relevance: ["clarify", "design", "review"]
+archetype_relevance: ["*"]
+---
+
+# Visual Review Skill
+
+Systematic, evidence-based visual design analysis. Provides structured checklists and scoring.
+
+## What This Evaluates
+
+### Spacing and Alignment
+
+- Grid system adherence (4px/8px grid)
+- Consistent padding/margin within and between components
+- Alignment: elements on a shared baseline or grid column
+- Gutters and whitespace proportions
+
+### Typography Hierarchy
+
+- Type scale (heading levels, body, caption, label)
+- Font weight usage (bold for emphasis, not decoration)
+- Line height and letter spacing consistency
+- Responsive type scaling
+
+### Color Consistency
+
+- All colors sourced from design tokens or CSS variables
+- No hardcoded hex values outside token definitions
+- Semantic color usage (error = red, success = green, etc.)
+- Dark mode / theme variant coverage
+
+### Component Patterns
+
+- Reuse of existing components before creating new ones
+- Consistent state handling: default, hover, focus, active, disabled, error
+- Variant naming follows design system conventions
+- No one-off component duplications
+
+### Responsive Layout
+
+- Mobile-first breakpoint structure
+- No fixed widths that break at narrow viewports
+- Touch targets ≥44×44px
+- Images and media have max-width constraints
+
+## Review Checklist
+
+| Category | Check | Result |
+|----------|-------|--------|
+| Spacing | 4/8px grid used | ✓ / ⚠ / ✗ |
+| Spacing | No magic number values | ✓ / ⚠ / ✗ |
+| Typography | Heading levels sequential | ✓ / ⚠ / ✗ |
+| Typography | Font stack from tokens | ✓ / ⚠ / ✗ |
+| Color | No hardcoded hex | ✓ / ⚠ / ✗ |
+| Color | Semantic tokens used | ✓ / ⚠ / ✗ |
+| Components | States defined | ✓ / ⚠ / ✗ |
+| Components | No duplicates | ✓ / ⚠ / ✗ |
+| Responsive | Mobile-first media queries | ✓ / ⚠ / ✗ |
+| Responsive | Touch targets sized | ✓ / ⚠ / ✗ |
+
+## Common Violations
+
+```
+Spacing violations:
+  margin: 17px          → margin: var(--space-4)
+  padding: 12px 20px    → padding: var(--space-3) var(--space-5)
+
+Color violations:
+  color: #3b82f6        → color: var(--color-primary)
+  background: #f9fafb   → background: var(--color-surface)
+
+Typography violations:
+  font-size: 13px       → font-size: var(--text-sm)
+  font-weight: 600      → font-weight: var(--font-semibold)
+```
+
+## Scoring
+
+| Score | Meaning |
+|-------|---------|
+| 5 — Ship it | All tokens used, consistent patterns, no violations |
+| 4 — Minor polish | 1–3 minor violations, no systematic issues |
+| 3 — Needs work | Inconsistent token usage, some components non-conforming |
+| 2 — Significant issues | Systematic violations across multiple categories |
+| 1 — Redesign needed | No design system adherence, inconsistent throughout |
+
+## Output Format
+
+```markdown
+## Visual Review: {target}
+
+**Score**: {1–5}
+**Verdict**: {Ship it | Minor polish | Needs work | Significant issues | Redesign}
+
+### Findings by Category
+
+#### Spacing
+- {finding with file:line and fix}
+
+#### Typography
+- {finding with file:line and fix}
+
+#### Color
+- {finding with file:line and fix}
+
+#### Components
+- {finding with file:line and fix}
+
+#### Responsive
+- {finding with file:line and fix}
+
+### Top 3 Fixes
+1. {highest impact fix}
+2. {second fix}
+3. {third fix}
+```
+
+## Integration
+
+- **screenshot skill**: Capture visuals for before/after comparison
+- **accessibility skill**: Color contrast overlaps with a11y
+- **product/ux-review**: For UX flows, user research, and usability evaluation
+- **wicked-garden:search**: `wicked-garden:search "#[0-9a-fA-F]{3,6}"` finds hardcoded colors
+- **imagery/review skill**: For comprehensive image analysis with quality gates (brand, accessibility, production, sensitivity), see the `imagery/review` skill