wizz-method 1.4.1 → 1.5.0

package/src/skills-lib/form-cro/SKILL.md

@@ -16,399 +16,23 @@ If `.agents/product-marketing-context.md` exists (or `.claude/product-marketing-
 
 Before providing recommendations, identify:
 
-1. **Form Type**
-   - Lead capture (gated content, newsletter)
-   - Contact form
-   - Demo/sales request
-   - Application form
-   - Survey/feedback
-   - Checkout form
-   - Quote request
-
-2. **Current State**
-   - How many fields?
-   - What's the current completion rate?
-   - Mobile vs. desktop split?
-   - Where do users abandon?
-
-3. **Business Context**
-   - What happens with form submissions?
-   - Which fields are actually used in follow-up?
-   - Are there compliance/legal requirements?
-
----
+1. **Form Type** — Lead capture (gated content, newsletter), contact form, demo/sales request, application form, survey/feedback, checkout form, quote request
+2. **Current State** — How many fields? What's the current completion rate? Mobile vs. desktop split? Where do users abandon?
+3. **Business Context** — What happens with form submissions? Which fields are actually used in follow-up? Are there compliance/legal requirements?
 
 ## Core Principles
 
-### 1. Every Field Has a Cost
-Each field reduces completion rate. Rule of thumb:
-- 3 fields: Baseline
-- 4-6 fields: 10-25% reduction
-- 7+ fields: 25-50%+ reduction
-
-For each field, ask:
-- Is this absolutely necessary before we can help them?
-- Can we get this information another way?
-- Can we ask this later?
-
-### 2. Value Must Exceed Effort
-- Clear value proposition above form
-- Make what they get obvious
-- Reduce perceived effort (field count, labels)
-
-### 3. Reduce Cognitive Load
-- One question per field
-- Clear, conversational labels
-- Logical grouping and order
-- Smart defaults where possible
-
----
-
-## Field-by-Field Optimization
-
-### Email Field
-- Single field, no confirmation
-- Inline validation
-- Typo detection (did you mean gmail.com?)
-- Proper mobile keyboard
-
-### Name Fields
-- Single "Name" vs. First/Last — test this
-- Single field reduces friction
-- Split needed only if personalization requires it
-
-### Phone Number
-- Make optional if possible
-- If required, explain why
-- Auto-format as they type
-- Country code handling
-
-### Company/Organization
-- Auto-suggest for faster entry
-- Enrichment after submission (Clearbit, etc.)
-- Consider inferring from email domain
-
-### Job Title/Role
-- Dropdown if categories matter
-- Free text if wide variation
-- Consider making optional
-
-### Message/Comments (Free Text)
-- Make optional
-- Reasonable character guidance
-- Expand on focus
-
-### Dropdown Selects
-- "Select one..." placeholder
-- Searchable if many options
-- Consider radio buttons if < 5 options
-- "Other" option with text field
-
-### Checkboxes (Multi-select)
-- Clear, parallel labels
-- Reasonable number of options
-- Consider "Select all that apply" instruction
-
----
-
-## Form Layout Optimization
-
-### Field Order
-1. Start with easiest fields (name, email)
-2. Build commitment before asking more
-3. Sensitive fields last (phone, company size)
-4. Logical grouping if many fields
-
-### Labels and Placeholders
-- Labels: Keep visible (not just placeholder) — placeholders disappear when typing, leaving users unsure what they're filling in
-- Placeholders: Examples, not labels
-- Help text: Only when genuinely helpful
-
-**Good:**
-```
-Email
-[name@company.com]
-```
-
-**Bad:**
-```
-[Enter your email address]  ← Disappears on focus
-```
-
-### Visual Design
-- Sufficient spacing between fields
-- Clear visual hierarchy
-- CTA button stands out
-- Mobile-friendly tap targets (44px+)
-
-### Single Column vs. Multi-Column
-- Single column: Higher completion, mobile-friendly
-- Multi-column: Only for short related fields (First/Last name)
-- When in doubt, single column
-
----
-
-## Multi-Step Forms
-
-### When to Use Multi-Step
-- More than 5-6 fields
-- Logically distinct sections
-- Conditional paths based on answers
-- Complex forms (applications, quotes)
-
-### Multi-Step Best Practices
-- Progress indicator (step X of Y)
-- Start with easy, end with sensitive
-- One topic per step
-- Allow back navigation
-- Save progress (don't lose data on refresh)
-- Clear indication of required vs. optional
-
-### Progressive Commitment Pattern
-1. Low-friction start (just email)
-2. More detail (name, company)
-3. Qualifying questions
-4. Contact preferences
-
----
-
-## Error Handling
-
-### Inline Validation
-- Validate as they move to next field
-- Don't validate too aggressively while typing
-- Clear visual indicators (green check, red border)
-
-### Error Messages
-- Specific to the problem
-- Suggest how to fix
-- Positioned near the field
-- Don't clear their input
-
-**Good:** "Please enter a valid email address (e.g., name@company.com)"
-**Bad:** "Invalid input"
-
-### On Submit
-- Focus on first error field
-- Summarize errors if multiple
-- Preserve all entered data
-- Don't clear form on error
-
----
-
-## Submit Button Optimization
-
-### Button Copy
-Weak: "Submit" | "Send"
-Strong: "[Action] + [What they get]"
-
-Examples:
-- "Get My Free Quote"
-- "Download the Guide"
-- "Request Demo"
-- "Send Message"
-- "Start Free Trial"
-
-### Button Placement
-- Immediately after last field
-- Left-aligned with fields
-- Sufficient size and contrast
-- Mobile: Sticky or clearly visible
-
-### Post-Submit States
-- Loading state (disable button, show spinner)
-- Success confirmation (clear next steps)
-- Error handling (clear message, focus on issue)
-
----
-
-## Trust and Friction Reduction
-
-### Near the Form
-- Privacy statement: "We'll never share your info"
-- Security badges if collecting sensitive data
-- Testimonial or social proof
-- Expected response time
+1. **Every Field Has a Cost** — 3 fields is baseline, 4-6 fields costs 10-25% completion, 7+ fields costs 25-50%+. For each field ask: is it necessary before we can help them, can we get it another way, can we ask it later?
+2. **Value Must Exceed Effort** — clear value proposition above the form, make what they get obvious, reduce perceived effort (field count, labels).
+3. **Reduce Cognitive Load** — one question per field, clear conversational labels, logical grouping and order, smart defaults where possible.
 
-### Reducing Perceived Effort
-- "Takes 30 seconds"
-- Field count indicator
-- Remove visual clutter
-- Generous white space
+## References (load on demand)
 
-### Addressing Objections
-- "No spam, unsubscribe anytime"
-- "We won't share your number"
-- "No credit card required"
-
----
-
-## Form Types: Specific Guidance
-
-### Lead Capture (Gated Content)
-- Minimum viable fields (often just email)
-- Clear value proposition for what they get
-- Consider asking enrichment questions post-download
-- Test email-only vs. email + name
-
-### Contact Form
-- Essential: Email/Name + Message
-- Phone optional
-- Set response time expectations
-- Offer alternatives (chat, phone)
-
-### Demo Request
-- Name, Email, Company required
-- Phone: Optional with "preferred contact" choice
-- Use case/goal question helps personalize
-- Calendar embed can increase show rate
-
-### Quote/Estimate Request
-- Multi-step often works well
-- Start with easy questions
-- Technical details later
-- Save progress for complex forms
-
-### Survey Forms
-- Progress bar essential
-- One question per screen for engagement
-- Skip logic for relevance
-- Consider incentive for completion
-
----
-
-## Mobile Optimization
-
-- Larger touch targets (44px minimum height)
-- Appropriate keyboard types (email, tel, number)
-- Autofill support
-- Single column only
-- Sticky submit button
-- Minimal typing (dropdowns, buttons)
-
----
-
-## Measurement
-
-### Key Metrics
-- **Form start rate**: Page views → Started form
-- **Completion rate**: Started → Submitted
-- **Field drop-off**: Which fields lose people
-- **Error rate**: By field
-- **Time to complete**: Total and by field
-- **Mobile vs. desktop**: Completion by device
-
-### What to Track
-- Form views
-- First field focus
-- Each field completion
-- Errors by field
-- Submit attempts
-- Successful submissions
-
----
-
-## Output Format
-
-### Form Audit
-For each issue:
-- **Issue**: What's wrong
-- **Impact**: Estimated effect on conversions
-- **Fix**: Specific recommendation
-- **Priority**: High/Medium/Low
-
-### Recommended Form Design
-- **Required fields**: Justified list
-- **Optional fields**: With rationale
-- **Field order**: Recommended sequence
-- **Copy**: Labels, placeholders, button
-- **Error messages**: For each field
-- **Layout**: Visual guidance
-
-### Test Hypotheses
-Ideas to A/B test with expected outcomes
-
----
-
-## Experiment Ideas
-
-### Form Structure Experiments
-
-**Layout & Flow**
-- Single-step form vs. multi-step with progress bar
-- 1-column vs. 2-column field layout
-- Form embedded on page vs. separate page
-- Vertical vs. horizontal field alignment
-- Form above fold vs. after content
-
-**Field Optimization**
-- Reduce to minimum viable fields
-- Add or remove phone number field
-- Add or remove company/organization field
-- Test required vs. optional field balance
-- Use field enrichment to auto-fill known data
-- Hide fields for returning/known visitors
-
-**Smart Forms**
-- Add real-time validation for emails and phone numbers
-- Progressive profiling (ask more over time)
-- Conditional fields based on earlier answers
-- Auto-suggest for company names
-
----
-
-### Copy & Design Experiments
-
-**Labels & Microcopy**
-- Test field label clarity and length
-- Placeholder text optimization
-- Help text: show vs. hide vs. on-hover
-- Error message tone (friendly vs. direct)
-
-**CTAs & Buttons**
-- Button text variations ("Submit" vs. "Get My Quote" vs. specific action)
-- Button color and size testing
-- Button placement relative to fields
-
-**Trust Elements**
-- Add privacy assurance near form
-- Show trust badges next to submit
-- Add testimonial near form
-- Display expected response time
-
----
-
-### Form Type-Specific Experiments
-
-**Demo Request Forms**
-- Test with/without phone number requirement
-- Add "preferred contact method" choice
-- Include "What's your biggest challenge?" question
-- Test calendar embed vs. form submission
-
-**Lead Capture Forms**
-- Email-only vs. email + name
-- Test value proposition messaging above form
-- Gated vs. ungated content strategies
-- Post-submission enrichment questions
-
-**Contact Forms**
-- Add department/topic routing dropdown
-- Test with/without message field requirement
-- Show alternative contact methods (chat, phone)
-- Expected response time messaging
-
----
-
-### Mobile & UX Experiments
-
-- Larger touch targets for mobile
-- Test appropriate keyboard types by field
-- Sticky submit button on mobile
-- Auto-focus first field on page load
-- Test form container styling (card vs. minimal)
-
----
+- `references/field-optimization.md` — field-by-field guidance (email, name, phone, company, job title, free text, dropdowns, checkboxes), field order, labels vs. placeholders, visual design, single- vs. multi-column, and mobile optimization. Load when deciding which fields to keep/cut and how to lay them out.
+- `references/flow-and-errors.md` — when/how to use multi-step forms (progressive commitment pattern), inline validation, error message copy, and submit button copy/placement/post-submit states. Load when designing the flow, validation, or the submit button.
+- `references/trust-and-form-types.md` — trust and friction-reduction copy near the form, plus specific guidance per form type (lead capture, contact, demo request, quote/estimate, survey). Load when the form is a known type or needs trust copy.
+- `references/measurement-output.md` — key metrics/benchmarks to track and the output format for a form audit or recommended design. Load when instrumenting the form or formatting the deliverable.
+- `references/experiments.md` — a full experiment backlog (structure, copy/design, form-type-specific, mobile) for A/B testing. Load when the deliverable needs a test plan.
 
 ## Task-Specific Questions
 
@@ -419,8 +43,6 @@ Ideas to A/B test with expected outcomes
 5. Are there compliance/legal requirements?
 6. What's the mobile vs. desktop split?
 
----
-
 ## Related Skills
 
 - **signup-flow-cro**: For account creation forms

package/src/skills-lib/form-cro/references/experiments.md

@@ -0,0 +1,73 @@
+# Experiment Ideas
+
+Load this file when the deliverable includes a test plan / A/B test backlog for a form.
+
+## Form Structure Experiments
+
+**Layout & Flow**
+- Single-step form vs. multi-step with progress bar
+- 1-column vs. 2-column field layout
+- Form embedded on page vs. separate page
+- Vertical vs. horizontal field alignment
+- Form above fold vs. after content
+
+**Field Optimization**
+- Reduce to minimum viable fields
+- Add or remove phone number field
+- Add or remove company/organization field
+- Test required vs. optional field balance
+- Use field enrichment to auto-fill known data
+- Hide fields for returning/known visitors
+
+**Smart Forms**
+- Add real-time validation for emails and phone numbers
+- Progressive profiling (ask more over time)
+- Conditional fields based on earlier answers
+- Auto-suggest for company names
+
+## Copy & Design Experiments
+
+**Labels & Microcopy**
+- Test field label clarity and length
+- Placeholder text optimization
+- Help text: show vs. hide vs. on-hover
+- Error message tone (friendly vs. direct)
+
+**CTAs & Buttons**
+- Button text variations ("Submit" vs. "Get My Quote" vs. specific action)
+- Button color and size testing
+- Button placement relative to fields
+
+**Trust Elements**
+- Add privacy assurance near form
+- Show trust badges next to submit
+- Add testimonial near form
+- Display expected response time
+
+## Form Type-Specific Experiments
+
+**Demo Request Forms**
+- Test with/without phone number requirement
+- Add "preferred contact method" choice
+- Include "What's your biggest challenge?" question
+- Test calendar embed vs. form submission
+
+**Lead Capture Forms**
+- Email-only vs. email + name
+- Test value proposition messaging above form
+- Gated vs. ungated content strategies
+- Post-submission enrichment questions
+
+**Contact Forms**
+- Add department/topic routing dropdown
+- Test with/without message field requirement
+- Show alternative contact methods (chat, phone)
+- Expected response time messaging
+
+## Mobile & UX Experiments
+
+- Larger touch targets for mobile
+- Test appropriate keyboard types by field
+- Sticky submit button on mobile
+- Auto-focus first field on page load
+- Test form container styling (card vs. minimal)

package/src/skills-lib/form-cro/references/field-optimization.md

@@ -0,0 +1,92 @@
+# Field-by-Field, Layout, and Mobile Optimization
+
+Load this file when deciding which fields to keep/cut, how to lay them out, and how to adapt the form for mobile.
+
+## Field-by-Field Optimization
+
+### Email Field
+- Single field, no confirmation
+- Inline validation
+- Typo detection (did you mean gmail.com?)
+- Proper mobile keyboard
+
+### Name Fields
+- Single "Name" vs. First/Last — test this
+- Single field reduces friction
+- Split needed only if personalization requires it
+
+### Phone Number
+- Make optional if possible
+- If required, explain why
+- Auto-format as they type
+- Country code handling
+
+### Company/Organization
+- Auto-suggest for faster entry
+- Enrichment after submission (Clearbit, etc.)
+- Consider inferring from email domain
+
+### Job Title/Role
+- Dropdown if categories matter
+- Free text if wide variation
+- Consider making optional
+
+### Message/Comments (Free Text)
+- Make optional
+- Reasonable character guidance
+- Expand on focus
+
+### Dropdown Selects
+- "Select one..." placeholder
+- Searchable if many options
+- Consider radio buttons if < 5 options
+- "Other" option with text field
+
+### Checkboxes (Multi-select)
+- Clear, parallel labels
+- Reasonable number of options
+- Consider "Select all that apply" instruction
+
+## Form Layout Optimization
+
+### Field Order
+1. Start with easiest fields (name, email)
+2. Build commitment before asking more
+3. Sensitive fields last (phone, company size)
+4. Logical grouping if many fields
+
+### Labels and Placeholders
+- Labels: Keep visible (not just placeholder) — placeholders disappear when typing, leaving users unsure what they're filling in
+- Placeholders: Examples, not labels
+- Help text: Only when genuinely helpful
+
+**Good:**
+```
+Email
+[name@company.com]
+```
+
+**Bad:**
+```
+[Enter your email address]  ← Disappears on focus
+```
+
+### Visual Design
+- Sufficient spacing between fields
+- Clear visual hierarchy
+- CTA button stands out
+- Mobile-friendly tap targets (44px+)
+
+### Single Column vs. Multi-Column
+- Single column: Higher completion, mobile-friendly
+- Multi-column: Only for short related fields (First/Last name)
+- When in doubt, single column
+
+## Mobile Optimization
+
+- Larger touch targets (44px minimum height)
+- Appropriate keyboard types (email, tel, number)
+- Autofill support
+- Single column only
+- Sticky submit button
+- Minimal typing (dropdowns, buttons)

package/src/skills-lib/form-cro/references/flow-and-errors.md

@@ -0,0 +1,71 @@
+# Multi-Step Flow, Error Handling, and Submit Button
+
+Load this file when the form needs multiple steps, or when designing validation/error states and the submit button.
+
+## Multi-Step Forms
+
+### When to Use Multi-Step
+- More than 5-6 fields
+- Logically distinct sections
+- Conditional paths based on answers
+- Complex forms (applications, quotes)
+
+### Multi-Step Best Practices
+- Progress indicator (step X of Y)
+- Start with easy, end with sensitive
+- One topic per step
+- Allow back navigation
+- Save progress (don't lose data on refresh)
+- Clear indication of required vs. optional
+
+### Progressive Commitment Pattern
+1. Low-friction start (just email)
+2. More detail (name, company)
+3. Qualifying questions
+4. Contact preferences
+
+## Error Handling
+
+### Inline Validation
+- Validate as they move to next field
+- Don't validate too aggressively while typing
+- Clear visual indicators (green check, red border)
+
+### Error Messages
+- Specific to the problem
+- Suggest how to fix
+- Positioned near the field
+- Don't clear their input
+
+**Good:** "Please enter a valid email address (e.g., name@company.com)"
+**Bad:** "Invalid input"
+
+### On Submit
+- Focus on first error field
+- Summarize errors if multiple
+- Preserve all entered data
+- Don't clear form on error
+
+## Submit Button Optimization
+
+### Button Copy
+Weak: "Submit" | "Send"
+Strong: "[Action] + [What they get]"
+
+Examples:
+- "Get My Free Quote"
+- "Download the Guide"
+- "Request Demo"
+- "Send Message"
+- "Start Free Trial"
+
+### Button Placement
+- Immediately after last field
+- Left-aligned with fields
+- Sufficient size and contrast
+- Mobile: Sticky or clearly visible
+
+### Post-Submit States
+- Loading state (disable button, show spinner)
+- Success confirmation (clear next steps)
+- Error handling (clear message, focus on issue)

package/src/skills-lib/form-cro/references/measurement-output.md

@@ -0,0 +1,41 @@
+# Measurement and Output Format
+
+Load this file when defining what to instrument/track, or when formatting the audit/recommendation deliverable.
+
+## Measurement
+
+### Key Metrics
+- **Form start rate**: Page views → Started form
+- **Completion rate**: Started → Submitted
+- **Field drop-off**: Which fields lose people
+- **Error rate**: By field
+- **Time to complete**: Total and by field
+- **Mobile vs. desktop**: Completion by device
+
+### What to Track
+- Form views
+- First field focus
+- Each field completion
+- Errors by field
+- Submit attempts
+- Successful submissions
+
+## Output Format
+
+### Form Audit
+For each issue:
+- **Issue**: What's wrong
+- **Impact**: Estimated effect on conversions
+- **Fix**: Specific recommendation
+- **Priority**: High/Medium/Low
+
+### Recommended Form Design
+- **Required fields**: Justified list
+- **Optional fields**: With rationale
+- **Field order**: Recommended sequence
+- **Copy**: Labels, placeholders, button
+- **Error messages**: For each field
+- **Layout**: Visual guidance
+
+### Test Hypotheses
+Ideas to A/B test with expected outcomes