# PRD: Agent Moneypenny
**Marketing Performance Analysis Agent**

---

## 1. Overview

Agent Moneypenny analyzes organic social media performance across X, YouTube, and Substack to surface what's working and what isn't. Unlike vanity-metric reporting, Moneypenny is ruthlessly pragmatic: she measures success by subscriber growth and surfaces actionable patterns in post performance.

**Vision:** A weekly (or on-demand) briefing delivered to the Hyperagent dashboard that tells a small team *exactly* what to replicate, abandon, or double down on—with prioritized actions, team assignment, and accountability tracking.

**User:** Small marketing teams (2–3 creators/ops) managing organic social across multiple platforms. Outputs feed directly into the team's workflow via Hyperagent dashboard.

---

## 2. Problem Statement

Creators ship content across multiple platforms but lack time to:
- Synthesize performance across disparate dashboards/APIs
- Distinguish signal (meaningful patterns) from noise (statistical flukes)
- Identify *why* some posts outperform others
- Know which platform-specific tactics to double down on

Result: They rely on intuition rather than data. Moneypenny kills that.

---

## 3. Core Experience

### 3.1 Trigger
- **Weekly cadence:** Runs every Sunday at 9 AM (configurable)
- **On-demand:** User clicks "Analyze Now" button in dashboard/app
- **Scope:** All posts from July 1 onwards

### 3.2 Agent Workflow

**Input:** Pull performance data for all posts across three platforms.

**Process:**
1. **Channel Performance Review**
   - Aggregate stats per platform (total posts, avg engagement, subscriber impact)
   - Compare to baseline (their own 4-week rolling average)
   
2. **Last Week vs. Platform Average**
   - Identify posts from past 7 days
   - Benchmark each post's metrics against that platform's rolling 4-week median
   - Flag outliers (top 25% and bottom 25%)
   
3. **Winners & Losers**
   - Top 3 posts (by engagement, subscriber correlation)
   - Bottom 3 posts (by engagement or subscriber churn)
   - Annotate: topic, format, timing, hashtags, etc.
   
4. **3 Insights**
   - What pattern emerges in winners? (e.g., "Threads with 3+ paragraphs get 40% more engagement")
   - What kills engagement? (e.g., "Self-promotional posts underperform by 60%")
   - Platform-specific finding? (e.g., "YouTube Shorts trending on Mondays, long-form on Thursdays")
   
5. **3 Actions**
   - **Scheduling:** Specific publish times & frequency (e.g., "Post threads on X Tue/Thu 9–11 AM ET")
   - **Format/Content:** Prescriptive changes (e.g., "Switch to 3-part threads instead of 1-offs"; "Add captions to YouTube Shorts")
   - **Pause/Stop:** What underperforms (e.g., "Pause sponsor spotlights; test pure-value sends for 3 weeks")
   - **Experiment:** A/B test proposal with success metric (e.g., "Test subject line patterns (numbers vs. questions); measure open rate lift")
   - **Quick-action:** Pre-built action buttons in dashboard (e.g., "Schedule 3 threads this week using winning template")

**Output:** Structured report (see Section 4).

---

## 4. Data Model & Platform-Specific Workflows

### 4.1 X (Twitter API v2)

**Metrics available:**
- Impressions, engagements, replies, retweets, quote tweets, favorites, bookmark rate
- Post timestamp, content type (thread, reply, retweet, etc.)
- Author followers at post time

**KPI linkage:**
- Correlation between engagement rate and follower growth
- Count new followers gained in 7 days post-publication

**Workflow:**
1. Fetch all posts from July 1 onwards (via `/tweets/search/recent` or `/users/tweets`)
2. For each post: pull engagement metrics and organic engagement rate
3. Calculate rolling 4-week median engagement rate (baseline)
4. Identify posts that outperform/underperform baseline by >30%
5. Segment winners by: thread vs. single post, content category, timestamp
6. Measure subscriber correlation (new followers in 7 days post-publication)

---

### 4.2 YouTube

**Metrics available:**
- Views, watch time, average view duration, click-through rate (CTR), subscriber gain, likes, comments

**KPI linkage:**
- Direct: subscriber count delta per video
- Indirect: average view duration (proxy for content quality)

