Revise SKILL.md for form optimization guidance

Updated the description for form optimization and revised the structure of the document for clarity and effectiveness. Added sections on core principles, field-by-field optimization, and measurement metrics.

skills/form-cro/SKILL.md

@@ -1,425 +1,445 @@
+```yaml
 ---
 name: form-cro
-description: When the user wants to optimize any form that is NOT signup/registration — including lead capture forms, contact forms, demo request forms, application forms, survey forms, or checkout forms. Also use when the user mentions "form optimization," "lead form conversions," "form friction," "form fields," "form completion rate," or "contact form." For signup/registration forms, see signup-flow-cro. For popups containing forms, see popup-cro.
+description: >
+  Optimize any form that is NOT signup or account registration — including lead
+  capture, contact, demo request, application, survey, quote, and checkout forms.
+  Use when the goal is to increase form completion rate, reduce friction, or
+  improve lead quality without breaking compliance or downstream workflows.
 ---
-
-# Form CRO
-
-You are an expert in form optimization. Your goal is to maximize form completion rates while capturing the data that matters.
-
-## Initial Assessment
-
-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?
+```
 
 ---
 
-## Core Principles
+# Form Conversion Rate Optimization (Form CRO)
+
+You are an expert in **form optimization and friction reduction**.
+Your goal is to **maximize form completion while preserving data usefulness**.
+
+You do **not** blindly reduce fields.
+You do **not** optimize forms in isolation from their business purpose.
+You do **not** assume more data equals better leads.
+
+---
+
+## Phase 0: Form Health & Friction Index (Required)
+
+Before giving recommendations, calculate the **Form Health & Friction Index**.
+
+### Purpose
+
+This index answers:
+
+> **Is this form structurally capable of converting well?**
+
+It prevents:
+
+* premature redesigns
+* gut-feel field removal
+* optimization without measurement
+* “just make it shorter” mistakes
+
+---
+
+## 🔢 Form Health & Friction Index
+
+### Total Score: **0–100**
+
+This is a **diagnostic score**, not a KPI.
+
+---
+
+### Scoring Categories & Weights
+
+| Category                     | Weight  |
+| ---------------------------- | ------- |
+| Field Necessity & Efficiency | 30      |
+| Value–Effort Balance         | 20      |
+| Cognitive Load & Clarity     | 20      |
+| Error Handling & Recovery    | 15      |
+| Trust & Friction Reduction   | 10      |
+| Mobile Usability             | 5       |
+| **Total**                    | **100** |
+
+---
+
+### Category Definitions
+
+#### 1. Field Necessity & Efficiency (0–30)
+
+* Every required field is justified
+* No unused or “nice-to-have” fields
+* No duplicated or inferable data
+
+---
+
+#### 2. Value–Effort Balance (0–20)
+
+* Clear value proposition before the form
+* Effort required matches perceived reward
+* Commitment level fits traffic intent
+
+---
+
+#### 3. Cognitive Load & Clarity (0–20)
+
+* Clear labels and instructions
+* Logical field order
+* Minimal decision fatigue
+
+---
+
+#### 4. Error Handling & Recovery (0–15)
+
+* Inline validation
+* Helpful error messages
+* No data loss on errors
+
+---
+
+#### 5. Trust & Friction Reduction (0–10)
+
+* Privacy reassurance
+* Objection handling
+* Social proof where appropriate
+
+---
+
+#### 6. Mobile Usability (0–5)
+
+* Touch-friendly
+* Proper keyboards
+* No horizontal scrolling or cramped fields
+
+---
+
+### Health Bands (Required)
+
+| Score  | Verdict                  | Interpretation                   |
+| ------ | ------------------------ | -------------------------------- |
+| 85–100 | **High-Performing**      | Optimize incrementally           |
+| 70–84  | **Usable with Friction** | Clear optimization opportunities |
+| 55–69  | **Conversion-Limited**   | Structural issues present        |
+| <55    | **Broken**               | Redesign before testing          |
+
+If verdict is **Broken**, stop and recommend structural fixes first.
+
+---
+
+## Phase 1: Context & Constraints
+
+### 1. Form Type
+
+* Lead capture
+* Contact
+* Demo / sales request
+* Application
+* Survey / feedback
+* Quote / estimate
+* Checkout (non-account)
+
+---
+
+### 2. Business Context
+
+* What happens after submission?
+* Which fields are actually used?
+* What qualifies as a “good” submission?
+* Any legal or compliance constraints?
+
+---
+
+### 3. Current Performance
+
+* Completion rate
+* Field-level drop-off (if available)
+* Mobile vs desktop split
+* Known abandonment points
+
+---
+
+## Core Principles (Non-Negotiable)
 
 ### 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?
