igny8/docs/UX-METRICS-SYSTEM-PLAN.md

UX Metrics & Widget System - Strategic Plan

Document Purpose

Strategic plan for redesigning header metrics and footer widgets based on actual system architecture, workflow states, and user journey progression. No code - pure flow and implementation strategy.

---

Part 1: System Analysis & Current State

Data Models Status Tracking

Keywords Model:

• Status: new | mapped
• Cluster assignment: nullable FK
• Volume/difficulty: inherited from SeedKeyword or overridden
• Disabled flag: excludes from workflows

Clusters Model:

• Status: new | mapped
• Keywords count: aggregated integer
• Total volume: summed from keywords
• Mapped pages: count of related content
• Disabled flag: workflow exclusion

ContentIdeas Model:

• Status: new | queued | completed
• Cluster FK: optional relationship
• Keywords M2M: multi-keyword support
• Content type/structure: categorization
• Estimated word count: planning metric
• Disabled flag: workflow exclusion

Workflow Bottlenecks & State Transitions

Critical Path Analysis:

• Keywords without clusters = workflow blockage at Stage 1
• Clusters without ideas = workflow blockage at Stage 2
• Ideas not queued = manual intervention required at Stage 3
• Volume data absence = prioritization impossible
• Disabled entities = silent workflow failures

Automation Dependencies:

• Stage 1 requires minimum 5 keywords per batch
• Credit balance must exceed 1.2x estimated cost
• Site/sector filtering applied to all queries
• Lock mechanism prevents concurrent runs
• Partial results tracked per stage for resume capability

---

Part 2: Header Metrics Strategy (Top Banner)

Design Philosophy

Header metrics must communicate workflow readiness, not just data counts. Each metric should answer: "Can I progress to the next stage?" and "What's blocking me?"

Keywords Page Header Metrics

Metric 1: Pipeline Readiness Score

• Formula: (clustered_keywords / total_active_keywords) × 100
• Displays: percentage with contextual color coding
• Color logic: <30% red | 30-60% amber | 60-85% blue | >85% green
• Purpose: instant assessment of clustering progress
• User insight: "Am I ready for idea generation?"

Metric 2: Clustering Potential

• Displays: count of new status keywords (unclustered)
• Secondary: estimated credits for auto-clustering
• Visibility trigger: shows when count > 5 (minimum batch size)
• Purpose: actionable metric for next AI operation
• User insight: "I have N keywords ready to cluster for X credits"

Metric 3: SEO Opportunity Index

• Calculation: sum of volume for unclustered keywords with difficulty <3
• Displays: total monthly search volume + count of "easy wins"
• Purpose: prioritization based on ROI potential
• User insight: "X monthly searches available in low-competition keywords"

Metric 4: Coverage Gaps

• Logic: clusters with keywords_count = 1 (under-researched topics)
• Displays: count of thin clusters
• Secondary indicator: total volume in these clusters
• Purpose: highlight research needs before content creation
• User insight: "N clusters need more keyword research"

Metric 5: Automation Ready Status

• Binary indicator: sufficient keywords for automation run
• Requirements checked: >5 keywords, credit balance adequate, no active lock
• Displays: checkmark icon + "Automation Ready" or blocking factor
• Purpose: remove friction for automation adoption
• User insight: Clear go/no-go for full pipeline run

Clusters Page Header Metrics

Metric 1: Content Generation Readiness

• Formula: (clusters_with_ideas / total_active_clusters) × 100
• Displays: percentage with progress indication
• Color coding: <40% red | 40-70% amber | 70-90% blue | >90% green
• Purpose: show how prepared user is for content creation
• User insight: "X% of my clusters are ready for content production"

Metric 2: Uncovered Clusters

• Count: clusters with status=new AND ideas_count=0
• Secondary: estimated credits for bulk idea generation
• Displays: "N clusters need ideas (cost: X credits)"
• Purpose: next-action clarity for AI operations
• User insight: Direct call-to-action with cost transparency

Metric 3: Total Coverage Volume