**Workflow:**
1. Fetch all videos published since July 1 (via YouTube Analytics API)
2. For each video: pull views, watch time, avg. view duration, CTR, subscriber gain
3. Calculate rolling 4-week median for each metric
4. Identify outliers: videos with >150% median performance = winners; <50% = losers
5. Segment by: video type (short-form, long-form, premiere), content theme, publish day/time
6. Correlate subscriber gain with video performance (which videos convert best?)

**Note:** YouTube API requires channel-level access; assumes user has connected their channel.

---

### 4.3 Substack (Google Sheets)

**Data structure:** Assume user maintains a Substack performance sheet with columns:
- Post title, publish date, email sent (yes/no), subject line
- Open rate, click-through rate (CTR), subscriber gain, subscriber churn
- Content category/topic

**Workflow:**
1. Read connected Google Sheet (via Google Sheets API)
2. Filter for entries since July 1
3. Calculate rolling 4-week median open rate and CTR
4. Identify outliers: emails with >125% median open rate = winners; <75% = losers
5. Segment by: subject line length, content theme, send time (if available), email-only vs. cross-posted
6. Correlate subscriber gain with email performance (which posts drive paid upgrades?)

**Note:** Requires manual data entry or Substack integration; assume data accuracy is user's responsibility.

---

## 5. Output Format

### 5.1 Report Structure

```
Agent Moneypenny Weekly Briefing
[Report Date: YYYY-MM-DD]

📊 CHANNEL PERFORMANCE OVERVIEW
├─ X: 47 posts | Avg engagement rate: 2.1% | +123 subscribers this week
├─ YouTube: 3 videos | Avg watch time: 18m | +45 subscribers this week
└─ Substack: 2 emails | Avg open rate: 42% | +67 subscribers this week

🏆 WINNERS (Last 7 Days vs. Platform Average)
├─ X: "Thread on AI regulation frameworks" 
│  └─ 4.2% engagement rate (+100% vs. 2.1% avg) | +32 new followers
├─ YouTube: "Building a RAG system" 
│  └─ 28 min avg watch time (+55% vs. 18m avg) | +18 new subs
└─ Substack: "Venture debt deep dive"
   └─ 58% open rate (+38% vs. 42% avg) | +22 new subs

💔 LOSERS (Last 7 Days vs. Platform Average)
├─ X: "Product update thread"
│  └─ 0.8% engagement rate (-62% vs. 2.1% avg)
├─ YouTube: "Q&A live stream"
│  └─ 9 min avg watch time (-50% vs. 18m avg) | -3 subs
└─ Substack: "Sponsor spotlight"
   └─ 28% open rate (-33% vs. 42% avg)

💡 3 KEY INSIGHTS
1. Polarizing topics (regulation, controversy) drive 2.5x engagement on X vs. neutral updates
2. Video content >20 min watch time converts 3x more YouTube subscribers than <10 min content
3. Substack subject lines with specific numbers ("3 reasons...", "5 lessons...") open 18% higher

⚙️ 3 RECOMMENDED ACTIONS (Prioritized by ROI)

[🔴 HIGH IMPACT – DO THIS WEEK]
Action 1: Publish threads on X 2x weekly during peak hours (9–11 AM ET)
├─ Rationale: Polarizing topics drive 2.5x engagement; current posting cadence is 1x/week
├─ Format: 3-part threads (winning format)
├─ Effort: 2 hours/week | Expected impact: +15–20% engagement | Subscriber lift: +5–8/week
├─ Assigned to: [Open]
├─ Target completion: This week
└─ Status: [Not started]

[🟡 MEDIUM IMPACT – THIS MONTH]
Action 2: YouTube video experiment – target 20+ min average watch time
├─ Rationale: Videos with >20 min watch time convert 3x more subscribers
├─ Tactic: Next video – segment into chapters; add timestamps in description
├─ Effort: 1 hour production | Expected impact: +8–10% watch time | Subscriber lift: +3–5/video
├─ Assigned to: [Open]
├─ Target completion: 2 weeks
└─ Status: [Not started]

[🔵 LOWER PRIORITY – TRY NEXT QUARTER]
Action 3: A/B test Substack subject lines with numbers vs. questions
├─ Rationale: Numbers-based subjects open 18% higher; test on next 4 sends
├─ Test design: Alternate subject line format each send; log results
├─ Effort: Minimal (manual tracking) | Expected impact: +5–8% open rate
├─ Assigned to: [Open]
├─ Target completion: Month-end review
└─ Status: [Not started]

🔗 DASHBOARD FEATURES
├─ 📝 Add notes (team context, blockers, results)
├─ ✓ Mark action as complete
├─ 👤 Assign to team member + set deadline
├─ 📊 Link to A/B test results (when available)
└─ 🔄 Compare to last week's actions (what moved the needle?)

📈 NEXT ANALYSIS: [Date + Time]
```