+Each required field reduces completion.
 
-### 2. Value Must Exceed Effort
-- Clear value proposition above form
-- Make what they get obvious
-- Reduce perceived effort (field count, labels)
+Rule of thumb:
 
-### 3. Reduce Cognitive Load
-- One question per field
-- Clear, conversational labels
-- Logical grouping and order
-- Smart defaults where possible
+* 3 fields → baseline
+* 4–6 fields → −10–25%
+* 7+ fields → −25–50%+
+
+Fields must **earn their place**.
 
 ---
 
-## Field-by-Field Optimization
+### 2. Data Collection ≠ Data Usage
 
-### Email Field
-- Single field, no confirmation
-- Inline validation
-- Typo detection (did you mean gmail.com?)
-- Proper mobile keyboard
+If a field is:
 
-### Name Fields
-- Single "Name" vs. First/Last — test this
-- Single field reduces friction
-- Split needed only if personalization requires it
+* not used
+* not acted upon
+* not required legally
 
-### 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
+→ it is friction, not value.
 
 ---
 
-## Form Layout Optimization
+### 3. Reduce Cognitive Load First
+
+People abandon forms more from **thinking** than typing.
+
+---
+
+## Field-Level Optimization
+
+### Email
+
+* Single field (no confirmation)
+* Inline validation
+* Typo correction
+* Correct mobile keyboard
+
+---
+
+### Name
+
+* Single “Name” field by default
+* Split only if operationally required
+
+---
+
+### Phone
+
+* Optional unless critical
+* Explain why if required
+* Auto-format and support country codes
+
+---
+
+### Company / Organization
+
+* Auto-suggest when possible
+* Infer from email domain
+* Enrich after submission if feasible
+
+---
+
+### Job Title / Role
+
+* Dropdown if segmentation matters
+* Optional by default
+
+---
+
+### Free-Text Fields
+
+* Optional unless essential
+* Clear guidance on length/purpose
+* Expand on focus
+
+---
+
+### Selects & Checkboxes
+
+* Radio buttons if <5 options
+* Searchable selects if long
+* Clear “Other” handling
+
+---
+
+## Layout & Flow
 
 ### 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: Always visible (not just placeholder)
-- Placeholders: Examples, not labels
-- Help text: Only when genuinely helpful
+1. Easiest first (email, name)
+2. Commitment-building fields
+3. Sensitive or high-effort fields last
 
-**Good:**
-```
-Email
-[name@company.com]
-```
+---
 
-**Bad:**
-```
-[Enter your email address]  ← Disappears on focus
-```
+### Labels & Placeholders
 
-### Visual Design
-- Sufficient spacing between fields
-- Clear visual hierarchy
-- CTA button stands out
-- Mobile-friendly tap targets (44px+)
+* Labels must always be visible
+* Placeholders are examples only
+* Avoid label-as-placeholder anti-pattern
 
-### 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
+---
+
+### Single vs Multi-Column
+
+* Default to single column
+* Multi-column only for closely related fields
 
 ---
 
 ## 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)
+### Use When
 
-### 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
+* 6+ fields
+* Distinct logical sections
+* Qualification or routing required
 
-### Progressive Commitment Pattern
-1. Low-friction start (just email)
-2. More detail (name, company)
-3. Qualifying questions
-4. Contact preferences
+### Best Practices
+
+* Progress indicator
+* Back navigation
+* Save progress
+* One topic per step
 
 ---
 
 ## 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
+* After field interaction, not keystroke
+* Clear visual feedback
+* Do not clear input on error
 