• Calculation: sum of volume across all clusters
• Displays: formatted number (e.g., "24.5K monthly searches")
• Comparison: against previous period if available
• Purpose: show total market opportunity being addressed
• User insight: Scale of SEO opportunity in current cluster set

Metric 4: Cluster Health Score

• Logic: percentage of clusters with keywords_count ≥3 AND volume >500
• Displays: health percentage with quality indicator
• Purpose: surface clusters worth content investment
• User insight: "X% of clusters meet quality thresholds"

Metric 5: Mapped Content Progress

• Count: clusters with mapped_pages >0
• Ratio display: "X of Y clusters have published content"
• Purpose: track execution progress from planning to publication
• User insight: Content creation completion percentage

Ideas Page Header Metrics

Metric 1: Queue Activation Rate

• Formula: (status=queued / total_ideas) × 100
• Displays: percentage + absolute count of queued ideas
• Color: <20% amber | 20-50% blue | >50% green
• Purpose: measure activation momentum toward content creation
• User insight: "X ideas active in production queue"

Metric 2: Completion Velocity

• Count: ideas with status=completed in current period
• Displays: completed count with trend indicator
• Purpose: show production throughput
• User insight: Content generation pace visibility

Metric 3: Content Credit Forecast

• Calculation: sum of (estimated_word_count / 100) × content_generation_cost for new/queued ideas
• Displays: total credits needed for all pending ideas
• Comparison: against current credit balance
• Purpose: budget planning for content production
• User insight: "Production pipeline needs X credits (Y% of balance)"

Metric 4: Structure Distribution

• Count: ideas grouped by content_structure (article, guide, listicle, etc.)
• Displays: most common structure + diversity score
• Purpose: content variety assessment
• User insight: Ensure diverse content mix for SEO

Metric 5: Orphaned Ideas Warning

• Logic: ideas with no keyword_objects AND empty target_keywords
• Count display: number of ideas lacking keyword targeting
• Purpose: quality gate before queuing
• User insight: "X ideas need keyword assignment"

---

Part 3: Footer Widget System Design

Widget Philosophy

Footer widgets provide context-rich progress tracking and next-action guidance. Unlike header metrics (quick scan), footer widgets support deeper analysis and multi-metric relationships.

Keywords Page Footer Widgets

Widget 1: Workflow Progression Tracker

• Display type: horizontal flow diagram with completion percentages
• Data points: Keywords → Clusters → Ideas → Tasks → Content
• Visual: connected nodes with percentage fills
• Interactive: clicking each node filters table to that state
• Purpose: visual pipeline status from keywords to final content
• Actionable insight: identify workflow bottlenecks visually

Widget 2: Clustering Efficiency Metrics

• Card layout with 4 sub-metrics:
  • Average keywords per cluster (target: 3-7)
  • Cluster coverage ratio (clustered/total)
  • Orphaned keywords count (no cluster assignment)
  • Last clustering activity timestamp
• Purpose: measure clustering quality and recency
• Action trigger: "Run Auto-Cluster" button if efficiency low

Widget 3: SEO Opportunity Matrix

• 2×2 grid visualization: Volume (high/low) × Difficulty (easy/hard)
• Four quadrants populated with keyword counts
• Color coding: high-volume + easy = green highlight
• Click behavior: filters table to quadrant keywords
• Purpose: prioritization dashboard for keyword targeting
• Strategic insight: focus efforts on high-ROI quadrants

Widget 4: Intent Distribution Breakdown

• Pie chart or bar graph showing keyword counts by intent type
• Intent categories: informational, commercial, transactional, navigational
• Percentage display for each category
• Purpose: content strategy alignment check
• User insight: "Am I creating content for the right user intents?"

Clusters Page Footer Widgets

Widget 1: Cluster Maturity Dashboard

• Table format with maturity scoring per cluster
• Columns: Cluster name | Keywords | Volume | Ideas | Content | Score
• Maturity score: weighted formula based on completeness
• Sort capability: by score, volume, or idea count
• Purpose: prioritize which clusters need attention
• Action: click to deep-dive into specific cluster

Widget 2: Content Pipeline Status