### 5.2 Delivery Channel
- **Primary:** Hyperagent dashboard widget
- **Integration:** Real-time report generation; users see results immediately after "Analyze Now" click
- **Team visibility:** All team members see the same report; flagged insights persist for reference

### 5.3 Team Collaboration Features
Small team workflows require shared context and accountability.

**Dashboard features:**
- **Insights persist:** Each weekly report archived; team can compare trends over time
- **Notes & comments:** Team members add context to insights (e.g., "This spike was due to X trending")
- **Action assignment:** Assign recommendations to specific team members with due dates
- **Status tracking:** Mark actions as "Queued," "In Progress," "Complete," or "Deprioritized" with rationale
- **A/B test companion:** Agent suggests experiments; team logs results in dashboard; next report incorporates learnings
- **Audit trail:** Who viewed the report, what actions were taken, when—for accountability and learning

**Workflow example:**
1. Agent generates report (Sunday 9 AM or on-demand)
2. Team lead reviews insights; assigns 2–3 actions to writers/editors
3. Writer schedules X threads using recommended times/templates
4. Next report flags performance delta vs. previous week
5. Team captures learnings in "Notes" for future reference

---

## 6. Hyperagent Dashboard Integration

### 6.0 Dashboard Widget Specification

Agent Moneypenny runs as a Hyperagent agent that generates reports and displays them in a persistent dashboard widget.

**Widget layout:**
1. **Header** — Report date, next analysis date, "Analyze Now" button
2. **Tabs** — Channel Performance | Winners | Losers | Insights | Actions
3. **Channel Performance tab:**
   - 3-column layout (X | YouTube | Substack)
   - Each column: key metrics + trend indicators (↑/↓ vs. baseline)
   - Summary line: "X: 47 posts | +2.1% avg engagement vs. 4-week avg | +123 subs this week"
4. **Winners/Losers tabs:**
   - Sortable/filterable table or card view
   - Top 3 + bottom 3; expandable for full list
   - Annotations: topic, format, timestamp, engagement delta
5. **Insights tab:**
   - Three key findings with supporting data
   - Color-coded insight type (e.g., "Pattern" vs. "Opportunity" vs. "Risk")
6. **Actions tab:**
   - Priority-ranked list (🔴 HIGH | 🟡 MEDIUM | 🔵 LOW)
   - Inline assignment, status tracking, notes
   - "Quick-action" buttons where applicable (e.g., "Create thread template")

**Persistence:**
- All reports archived; team can compare week-over-week
- Notes, assignments, and status updates persist across sessions
- Search/filter by action status, assignee, date range

### 6.1.1 Agent Output Contract
Agent Moneypenny outputs a structured JSON payload to Hyperagent, which renders it in the dashboard:

```json
{
  "report_date": "2024-07-21",
  "next_analysis": "2024-07-28T09:00:00Z",
  "channel_performance": {
    "x": { "total_posts": 47, "avg_engagement": 2.1, "baseline": 2.1, "subscribers_gained": 123 },
    "youtube": { "total_videos": 3, "avg_watch_time": 18, "baseline": 18, "subscribers_gained": 45 },
    "substack": { "total_emails": 2, "avg_open_rate": 42, "baseline": 42, "subscribers_gained": 67 }
  },
  "winners": [
    { "platform": "x", "title": "Thread on AI regulation...", "metric": "engagement_rate", "value": 4.2, "baseline": 2.1, "delta_pct": 100, "subscribers_gained": 32 },
    ...
  ],
  "losers": [...],
  "insights": [
    { "type": "pattern", "title": "Polarizing topics drive 2.5x engagement", "description": "...", "confidence": 0.85 },
    ...
  ],
  "actions": [
    {
      "id": "action_001",
      "priority": "high",
      "title": "Publish threads 2x weekly at 9–11 AM ET",
      "description": "...",
      "effort_hours": 2,
      "expected_impact_subscribers": "5-8/week",
      "deadline": "2024-07-28",
      "assigned_to": null,
      "status": "not_started",
      "notes": []
    },
    ...
  ]
}
```

