compare-variations

name	compare-variations
description	Score 3 content variations and rank them with comparative analysis
version	1.0.0

Compare Variations — LinkedIn Audience Simulator Skill

Purpose: Score multiple post variations and compare them to identify the best performer.

Input

{
  "variation_1": "string (draft text)",
  "variation_2": "string (draft text)",
  "variation_3": "string (draft text)"
}

Output

{
  "ranked_variations": [
    {
      "rank": 1,
      "overall_score": 85,
      "confidence": "medium",
      "predicted_reactions": 38,
      "hook_type": "story",
      "topics": ["Leadership", "Founder Stories"],
      "top_segments": [
        {
          "segment": "Executives",
          "predicted_reactions": 28,
          "hook_strength": 92
        }
      ],
      "recommendation": "This is your best variation. Story hook + founder journey resonates strongly with Executives and Growth & Sales."
    }
  ],
  "comparative_analysis": {
    "variation_1_vs_2": "Variation 1 scores 10 points higher. The story hook (92/100) beats the question hook (68/100) for your Executives.",
    "variation_2_vs_3": "Variation 2 is slightly stronger. More technical depth appeals to your largest engaged segment (Technical Leaders).",
    "winner": "Variation 1"
  },
  "hook_comparison": {
    "story": 85,
    "question": 75,
    "data-driven": 68
  },
  "segment_coverage": {
    "Executives": {
      "best_variation": 1,
      "reactions_sum": 28,
      "hook_alignment": "story"
    }
  },
  "recommendation": "Post Variation 1. The story hook and founder focus will drive engagement across Executives (your most engaged segment) and Growth & Sales. Expected performance: 38 reactions, strong resonance."
}

Implementation (Python)

def compare_variations(variation_1, variation_2, variation_3):
    """Score and rank 3 variations."""
    conn = get_db_connection()

    try:
        variations = [variation_1, variation_2, variation_3]
        scores = []

        # Score each variation independently
        for i, draft in enumerate(variations, 1):
            # Use score_draft skill to score this variation
            score_result = score_draft(draft, track_for_calibration=False)

            if 'error' in score_result:
                return score_result

            scores.append({
                'variation_num': i,
                'overall_score': score_result['overall_score'],
                'confidence': score_result['confidence'],
                'predicted_reactions': score_result['predicted_metrics']['reactions'],
                'predicted_comments': score_result['predicted_metrics']['comments'],
                'predicted_reach': score_result['predicted_metrics']['reach'],
                'hook_type': score_result['hook_type'],
                'topics': score_result['topics'],
                'per_segment': score_result['per_segment']
            })

        # Sort by overall score (descending)
        scores.sort(key=lambda s: s['overall_score'], reverse=True)

        # Build ranked output
        ranked_variations = []
        for rank, score in enumerate(scores, 1):
            top_segments = sorted(
                score['per_segment'],
                key=lambda p: p['predicted_reactions'],
                reverse=True
            )[:3]

            recommendation = generate_variation_recommendation(
                rank, score['overall_score'], score['hook_type'], top_segments
            )

            ranked_variations.append({
                'rank': rank,
                'variation_number': score['variation_num'],
                'overall_score': score['overall_score'],
                'confidence': score['confidence'],
                'predicted_reactions': score['predicted_reactions'],
                'predicted_comments': score['predicted_comments'],
                'predicted_reach': score['predicted_reach'],
                'hook_type': score['hook_type'],
                'topics': score['topics'],
                'top_segments': [
                    {
                        'segment': s['segment'],
                        'predicted_reactions': s['predicted_reactions'],
                        'hook_strength': s['hook_strength']
                    }
                    for s in top_segments
                ],
                'recommendation': recommendation
            })

        # Comparative analysis
        comparative = {
            f"variation_{scores[0]['variation_num']}_vs_{scores[1]['variation_num']}":
                f"Variation {scores[0]['variation_num']} scores {scores[0]['overall_score'] - scores[1]['overall_score']:.0f} points higher. "
                f"Hook strength: {scores[0]['hook_type']} ({get_avg_hook_strength(scores[0]['per_segment']):.0f}) vs "
                f"{scores[1]['hook_type']} ({get_avg_hook_strength(scores[1]['per_segment']):.0f}). "
                f"Primary difference: {get_variation_difference(scores[0], scores[1])}.",
            'winner': f"Variation {scores[0]['variation_num']}"
        }

        # Hook comparison
        hook_comparison = {}
        for score in scores:
            hook = score['hook_type']
            avg_strength = get_avg_hook_strength(score['per_segment'])
            if hook not in hook_comparison:
                hook_comparison[hook] = avg_strength

        # Segment coverage
        segment_coverage = {}
        for seg_name in set(s['segment'] for score in scores for s in score['per_segment']):
            best_var = max(scores, key=lambda s: next(
                (p['predicted_reactions'] for p in s['per_segment'] if p['segment'] == seg_name), 0
            ))
            segment_coverage[seg_name] = {
                'best_variation': best_var['variation_num'],
                'reactions_sum': sum(
                    p['predicted_reactions'] for p in best_var['per_segment']
                    if p['segment'] == seg_name
                ),
                'hook_alignment': best_var['hook_type']
            }

        final_recommendation = (
            f"Post Variation {scores[0]['variation_num']}. "
            f"Score: {scores[0]['overall_score']}/100. "
            f"The {scores[0]['hook_type']} hook and focus on "
            f"{', '.join(scores[0]['topics'])} will drive {scores[0]['predicted_reactions']} reactions. "
            f"Best resonance with {scores[0]['per_segment'][0]['segment']}."
        )

        return {
            'ranked_variations': ranked_variations,
            'comparative_analysis': comparative,
            'hook_comparison': hook_comparison,
            'segment_coverage': segment_coverage,
            'recommendation': final_recommendation
        }

    except Exception as e:
        return {'error': f'Error comparing variations: {str(e)}'}

    finally:
        conn.close()