• Progress bars for each active cluster showing:
  • Ideas generated (vs target 3-5 per cluster)
  • Tasks created (queued ideas)
  • Content produced (completed articles)
  • Published count (live on site)
• Purpose: track execution from planning to publication per cluster
• Visual hierarchy: clusters closest to completion highlighted

Widget 3: Volume vs Coverage Chart

• Scatter plot: X-axis = total volume, Y-axis = content produced
• Each bubble = one cluster, size = keyword count
• Quadrant labels: "High opportunity, low coverage" = priority zone
• Purpose: visual gap analysis for content strategy
• Actionable: identify high-value clusters without content

Widget 4: Idea Generation Summary

• Metrics card showing:
  • Total clusters (active, not disabled)
  • Clusters with 0 ideas (needs action)
  • Average ideas per cluster
  • Estimated credits to fill all gaps
• CTA button: "Generate Missing Ideas" with credit preview
• Purpose: one-click path to complete idea coverage

Ideas Page Footer Widgets

Widget 1: Production Queue Analytics

• Three-column layout:
  • New (not activated): count + bulk queue option
  • Queued (in production): count + estimated completion time
  • Completed: count + publish readiness indicator
• Progress bar: overall completion percentage across all ideas
• Purpose: production pipeline visibility and queue management
• Actions: bulk status updates with single click

Widget 2: Content Type Mix Analyzer

• Stacked bar chart showing distribution:
  • Content types: post, page, product, taxonomy
  • Structure types: article, guide, comparison, review, listicle
• Target mix overlay: recommended distribution for SEO
• Purpose: ensure content portfolio diversity
• Insight: flag over-concentration in single content type

Widget 3: Keyword Targeting Health

• Metrics showing:
  • Ideas with 0 keywords (critical issue)
  • Ideas with 1-2 keywords (acceptable)
  • Ideas with 3+ keywords (optimal)
  • Average keyword count per idea
• Alert: red badge for ideas missing keywords
• Purpose: quality control before content production
• Action: filter table to show untargeted ideas

Widget 4: Credit Burn Rate Projector

• Financial planning widget:
  • Current queued ideas credit cost
  • Current credit balance
  • Estimated credits per week based on queue rate
  • Runway: weeks until credits depleted at current pace
• Visual: gauge showing balance sufficiency
• Purpose: prevent mid-production credit depletion
• Action: "Add Credits" CTA when runway <2 weeks

---

Part 4: Cross-Page Integration Strategy

Global Workflow State Indicator

• Persistent mini-widget in page header showing:
  • Current stage completion: Keywords 85% → Clusters 60% → Ideas 40%
  • Next recommended action based on lowest percentage
  • Quick-jump links to pages needing attention
• Purpose: maintain workflow context across navigation
• Always visible: helps users stay oriented in multi-step process

Automation Readiness Badge

• Displayed when ALL conditions met:
  • Keywords ≥5 per batch configuration
  • Credit balance ≥ 1.2× estimated pipeline cost
  • No active automation lock
  • At least one complete keyword→cluster→idea chain exists
• Visual: pulsing badge "Ready for Automation"
• Click behavior: opens automation config modal
• Purpose: drive automation adoption at optimal timing

---

Part 5: Implementation Data Requirements

New Computed Fields Needed

Keywords Model:

• Pipeline position: enum tracking how far keyword has progressed
• SEO opportunity score: volume × (inverse difficulty) calculation
• Last modified timestamp: for activity recency metrics

Clusters Model:

• Maturity score: formula based on keywords count, ideas count, volume, content count
• Completion percentage: ideas/target ratio
• Health status: enum (healthy, needs-attention, critical)

ContentIdeas Model:

• Production readiness: boolean check for keywords, structure, word count
• Estimated time to complete: based on word count and average production rate
• Target ROI: volume of associated keywords / estimated credits

Aggregation Queries Required

• Cross-model counts: keywords→clusters→ideas→tasks→content chain
• Volume summations: at keyword, cluster, and idea levels with filtering
• Credit calculations: bulk cost estimates for batch operations
• Time-series data: completion rates over rolling periods
• Distribution analyses: intent, difficulty, structure breakdowns

