# Campaign Report

**Skill:** `/campaign-report <customer>`
**Type:** Claude Code skill + Python scripts
**APIs:** SmartLead (campaign analytics)

---

## What It Does

Generates a structured weekly performance report for a customer's active outbound campaigns. It pulls fresh stats from the SmartLead API, compares them against the most recent prior report for trend analysis, and produces a complete report with executive summary, per-campaign breakdown, and actionable recommendations.

The skill is designed to run weekly (or on demand) and produces a markdown report that can be shared directly with the customer or used as internal documentation.

---

## How It Works

```
/campaign-report <customer>
        |
        v
+---------------------------+
|  Read customer profile     |
|  (ICP, KPIs, context)     |
+-------------+-------------+
              |
              v
+---------------------------+
|  Read most recent report   |
|  (baseline for comparison) |
+-------------+-------------+
              |
              v
+---------------------------+
|  Scan active campaigns     |
|  for SmartLead campaign IDs|
+-------------+-------------+
              |
              v
+---------------------------+
|  Fetch fresh stats from    |
|  SmartLead API per campaign|
+-------------+-------------+
              |
              v
+---------------------------+
|  Read active campaign copy |
|  (for context on angles)   |
+-------------+-------------+
              |
              v
+---------------------------+
|  Generate report:          |
|  - Summary with trends     |
|  - Campaign breakdown      |
|  - What's working          |
|  - What needs attention    |
|  - Recommendations         |
|  - Next steps              |
+---------------------------+
              |
              v
      Saved to customers/<name>/reports/
```

---

## Usage

```bash
# Generate a report for a customer
/campaign-report acme

# The skill reads from:
#   customers/acme/profile.md
#   customers/acme/reports/          (most recent report)
#   customers/acme/campaigns/active/ (campaign copy + IDs)

# Or run the Python scripts directly:
python analytics/campaign-report/fetch_stats.py acme
python analytics/campaign-report/generate_report.py acme
```

---

## What It Reads

| Source | Why |
|--------|-----|
| `customers/<name>/profile.md` | Understand ICP, goals, KPIs, sender profiles |
| `customers/<name>/reports/*.md` | Find baseline numbers for trend comparison |
| `customers/<name>/campaigns/active/*.md` | Extract SmartLead campaign IDs and campaign copy context |

---

## Output Format

The report follows this structure:

```markdown
# Weekly Performance Report: Customer Name
**Period:** 2026-02-15 to 2026-02-22
**Generated:** 2026-02-22 10:30

---

## Executive Summary

| Metric | This Period | Prior Period | Trend |
|--------|-----------|-------------|-------|
| Emails Sent | 1,240 | 1,180 | up |
| Open Rate | 62.3% | 58.1% | up |
| Reply Rate | 4.8% | 3.2% | up |
| Bounce Rate | 1.2% | 1.8% | down |
| Meetings Booked | 3 | 1 | up |

---

## Campaign Breakdown

| Campaign | Sent | Open Rate | Reply Rate | Bounce Rate |
|----------|------|-----------|------------|-------------|
| Pain Point - Economic | 320 | 64.1% | 5.6% | 0.9% |
| Pain Point - Data | 310 | 61.2% | 4.2% | 1.1% |
| Pain Point - Technical | 305 | 58.7% | 3.9% | 1.5% |
| Opportunities - General | 305 | 65.1% | 5.2% | 1.3% |

---

## What's Working
- Economic pain point angle generating highest reply rate (5.6%)
- Opportunities campaign has best open rate (65.1%), likely
  due to subject line approach
- Bounce rate trending down across all campaigns after list
  cleaning last week

## What Needs Attention
- Technical segment underperforming on replies (3.9% vs 4.8% avg)
- Data segment bounce rate (1.1%) slightly above target
- Reply-to-meeting conversion could improve (3 meetings from
  ~60 replies)

## Recommendations
1. A/B test new subject lines on the Technical segment
2. Review Technical segment messaging — may need sharper
   pain point or different angle
3. Tighten lead list criteria for Data segment to reduce bounces
4. Add a follow-up touchpoint for warm replies that haven't
   converted to meetings

## Next Steps
- [ ] Revise Technical campaign copy by Wednesday
- [ ] Run list hygiene on Data segment
- [ ] Schedule mid-week check on reply quality
- [ ] Prep next week's send volumes
```

---

## Key Files

| File | Purpose |
|------|---------|
| `SKILL.md` | This file -- skill documentation |
| `fetch_stats.py` | Pulls campaign stats from SmartLead API |
| `generate_report.py` | Aggregates stats and generates the markdown report |

---

## Benchmarks

These benchmarks are used to evaluate whether numbers are healthy:

| Metric | Good | Average | Poor |
|--------|------|---------|------|
| Open Rate | > 60% | 40-60% | < 40% |
| Reply Rate | > 5% | 2-5% | < 2% |
| Bounce Rate | < 2% | 2-5% | > 5% |
| Positive Reply Rate | > 40% of replies | 20-40% | < 20% |