wicked-garden 12.27.0

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

@@ -0,0 +1,68 @@
+# UX / Design Review Rubric (4 lenses)
+
+Apply this inline. A broad design audit across four lenses: **flows · ui · a11y ·
+research**. Each lens returns a score 1-5 + findings (severity + file:line + impact
++ fix). Scope with `--focus`; `--quick` = critical-only.
+
+> **Dispatch only for `--focus all`.** When all lenses run, dispatch the specialist
+> agents in parallel (ux-designer, ui-reviewer, a11y-expert) — real concurrency on a
+> large surface earns the hop. The research lens is folded into the ux-designer
+> dispatch (same artifact + reviewer skill). For a single `--focus`, apply that lens's
+> rubric inline; do not dispatch.
+
+Auto-detect focus when absent: `.tsx/.jsx/.vue` -> flows+ui+a11y; `.css/.scss` ->
+ui; requirements `.md` -> research; directory -> all.
+
+## Lens: flows (ux-designer)
+
+Evaluate flow clarity, error/empty/loading states, interaction patterns, IA.
+Happy path <=7 steps; every decision mapped; recovery on errors; back nav at every
+step; confirmation on destructive actions. Nielsen's 10 heuristics. (Full rubric:
+`refs/ux.md`.)
+
+## Lens: ui (ui-reviewer)
+
+Establish the design-system baseline (tokens file, component library, grid). Then:
+- **Consistency**: color palette, typography scale, spacing (4px/8px grid), radius,
+  elevation, icon style.
+- **Component patterns**: button variants; input states (default/focus/error/disabled);
+  card/modal/list patterns.
+- **Code violations**: hardcoded hex outside token files, magic-number spacing
+  (`12px`/`15px`), inline styles, duplicate components, missing interactive states.
+- **Responsive**: mobile-first breakpoints (~640/768/1024/1280), no fixed widths that
+  break narrow, touch targets >=44x44px, fluid sizing (clamp/min/max).
+- **Polish**: transitions (200-300ms), loading skeletons, empty/error styling, overflow/truncation.
+
+Score 1-5; verdict Ship it / Minor polish / Needs work / Significant issues.
+
+## Lens: a11y (a11y-expert)
+
+Audit WCAG 2.1 AA via POUR: semantic HTML, ARIA, keyboard reachability + order,
+screen-reader announcements, contrast (4.5:1 / 3:1), visible focus. Report WCAG
+level + issues with criterion + fix. (Full rubric: `refs/a11y.md`.)
+
+## Lens: research (folded into ux-designer)
+
+Assess personas (evidence-based, 3-5 distinct), user journeys (phases, pain points,
+opportunities), Jobs-to-be-Done (`When {situation}, I want {motivation}, so I can
+{outcome}`), and validation status (Validated / Assumed / Unknown). Return a gap list.
+
+## Output
+
+```markdown
+## UX/Design Review: {target}   (focus: {flows|ui|a11y|research|all})
+
+| Lens | Score 1-5 | Verdict |
+|------|-----------|---------|
+| Flows | {n} | {…} |
+| UI | {n} | {…} |
+| A11y | {n} | {WCAG level} |
+| Research | {n} | {…} |
+
+### Findings (by severity)
+#### Critical — {issue} — {file:line} — Impact: {who} — Fix: {change}
+#### Major / Minor — …
+
+### Top Fixes
+1. … 2. … 3. …
+```

package/skills/product/refs/ux.md