Performance Considerations

• Cache frequently accessed aggregations (cluster counts, volume sums)
• Compute expensive metrics asynchronously (maturity scores, opportunity indices)
• Provide real-time updates only for user-initiated actions
• Use database views for complex joins in footer widgets
• Implement pagination for widget data exceeding 100 records

---

Part 6: User Journey Mapping

New User Journey (Days 1-7)

Day 1: Import keywords → Header shows "0% clustered" → Footer widget highlights "Run Auto-Cluster" Day 2: Keywords clustered → Header shows improvement → Footer suggests "Generate ideas for X clusters" Day 3: Ideas created → Header shows queue status → Footer prompts "Queue ideas to Writer" Day 5: First content in production → All metrics show progress → Automation badge appears Day 7: First publish → Footer celebrates milestone → Prompts scaling via automation

Established User Journey (Ongoing)

• Header metrics: quick health check on page load
• Footer widgets: deep-dive when planning next actions
• Automation badge: reinforces scale-up path
• Cross-page indicator: maintains context during workflow execution

Power User Journey (Optimization Phase)

• Header metrics: track efficiency improvements (better clustering ratios, higher completion rates)
• Footer widgets: strategic planning tools (opportunity matrices, ROI projections)
• Automation: primary workflow with manual intervention only for edge cases

---

Part 7: Accessibility & Responsiveness

Mobile Considerations

• Header metrics: show top 3 most critical on mobile, expandable drawer for rest
• Footer widgets: vertical stack layout, one widget visible at a time with swipe navigation
• Touch targets: minimum 44×44px for all interactive elements
• Tooltip alternatives: tap-to-reveal detail panels instead of hover states

Screen Reader Support

• Semantic HTML: use proper ARIA landmarks for metric regions
• Live regions: announce metric updates with aria-live for dynamic changes
• Descriptive labels: "Pipeline readiness 67 percent, requires attention" vs "67%"
• Keyboard navigation: tab order follows logical workflow progression

Color Blindness Accommodations

• Pattern overlays: combine color with icons or patterns (not color alone)
• High contrast mode: ensure metrics readable in Windows high contrast
• Text labels: always include text with color-coded indicators
• Consistent semantics: green=good, red=needs action, amber=caution across all contexts

---

Part 8: Success Metrics for This System

Engagement Metrics

• Metric interaction rate: percentage of users clicking header metrics or footer widgets
• Action completion: users who click widget CTA and complete suggested action
• Navigation patterns: reduced page-hopping after metrics implementation
• Time-to-action: reduced time from page load to workflow action initiation

Business Impact Metrics

• Automation adoption: percentage increase in users running automation after readiness badge
• Credit efficiency: credits spent per published article (should decrease with better planning)
• Pipeline velocity: reduced time from keyword import to content publication
• User retention: reduced churn in days 3-14 (critical onboarding period)

Quality Metrics

• Fewer orphaned keywords: percentage of keywords clustered increases
• Better keyword targeting: ideas with 0 keywords decreases
• Content diversity: even distribution across content structures
• Credit planning: fewer instances of mid-production credit depletion

---

Part 9: Future Enhancement Considerations

Predictive Metrics

• ML-based opportunity scoring: predict which clusters will generate most traffic
• Credit burn forecasting: predict when user will need to purchase more credits
• Completion time estimates: based on historical user patterns and queue depth
• Anomaly detection: alert when metrics deviate significantly from user's baseline

Comparative Metrics

• Benchmark against similar accounts: "Your clustering efficiency is in top 20%"
• Historical comparison: "30% improvement in pipeline velocity vs last month"
• Goal tracking: user-set targets with progress indicators
• Peer insights: anonymized aggregate data showing what successful users do

Integration Opportunities

• Export metrics to external analytics: Google Data Studio, Tableau
• Webhook notifications: alert external systems when key thresholds crossed
• API access: allow users to build custom dashboards with metric data
• Calendar integration: suggest optimal times to run automation based on credit refresh

---

End of Strategic Plan - Ready for implementation phase with component-level specifications