### 6.1.2 Data Sources & Auth
| Platform | API | Auth | Refresh Cadence |
|----------|-----|------|-----------------|
| X | Twitter API v2 | OAuth 2.0 Bearer Token | Weekly or on-demand |
| YouTube | YouTube Analytics API | OAuth 2.0 (YouTube Channel) | Weekly or on-demand |
| Substack | Google Sheets API | OAuth 2.0 (Google Drive) | Weekly or on-demand |

### 6.2 Processing Pipeline
1. **Fetch:** Pull data from all three sources
2. **Transform:** Normalize metrics, calculate baselines, identify outliers
3. **Analyze:** Platform-specific insights (see Section 4)
4. **Synthesize:** Cross-platform patterns (if applicable)
5. **Report:** Format and deliver output

### 6.3 Computation
- Baseline = rolling 4-week median per metric per platform
- Outlier threshold = >30% for X, >50% for YouTube, >25% for Substack (configurable)
- Subscriber correlation = week-over-week delta aligned to post publication

---

## 6.4 Recommendation Prioritization & Team Feasibility

For a small team, not all actions are equal. Agent should rank recommendations by:

1. **Impact potential:** Subscriber growth impact / effort required (ROI)
2. **Effort:** Time to implement (hours)
3. **Dependencies:** Does it require external tools, approvals, or new processes?
4. **Frequency:** One-time setup vs. recurring effort

**Example ranking:**
```
HIGH PRIORITY (Do this week):
- "Post threads Tue/Thu 9–11 AM" 
  → Impact: +15–20% engagement | Effort: 2 hours setup | ROI: 10x

MEDIUM PRIORITY (This month):
- "Add captions to YouTube Shorts"
  → Impact: +8–10% watch time | Effort: 1 hour/video | ROI: 8x

LOW PRIORITY (Try next quarter):
- "Test new subject line format on Substack"
  → Impact: +5% open rate | Effort: ongoing | ROI: 3x
```

**Team capacity note:** Actions should assume a small team (2–3 people doing content + ops). Avoid suggesting "post 5x daily" if the team capacity is 2–3 posts/week. Instead, prioritize the highest-ROI actions within realistic capacity.

---

## 7. Success Metrics

**For the agent:**
- ✅ Report generated within 30 seconds of user request
- ✅ Accuracy: insights reproducible from raw data (no hallucinations)
- ✅ Actionability: user implements ≥1 recommendation per month

**For the user:**
- ✅ Subscriber growth accelerates (target: +15–20% MoM)
- ✅ Content ROI improves (higher engagement per post)
- ✅ Time saved: 30–45 min/week previously spent analyzing dashboards

---

## 8. Action Execution & Feedback Loop

Small teams need a workflow that turns recommendations into execution and learnings.

### 8.1 Typical Week Flow

**Sunday 9 AM:** Agent runs, generates report, posts to Hyperagent dashboard
↓
**Monday AM:** Team lead reviews report, assigns 1–2 actions to writers/ops
↓
**Mon–Wed:** Team executes assigned actions (schedule threads, adjust format, start A/B test)
↓
**Next Sunday:** Agent re-runs; new report shows performance delta vs. previous week
↓
**Continuous:** Team notes results, learnings, blockers in dashboard; agent incorporates patterns in future recommendations

### 8.2 Integration Points with Team Workflow

**Calendar/Scheduling:** Action says "Post 2x/week at 9–11 AM"
- Team uses their existing calendar/scheduling tool (Later, Buffer, native platform scheduler)
- Agent doesn't automate posting; it informs the schedule