def generate_variation_recommendation(rank, score, hook_type, top_segments):
    """Generate a human-readable recommendation for a variation."""
    if rank == 1:
        segments_str = ', '.join(s['segment'] for s in top_segments)
        return (
            f"This is your best variation. "
            f"{hook_type.capitalize()} hook scores well ({score}/100). "
            f"Strongest appeal: {segments_str}."
        )
    elif rank == 2:
        return (
            f"Solid alternative. Score: {score}/100. "
            f"Consider this if you want to test a different hook ({hook_type}) or topic."
        )
    else:
        return (
            f"This variation underperforms the others ({score}/100). "
            f"Consider revising the hook or topic angle, or choose variation 1-2."
        )

def get_avg_hook_strength(per_segment):
    """Calculate average hook strength across segments."""
    strengths = [p['hook_strength'] for p in per_segment]
    return sum(strengths) / len(strengths) if strengths else 50

def get_variation_difference(var1, var2):
    """Describe the key difference between two variations."""
    hooks_differ = var1['hook_type'] != var2['hook_type']
    topics_differ = var1['topics'] != var2['topics']

    if hooks_differ and topics_differ:
        return f"different hook ({var1['hook_type']} vs {var2['hook_type']}) and different topics"
    elif hooks_differ:
        return f"different hook ({var1['hook_type']} vs {var2['hook_type']})"
    elif topics_differ:
        return f"different topics ({var1['topics']} vs {var2['topics']})"
    else:
        return "similar structure but different wording"

Example Output

{
  "ranked_variations": [
    {
      "rank": 1,
      "variation_number": 1,
      "overall_score": 85,
      "confidence": "medium",
      "predicted_reactions": 38,
      "predicted_comments": 9,
      "predicted_reach": 2660,
      "hook_type": "story",
      "topics": ["Leadership", "Founder Stories"],
      "top_segments": [
        {
          "segment": "Executives",
          "predicted_reactions": 28,
          "hook_strength": 92
        },
        {
          "segment": "Growth & Sales",
          "predicted_reactions": 7,
          "hook_strength": 80
        }
      ],
      "recommendation": "This is your best variation. Story hook scores well (85/100). Strongest appeal: Executives, Growth & Sales."
    },
    {
      "rank": 2,
      "variation_number": 2,
      "overall_score": 75,
      "confidence": "medium",
      "predicted_reactions": 28,
      "predicted_comments": 7,
      "predicted_reach": 1960,
      "hook_type": "question",
      "topics": ["Leadership"],
      "top_segments": [
        {
          "segment": "Technical Leaders",
          "predicted_reactions": 12,
          "hook_strength": 82
        }
      ],
      "recommendation": "Solid alternative. Score: 75/100. Consider if you want to test a different hook (question) or topic."
    }
  ],
  "comparative_analysis": {
    "variation_1_vs_2": "Variation 1 scores 10 points higher. Hook strength: story (92/100) vs question (82/100). Primary difference: different hook (story vs question).",
    "winner": "Variation 1"
  },
  "hook_comparison": {
    "story": 85,
    "question": 75,
    "data-driven": 68
  },
  "segment_coverage": {
    "Executives": {
      "best_variation": 1,
      "reactions_sum": 28,
      "hook_alignment": "story"
    }
  },
  "recommendation": "Post Variation 1. Score: 85/100. The story hook and focus on Leadership, Founder Stories will drive 38 reactions. Best resonance with Executives."
}