performance-report

# Performance Report

Generate weekly or monthly affiliate performance reports — earnings, clicks, conversions, EPC, top performers, underperformers, and trend analysis. Output is a Markdown report with KPI dashboard, program rankings, and actionable recommendations.

## Stage

S6: Analytics — Data without analysis is just noise. This skill transforms raw affiliate numbers into insights — which programs are worth your time, which are dragging your portfolio down, and where to focus next. Professional affiliates review performance weekly.

## When to Use

- User wants to review their affiliate earnings for a period
- User asks "how are my programs doing?" or "show me my affiliate report"
- User has click/conversion/revenue data and wants analysis
- User wants to compare performance across multiple programs
- User says "weekly report", "monthly report", "earnings breakdown"
- Chaining from S6.1 (conversion-tracker) — analyze the data those links collected

## Input Schema

```yaml
programs:
  - name: string               # REQUIRED — program name (e.g., "HeyGen")
    clicks: number             # OPTIONAL — total clicks this period
    conversions: number        # OPTIONAL — total conversions
    revenue: number            # OPTIONAL — total commission earned ($)
    commission: number         # OPTIONAL — commission per sale ($)
    spend: number              # OPTIONAL — money spent on ads/promotion ($)

period: string                 # OPTIONAL — "week" | "month" | "quarter"
                               # Default: "month"

goals:
  revenue_target: number       # OPTIONAL — target revenue for the period ($)
  conversion_target: number    # OPTIONAL — target conversions

previous_period:               # OPTIONAL — last period's data for trend analysis
  - name: string
    clicks: number
    conversions: number
    revenue: number

notes: string                  # OPTIONAL — context about the period
                               # (e.g., "launched new blog post week 2")
```

**Chaining context**: If S1 program data or S6.1 tracking data exists in conversation, pull program names and any available metrics.

## Workflow

### Step 1: Collect Program Data

Gather data from user input. If data is incomplete, work with what's available and note gaps:
- "You provided revenue but not clicks — I can calculate revenue per program but not EPC or conversion rate."

### Step 2: Calculate KPIs

For each program:
- **EPC** (Earnings Per Click): revenue / clicks
- **Conversion Rate**: conversions / clicks × 100
- **Revenue Share**: program revenue / total revenue × 100
- **CPA** (Cost Per Acquisition): spend / conversions (if spend provided)
- **ROAS** (Return on Ad Spend): revenue / spend (if spend provided)
- **Commission Per Sale**: revenue / conversions

Portfolio-level:
- **Total Revenue**: sum of all program revenue
- **Blended EPC**: total revenue / total clicks
- **Blended Conversion Rate**: total conversions / total clicks × 100
- **Top Performer**: highest EPC program
- **Underperformer**: lowest EPC program

### Step 3: Rank Programs

Sort programs by ROI efficiency:
1. EPC (primary sort)
2. Total revenue (secondary)
3. Conversion rate (tertiary)

Assign labels:
- **Star**: High EPC + high volume → double down
- **Cash Cow**: Moderate EPC + high volume → maintain
- **Question Mark**: High EPC + low volume → scale up
- **Dog**: Low EPC + low volume → consider dropping

### Step 4: Identify Trends

If `previous_period` data is provided:
- Revenue trend: up/down/flat (with percentage)
- Click trend: up/down/flat
- Conversion trend: up/down/flat
- Per-program trends

### Step 5: Generate Recommendations

Based on data:
- **Double down**: Programs with high EPC that need more traffic
- **Optimize**: Programs with high traffic but low conversion (content issue)
- **Phase out**: Programs with low EPC and low volume
- **Investigate**: Programs with unusual patterns (sudden drops)

### Step 6: Self-Validation

Before presenting output, verify:

- [ ] EPC calculation correct: revenue ÷ clicks
- [ ] Conversion rate percentages are accurate
- [ ] Revenue shares across programs sum to ~100%
- [ ] Labels match metrics: Star (high EPC + growth), Cash Cow (high revenue + stable), Question Mark (low data), Dog (declining)
- [ ] Recommendations are specific and reference concrete next steps

If any check fails, fix the output before delivering. Do not flag the checklist to the user — just ensure the output passes.

## Output Schema

```yaml
output_schema_version: "1.0.0"  # Semver — bump major on breaking changes
report:
  period: string
  total_revenue: number
  total_clicks: number
  total_conversions: number
  blended_epc: number
  blended_conversion_rate: number
  goal_progress: string        # "on_track" | "behind" | "ahead" | "no_goal"

programs:
  - name: string
    clicks: number
    conversions: number
    revenue: number
    epc: number
    conversion_rate: number
    revenue_share: number      # percentage of total
    label: string              # "star" | "cash_cow" | "question_mark" | "dog"
    trend: string              # "up" | "down" | "flat" | "new"

recommendations:
  - program: string
    action: string             # "double_down" | "optimize" | "phase_out" | "investigate"
    reason: string
    next_step: string          # specific action to take
```

## Output Format

1. **KPI Dashboard** — summary table with total revenue, clicks, conversions, blended EPC
2. **Program Rankings** — table sorted by EPC with labels (Star/Cash Cow/Question Mark/Dog)
3. **Trend Analysis** — period-over-period comparison (if previous data provided)
4. **Recommendations** — prioritized list of actions per program
5. **Goal Progress** — progress toward targets (if goals provided)

## Error Handling

- **No data provided**: "I need your affiliate numbers to generate a report. At minimum, provide: program names and revenue. Ideally also clicks and conversions. You can get these from your affiliate dashboard or tra