@@ -0,0 +1,101 @@
+# UX Flow Design + Analysis Rubric
+
+Apply this inline. Design (`create`) or evaluate (`analyze`) user flows, interaction
+patterns, and information architecture — in-chat, no design tool. For research
+synthesis / journey maps grounded in study data, see the `ux-flow` skill
+(`skills/product/ux-flow/`).
+
+## Mode
+
+- **create** — generate flows from a requirement/description.
+- **analyze** — evaluate existing flows in code or a document.
+- Auto-detect: description string (no path) -> create; file/dir path -> analyze.
+
+## Create mode
+
+1. **Extract user goals** — what is the user accomplishing?
+2. **Identify entry points** — how do they arrive?
+3. **Map the happy path** — minimum steps to goal (<=7, Miller's Law).
+4. **Define decision points** — where flows branch.
+5. **Handle edge cases** — empty, error, loading, cancel states.
+6. **Document IA** — where this fits in the broader navigation.
+
+## Analyze mode
+
+1. **Trace the happy path** — is it clear and short?
+2. **Find dead ends** — any branch with no recovery?
+3. **Check error handling** — every failure has a user-facing message?
+4. **Validate back navigation** — can users always go back?
+5. **Assess cognitive load** — too many decisions at once?
+6. Score against the flow checklist + Nielsen heuristics.
+
+## Flow checklist
+
+- [ ] Happy path <=7 steps
+- [ ] Every decision has all outcomes mapped
+- [ ] Error states have recovery paths (not dead ends)
+- [ ] Back navigation available at every step
+- [ ] Confirmation on destructive actions
+- [ ] Progress indicators on 3+ step flows
+- [ ] Empty + loading states defined
+
+## Nielsen's 10 heuristics (audit)
+
+1. Visibility of system status · 2. Match system ↔ real world · 3. User control
+and freedom · 4. Consistency and standards · 5. Error prevention · 6. Recognition
+over recall · 7. Flexibility and efficiency · 8. Aesthetic and minimalist design ·
+9. Help users recognize/diagnose/recover from errors · 10. Help and documentation.
+
+## Interaction pattern guidance
+
+| Pattern | Use when |
+|---------|----------|
+| Modal | Focused action without losing page context |
+| Slide-over | Editing a list item |
+| Inline edit | Single-field quick edit |
+| Wizard | Complex multi-step with dependencies |
+| Accordion | Progressive disclosure for dense content |
+| Tab | Peer-level content switching |
+
+## Diagram formats
+
+ASCII (quick) or Mermaid `flowchart TD`. IA as a tree (`App / Public / Authenticated`).
+
+```
+[Entry] -> [Step 1] -> {Decision?}
+                        /         \
+                      Yes          No
+                       v            v
+                   [Step 2]    [Alt Path]
+                       v
+                   [Success]
+```
+
+## Output
+
+```markdown
+## UX {Flow | Review}: {feature or component}
+
+### Information Architecture
+{IA tree}
+
+### User Flow
+{ASCII or Mermaid diagram}
+
+### Step-by-Step Walkthrough
+1. {step} -> {system response}
+
+### Edge Cases
+- Empty: {what shows}  · Error: {what shows + recovery}  · Loading: {feedback}
+
+### Issues Found
+#### Critical — {issue} — Impact: {who} — Recommendation: {fix}
+#### Major — {friction} — Recommendation: {improvement}
+#### Minor — {polish}
+
+### Open Questions
+- {question for product/stakeholder}
+
+### Recommendations
+1. {priority action}  2. {pattern suggestion}
+```

package/skills/product/requirements-analysis/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: requirements-analysis
+description: |
+  Use when turning a vague idea or stakeholder ask into structured user stories with acceptance criteria
+  and a requirements graph. For complexity >= 3 or compliance projects, defaults to graph mode.
+  NOT for navigating an existing requirements graph (use requirements-navigate) or stakeholder alignment (use product:align).
+phase_relevance: ["clarify", "design", "review"]
+archetype_relevance: ["*"]
+---
+
+# Requirements Analysis Skill
+
+Structured requirements elicitation from discovery through documentation.
+
+> **Default: Graph mode.** For complexity >= 3 or compliance projects, produce
+> a `requirements/` graph (see `requirements-graph` skill) instead of a
+> monolithic document. Use `--monolith` to force the legacy single-file format.
+> See: `requirements-graph/SKILL.md` for graph layout and schema.
+> See: `requirements-navigate/SKILL.md` for querying and maintaining the graph.
+
+## Process
+
+### 1. Context Gathering
+- Read project brief, outcome.md, or requirements
+- Identify existing documentation
+- Note assumptions and constraints
+
+### 2. Stakeholder Identification
+- Who are the users/personas?
+- Who are secondary stakeholders?
+- Who has decision authority?
+
+### 3. Requirements Elicitation
+
+Ask the 5 W's:
+- **Who**: Which users/personas?
+- **What**: What capabilities needed?
+- **When**: What triggers the need?
+- **Where**: What context/environment?
+- **Why**: What value/benefit?
+
+### 4. User Story Definition
+
+Format: **As a [persona], I want [capability], so that [benefit]**
+
+Quality criteria:
+- Specific persona identified
+- Capability clearly stated
+- Benefit/value articulated
+- Testable outcome
+
+### 5. Acceptance Criteria
+
+For each story:
+```
+Given [context/precondition]
+When [action/event]
+Then [expected outcome]
+```
+
+Include:
+- Happy path scenarios
+- Error conditions
+- Edge cases
+- Non-functional requirements
+
+### 6. Validation
+
+Check:
+- [ ] All stories have persona, capability, benefit
+- [ ] Acceptance criteria are testable
+- [ ] Edge cases identified
+- [ ] Dependencies mapped
+- [ ] Ambiguities flagged
+
+## User Story Template
+
+```markdown
+### US{N}: {Story Title}
+
+**As a** {specific persona}
+**I want** {specific capability}
+**So that** {specific benefit}
+
+**Priority**: {P0/P1/P2}
+**Complexity**: {S/M/L/XL}
+
+**Acceptance Criteria**:
+1. Given {context}, When {action}, Then {outcome}
+2. Given {error condition}, When {action}, Then {error handling}
+3. Given {edge case}, When {action}, Then {graceful handling}
+
+**Non-Functional**:
+- Performance: {requirement}
+- Security: {requirement}
+- Usability: {requirement}
+
+**Dependencies**: {Other stories or systems}
+**Assumptions**: {What we're assuming}
+**Open Questions**: {What needs clarification}
+```
+
+## Common Patterns
+
+**CRUD Operations**:
+- Create: As a user, I want to create X, so that I can track Y
+- Read: As a user, I want to view X, so that I can understand Y
+- Update: As a user, I want to edit X, so that I can correct Y
+- Delete: As a user, I want to remove X, so that I can clean up Y
+
+**Authentication/Authorization**:
+- Login, logout, password reset
+- Role-based access control
+- Session management
+
+**Data Validation**:
+- Input validation
+- Error messaging
+- Constraint enforcement
+
+## Integration with Tools
+
+```bash
+# Search for similar requirements (FTS5 over indexed docs + wiki)
+wicked-brain:search "user story"
+
+# Store requirements on the active clarify task via native TaskUpdate
+# TaskUpdate(taskId="{task_id}", description="{previous}\n\n## Requirements\n{user_stories}")
+
+# Recall past patterns
+Skill(skill="wicked-brain:memory", args="recall \"requirements for {feature_type}\"")
+```
+
+## Output Format
+
+See: `refs/requirements-output-format-template.md`, `refs/requirements-example-auth.md`, and `refs/requirements-example-export-integration.md`

package/skills/product/requirements-analysis/refs/requirements-example-auth.md

@@ -0,0 +1,264 @@
+---
+phase_relevance: ["clarify", "design", "review"]
+archetype_relevance: ["*"]
+---
+# Requirements Output: Authentication Example
+
+Full domain-specific example of requirements analysis output for an authentication feature.
+
+## Example: Authentication Feature
+
+```markdown
+# Requirements Analysis: User Authentication System
+
+**Date**: 2026-01-24
+**Analyzed By**: Product Team
+**Stakeholders**: Engineering, QE, Security, Customer Success
+**Status**: Review
+
+## Executive Summary
+
+Build a secure authentication system supporting email/password login with password reset capabilities. Enables customers to create accounts, securely access their data, and manage credentials.
+
+## Context
+
+### Business Goals
+- Enable user account creation for personalized experiences
+- Meet security compliance requirements (SOC2)
+- Reduce support tickets related to access issues
+
+### User Needs
+- Quick account creation
+- Secure login
+- Easy password recovery
+- Persistent sessions
+
+### Constraints
+- Must launch within 6 weeks
+- Integrate with existing user database schema
+- GDPR compliance required for EU users
+
+## Personas
+
+### New Customer
+- **Role**: First-time visitor wanting to create account
+- **Goals**: Quickly sign up and access features
+- **Pain Points**: Forgot password, complex registration flows
+- **Technical Proficiency**: Low to Medium
+
+### Returning Customer
+- **Role**: Existing user returning to service
+- **Goals**: Quick, secure access to account
+- **Pain Points**: Remembering credentials, account lockouts
+- **Technical Proficiency**: Medium
+
+### Support Agent
+- **Role**: Customer support helping with access issues
+- **Goals**: Quickly help users regain access
+- **Pain Points**: Unable to reset passwords, no visibility into account status
+- **Technical Proficiency**: High
+
+## User Stories
+
+### US-AUTH-001: User Registration
+
+**As a** new customer
+**I want to** register with email and password
+**So that** I can create an account and save my preferences
+
+**Priority**: P0
+**Complexity**: M
+
+**Acceptance Criteria**:
+1. Given valid email and password (8+ chars), When I submit registration, Then account created
+2. Given email already registered, When I submit, Then error "Email already in use"
+3. Given weak password (<8 chars), When I submit, Then error with strength requirements
+4. Given successful registration, When account created, Then confirmation email sent
+
+**Dependencies**: Email service integration
+**Assumptions**: Email verification required before full access
+**Open Questions**:
+- [ ] Support social login (Google, GitHub)?
+- [ ] Password strength requirements (special chars, numbers)?
+
+### US-AUTH-002: User Login
+
+**As a** returning customer
+**I want to** log in with email and password
+**So that** I can access my account and data
+
+**Priority**: P0
+**Complexity**: S
+
+**Acceptance Criteria**:
+1. Given valid credentials, When I submit login, Then redirected to dashboard
+2. Given invalid password, When I submit, Then error "Invalid email or password"
+3. Given account locked, When I submit, Then error "Account locked. Reset password."
+4. Given successful login, When I close browser and return within 24h, Then still logged in
+
+**Dependencies**: Session management
+**Assumptions**: Sessions expire after 24 hours of inactivity
+**Open Questions**:
+- [ ] "Remember me" functionality?
+- [ ] Multi-device session limits?
+
+### US-AUTH-003: Password Reset
+
+**As a** customer who forgot password
+**I want to** reset my password via email
+**So that** I can regain access to my account
+
+**Priority**: P0
+**Complexity**: M
+
+**Acceptance Criteria**:
+1. Given registered email, When I request reset, Then reset link sent to email
+2. Given valid reset link, When I submit new password, Then password updated
+3. Given expired reset link (>24h), When I try to reset, Then error "Link expired"
+4. Given non-existent email, When I request reset, Then generic success message (no disclosure)
+
+**Dependencies**: Email service, token generation
+**Assumptions**: Reset links expire after 24 hours
+**Open Questions**:
+- [ ] Security questions as alternative?
+- [ ] SMS-based reset option?
+
+## Functional Requirements
+
+### Authentication
+1. **REQ-AUTH-001**: Support email/password authentication
+   - **Rationale**: Primary authentication method
+   - **Acceptance**: User can register and login
+   - **Priority**: P0
+
+2. **REQ-AUTH-002**: Hash passwords with bcrypt (cost factor 12)
+   - **Rationale**: Security best practice
+   - **Acceptance**: Passwords never stored in plaintext
+   - **Priority**: P0
+
+3. **REQ-AUTH-003**: Lock account after 3 failed login attempts
+   - **Rationale**: Prevent brute force attacks
+   - **Acceptance**: Account locked, only unlockable via password reset
+   - **Priority**: P1
+
+### Session Management
+1. **REQ-SESS-001**: Sessions expire after 24 hours of inactivity
+   - **Rationale**: Balance security and convenience
+   - **Acceptance**: User logged out after 24h inactive
+   - **Priority**: P1
+
+2. **REQ-SESS-002**: Support session persistence across browser restarts
+   - **Rationale**: User convenience
+   - **Acceptance**: User stays logged in if within 24h window
+   - **Priority**: P2
+
+## Non-Functional Requirements
+
+### Performance
+- **REQ-PERF-001**: Login response time <500ms (95th percentile)
+  - Target: Fast, responsive login
+  - Measured by: Application performance monitoring
+
+### Security
+- **REQ-SEC-001**: All authentication endpoints must use HTTPS
+  - Compliance: SOC2, GDPR
+  - Verification: SSL/TLS enforcement
+
+- **REQ-SEC-002**: Password reset tokens must be single-use
+  - Compliance: Security best practice
+  - Verification: Token invalidated after use
+
+- **REQ-SEC-003**: Log all authentication events (login, logout, failed attempts)
+  - Compliance: Audit requirements
+  - Verification: Events logged to security audit trail
+
+### Usability
+- **REQ-UX-001**: Error messages must not disclose whether email is registered
+  - Standard: Security best practice (prevent enumeration)
+  - Verification: Consistent messaging for valid/invalid emails
+
+- **REQ-UX-002**: Mobile-responsive login/registration forms
+  - Standard: Mobile-first design
+  - Verification: Forms usable on 320px+ screens
+
+## Scope Definition
+
+### In Scope
+- Email/password registration
+- Email/password login
+- Password reset via email
+- Session management
+- Account lockout after failed attempts
+
+### Out of Scope
+- Social login (Google, GitHub) - future consideration
+- Two-factor authentication (2FA) - future consideration
+- SSO/SAML integration - future consideration
+- Password strength meter UI - nice-to-have
+- Biometric authentication - future consideration
+
+### Future Considerations
+- 2FA for high-security accounts
+- OAuth2 integration for third-party apps
+- Passwordless authentication (magic links)
+
+## Dependencies
+
+### Internal
+- Email service for verification and reset emails
+- Database schema updates for user table
+- Frontend team for login/registration UI
+
+### External
+- Email delivery service (SendGrid/SES)
+- Session storage (Redis or database)
+
+## Assumptions
+
+1. Email service is reliable with >99% delivery rate
+2. Users have access to email for verification
+3. Existing user table can be extended for auth fields
+4. 24-hour session timeout is acceptable for users
+
+## Risks
+
+| Risk | Impact | Probability | Mitigation |
+|------|--------|-------------|------------|
+| Email delivery failures | High | Medium | Implement retry logic, provide alternative contact |
+| Credential stuffing attacks | High | Medium | Account lockout, rate limiting, monitoring |
+| Password reset token leakage | High | Low | Short expiry, single-use tokens, secure transport |
+| Poor mobile UX | Medium | Medium | Responsive design, user testing |
+
+## Open Questions
+
+- [ ] Should we support "remember me" functionality?
+- [ ] What password complexity requirements? (special chars, numbers, length)
+- [ ] Support social login in this phase or defer?
+- [ ] Multi-device session limits (e.g., max 5 active sessions)?
+- [ ] Account deletion/deactivation flow needed?
+
+## Traceability
+
+- **Source Document**: outcome.md
+- **Design Phase**: phases/design/auth-architecture.md
+- **Test Scenarios**: phases/qe/auth-test-scenarios.md
+- **Tasks**: Native tasks with `metadata.initiative="auth"`
+- **Memory**: Tags: auth, security, user-management
+
+## Appendices
+
+### A. Glossary
+- **Session**: Server-side authentication state
+- **Token**: Single-use, time-limited credential for password reset
+- **Account Lockout**: Temporary disabling of account after failed login attempts
+
+### B. References
+- [OWASP Authentication Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Authentication_Cheat_Sheet.html)
+- [SOC2 Authentication Requirements](https://example.com)
+- [GDPR User Data Guidelines](https://example.com)
+
+### C. Revision History
+| Date | Author | Changes |
+|------|--------|---------|
+| 2026-01-24 | Product Team | Initial draft |
+```

package/skills/product/requirements-analysis/refs/requirements-example-export-integration.md

@@ -0,0 +1,88 @@
+---
+phase_relevance: ["clarify", "design", "review"]
+archetype_relevance: ["*"]
+---
+# Requirements Output: Minimal Example & Integration Points
+
+Minimal format example and integration points for requirements analysis output.
+
+## Example: Data Export Feature (Minimal Format)
+
+```markdown
+# Requirements: CSV Export for Reports
+
+## Summary
+Enable managers to export report data to CSV for offline analysis in Excel.
+
+## User Stories
+
+### US-EXPORT-001: Export Report Data
+
+**As a** manager
+**I want to** export report data to CSV
+**So that** I can analyze trends offline in Excel
+
+**Priority**: P1
+**Complexity**: M
+
+**Acceptance Criteria**:
+1. Given report data exists, When I click export, Then CSV downloads with all data
+2. Given large dataset (10k+ rows), When I export, Then async job with email notification
+3. Given no data in report, When I click export, Then message "No data to export"
+4. Given CSV contains special characters, When I export, Then properly escaped for Excel
+
+### US-EXPORT-002: Custom Date Range Export
+
+**As a** manager
+**I want to** select date range for export
+**So that** I can focus on specific time periods
+
+**Priority**: P2
+**Complexity**: S
+
+**Acceptance Criteria**:
+1. Given date range selected, When I export, Then only data in range included
+2. Given invalid date range (start > end), When I try export, Then validation error
+
+## Out of Scope
+- PDF export format
+- Scheduled/recurring exports
+- Custom column selection
+- Multiple file format options (Excel, JSON, XML)
+
+## Open Questions
+- [ ] Max row limit for synchronous export? (suggest 10k)
+- [ ] Column headers customizable?
+- [ ] Include metadata (export date, user, filters)?
+```
+
+## Integration Points
+
+### With native tasks
+Store requirements as native tasks:
+```
+TaskCreate(
+  subject="US-AUTH-001",
+  description="$(cat requirements.md)",
+  metadata={
+    "event_type": "task",
+    "chain_id": "auth.clarify",
+    "source_agent": "requirements-analyst",
+    "phase": "clarify",
+    "priority": "P0",
+    "initiative": "auth"
+  }
+)
+```
+
+### With wicked-brain:memory
+Store for pattern recall:
+```
+Skill(skill="wicked-brain:memory", args="store \"auth-requirements-2026\" \"$(cat requirements.md)\"")
+```
+
+### With Wicked QE
+Requirements feed test scenarios:
+```
+Requirements -> User Stories -> Acceptance Criteria -> Test Scenarios
+```