**Content templates:** Action says "Use 3-part thread format"
- Agent could suggest a template or link to a previous winning thread
- Team adapts/writes new content using that template

**Analytics review:** Action says "A/B test subject lines"
- Team logs test results in dashboard notes
- Next week's report incorporates learnings (e.g., "You tested X; results show +5% open rate. Keep it.")

**Blockers & feedback:** Team can mark action as "Deprioritized" with reason
- E.g., "Pausing YouTube uploads due to resource constraints; resume in 2 weeks"
- Agent future reports respect known constraints

---

## 9. Scope: In & Out

### 9.1 In Scope
- **Organic social only:** X, YouTube, Substack performance analysis
- Historical analysis (July 1 onwards)
- Platform-specific KPI analysis
- Anomaly detection (winners/losers)
- Actionable recommendations (scheduling, format, content strategy)
- Weekly automation + on-demand execution
- Team collaboration features (assignment, notes, status tracking)

### Out of Scope
- Paid advertising or promotion analysis
- Competitor benchmarking
- Content creation (suggestions only, not generation)
- Cross-platform audience overlap analysis (v2)
- Predictive forecasting (v2)
- Automatic scheduled posting (recommendations only; team executes)
- Influencer or audience sentiment analysis

### 9.2 Out of Scope Justification
**Excluded because:**
- Paid media requires different metrics/optimization loops; separable product
- Automatic posting removes team agency and oversight
- Competitor analysis adds complexity; focus on own performance first
- Predictive models require longer history; start with pattern detection

---

## 10. Open Questions & Future Considerations

1. **Subscriber correlation:** Is there a reliable way to attribute subscriber growth to specific posts? (Timing lag, multi-touch, etc.)
2. **Baseline personalization:** Should baselines differ by day-of-week or content category? (Likely yes, but adds complexity.)
3. **Alert thresholds:** Should the agent alert on *negative* performance (e.g., "engagement dropped 40% this week")?
4. **Cohort analysis:** Should we segment insights by audience segment (paid vs. free Substack subscribers)?
5. **Content categorization:** Should the agent auto-tag posts (e.g., "market analysis," "personal story," "call-to-action")? Or rely on user tags?
6. **Frequency tuning:** Start with weekly; scale to bi-weekly or monthly if analysis paralysis emerges.

---

## 11. Timeline & Milestones

| Phase | Timeline | Deliverable |
|-------|----------|-------------|
| **v0.1** | Week 1 | X API integration + basic performance review |
| **v0.2** | Week 2 | YouTube API integration |
| **v0.3** | Week 3 | Substack Google Sheets integration |
| **v1.0** | Week 4 | Full agent workflow + report generation + weekly automation |
| **v1.1** | Week 5 | On-demand trigger + dashboard/email delivery |

---

## 12. Appendix: Example Data Schema

### X Post Record
```json
{
  "post_id": "1234567890",
  "created_at": "2024-07-15T10:30:00Z",
  "text": "Thread on AI regulation...",
  "public_metrics": {
    "impression_count": 4200,
    "like_count": 89,
    "reply_count": 12,
    "retweet_count": 34,
    "quote_count": 8,
    "bookmark_count": 16
  },
  "author_followers_at_post": 12400,
  "followers_gained_7d": 32
}
```

### YouTube Video Record
```json
{
  "video_id": "abc123def456",
  "published_at": "2024-07-15T14:00:00Z",
  "title": "Building a RAG system",
  "analytics": {
    "views": 1245,
    "watch_time_hours": 356,
    "average_view_duration_sec": 1680,
    "click_through_rate_pct": 3.2,
    "subscriber_gain": 18
  }
}
```

### Substack Email Record
```json
{
  "email_id": "sub_12345",
  "sent_at": "2024-07-15T09:00:00Z",
  "subject": "Venture debt deep dive",
  "metrics": {
    "open_rate_pct": 58,
    "click_through_rate_pct": 12.5,
    "subscriber_gain": 22,
    "subscriber_churn": 2
  }
}
```

---

## Document Info
- **Owner:** [Product Lead / Creator Name]
- **Last Updated:** [Date]
- **Status:** Draft