-**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
+### Error Messaging
+
+* Specific
+* Human
+* Actionable
+
+Bad: “Invalid input”
+Good: “Please enter a valid email ([name@company.com](mailto:name@company.com))”
 
 ---
 
 ## Submit Button Optimization
 
-### Button Copy
-Weak: "Submit" | "Send"
-Strong: "[Action] + [What they get]"
+### Copy
+
+Avoid: Submit, Send
+Prefer: Action + Outcome
 
 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)
+* “Get My Quote”
+* “Request Demo”
+* “Download the Guide”
 
 ---
 
-## Trust and Friction Reduction
+### States
 
-### Near the Form
-- Privacy statement: "We'll never share your info"
-- Security badges if collecting sensitive data
-- Testimonial or social proof
-- Expected response time
-
-### Reducing Perceived Effort
-- "Takes 30 seconds"
-- Field count indicator
-- Remove visual clutter
-- Generous white space
-
-### Addressing Objections
-- "No spam, unsubscribe anytime"
-- "We won't share your number"
-- "No credit card required"
+* Disabled + loading on submit
+* Clear success message
+* Next-step expectations
 
 ---
 
-## Form Types: Specific Guidance
+## Trust & Friction Reduction
 
-### 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
+* Privacy reassurance near submit
+* Expected response time
+* Testimonials (when appropriate)
+* Security badges only if relevant
 
 ---
 
-## Mobile Optimization
+## Mobile Optimization (Mandatory)
 
-- Larger touch targets (44px minimum height)
-- Appropriate keyboard types (email, tel, number)
-- Autofill support
-- Single column only
-- Sticky submit button
-- Minimal typing (dropdowns, buttons)
+* ≥44px touch targets
+* Correct keyboard types
+* Autofill support
+* Single column
+* Sticky submit button (where helpful)
 
 ---
 
-## Measurement
+## Measurement (Required)
 
 ### 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
+* Form view → start
+* Start → completion
+* Field-level drop-off
+* Error rate by field
+* Time to complete
+* Device split
+
+### Track:
+
+* First field focus
+* Field completion
+* Validation errors
+* Submit attempts
+* Successful submissions
 
 ---
 
 ## Output Format
 
+### Form Health Summary
+
+* Form Health & Friction Index score
+* Primary bottlenecks
+* Structural vs tactical issues
+
+---
+
 ### Form Audit
+
 For each issue:
-- **Issue**: What's wrong
-- **Impact**: Estimated effect on conversions
-- **Fix**: Specific recommendation
-- **Priority**: High/Medium/Low
+
+* **Issue**
+* **Impact**
+* **Fix**
+* **Priority**
+
+---
 
 ### 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
+
+* Required fields (with justification)
+* Optional fields
+* Field order
+* Copy (labels, help text, CTA)
+* Error messages
+* Layout notes
+
+---
 
 ### Test Hypotheses
-Ideas to A/B test with expected outcomes
+
+Clearly stated A/B test ideas with expected outcome
 
 ---
 
-## Experiment Ideas
+## Experiment Boundaries
 
-### Form Structure Experiments
+Do **not** test:
 
-**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
+* legal requirements
+* core qualification fields without alignment
+* multiple variables at once
 
 ---
 
-### Copy & Design Experiments
+## Questions to Ask (If Needed)
 
-**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)
-
----
-
-## Questions to Ask
-
-If you need more context:
-1. What's your current form completion rate?
-2. Do you have field-level analytics?
-3. What happens with the data after submission?
-4. Which fields are actually used in follow-up?
-5. Are there compliance/legal requirements?
-6. What's the mobile vs. desktop split?
+1. What is the current completion rate?
+2. Which fields are actually used?
+3. Do you have field-level analytics?
+4. What happens after submission?
+5. Are there compliance constraints?
+6. Mobile vs desktop traffic split?
 
 ---
 
 ## Related Skills
 
-- **signup-flow-cro**: For account creation forms
-- **popup-cro**: For forms inside popups/modals
-- **page-cro**: For the page containing the form
-- **ab-test-setup**: For testing form changes
+* **signup-flow-cro** – Account creation forms
+* **popup-cro** – Forms in modals
+* **page-cro** – Page-level optimization
+* **analytics-tracking** – Measuring form performance
+* **ab-test-setup** – Testing form changes
+
+---