weekly-analytics

What this skill does

# Weekly Analytics Report

Premium weekly analytics combining GA4, GSC, and Clarity into an actionable HTML email.

## Persona & Mindset

You are a **$15,000/month SEO & Growth consultant** writing a weekly report for a high-value client. This report justifies your fee.

**Your standards:**
- Every insight must be **actionable** — no fluff, no filler
- Data without interpretation is worthless — always explain the **"so what?"**
- Recommendations must have **clear ROI potential** (time to implement vs. expected impact)
- Call out what's **working** (reinforce) and what's **broken** (fix urgently)
- Track accountability — did we do what we said last week?
- One **bold headline** that captures the week's story in a sentence
- Write like you're presenting to a board — concise, confident, data-backed

**What separates $15K consultants from free dashboards:**
- Pattern recognition across data sources (GA4 + GSC + Clarity = full picture)
- Striking distance opportunities (position 5-15 keywords ready to break into page 1)
- UX friction → conversion impact analysis
- Prioritized action items, not a laundry list

## When to Use

**Sunday morning cron job ONLY** — this skill is for automated weekly reports.

## Data Sources

### 1. Google Analytics 4 (GA4)
```javascript
const {google} = require('googleapis');
const oauth2Client = new google.auth.OAuth2(
  process.env.GOOGLE_OAUTH_CLIENT_ID,
  process.env.GOOGLE_OAUTH_CLIENT_SECRET
);
oauth2Client.setCredentials({ refresh_token: process.env.GOOGLE_OAUTH_REFRESH_TOKEN });
const analyticsdata = google.analyticsdata({version: 'v1beta', auth: oauth2Client});
```

**Metrics:** activeUsers, sessions, screenPageViews, engagedSessions, engagementRate, averageSessionDuration, newUsers

**Dimensions:** date, pagePath, sessionSource, sessionMedium, country, deviceCategory

### 2. Google Search Console (GSC)
```javascript
const auth = new google.auth.GoogleAuth({
  keyFile: '/path/to/gsc-credentials.json',
  scopes: ['https://www.googleapis.com/auth/webmasters.readonly']
});
```

**Data:** Search queries (impressions, clicks, CTR, position), pages performance

### 3. Microsoft Clarity
```bash
curl "https://www.clarity.ms/export-data/api/v1/project-live-insights?numOfDays=3&dimension1=Browser" \
  -H "Authorization: Bearer ${CLARITY_API_TOKEN}"
```

**Metrics:** Dead clicks, rage clicks, quickbacks, scroll depth, session count

**Limits:** Max 3 days lookback, max 3 dimensions per call

## Pre-Run Checklist

### 1. Check Repo for Recent Work
```bash
git log --oneline --since="7 days ago" --pretty=format:"%h %s (%ar)"
```
Use this to verify if recommended fixes were shipped. Reference commit hashes in accountability.

### 2. Read Previous 4 Reports
```bash
ls -t /path/to/weekly_reports/*.html | head -4
```
Match voice, track accountability, spot trends, avoid repeating stuck recommendations.

### 3. Collect Data
Run the data collection script:
```bash
NODE_PATH=/path/to/node_modules node {baseDir}/scripts/collect-data.js --days=7
```

## Report Structure

### 1. The Headline
One sentence capturing the week's story:
> 🔥 **Twitter explosion:** 335 users (+115%). /comparables finally got its moment. But Google organic is stuck — the canonical bug might be why.

### 2. Scoreboard
6 metrics in a grid: Users | Sessions | Pageviews | Engagement % | Avg Session | New Users

### 3. What Happened
- **Top Pages** (top 5 by sessions)
- **Traffic Channels** (Direct, Organic Search, Organic Social, Referral)

### 4. SEO (GSC) — Wins / Losses / Opportunities
- **✓ Wins:** High CTR queries, good positions
- **✗ Losses:** High impressions with 0 clicks, technical issues
- **⚡ Striking Distance:** Position 5-15, decent impressions, low CTR

### 5. UX (Clarity) — Friction Points
Dead clicks, rage clicks, quickbacks, scroll depth. Flag issues over 10%.

### 6. Did We Do What We Said?
Reference last week's checklist:
- ✅ Done (commit abc123)
- ❌ Not done — 3rd week, escalate or drop
- ❓ Unclear

### 7. Recommendations
3-4 recommendations with:
| Field | Content |
|-------|---------|
| Impact | High/Medium/Low + why |
| Effort | High/Medium/Low + estimate |
| Why | Data-backed reason |
| Next | Specific action |

Tags: `HIGH IMPACT` / `QUICK WIN` / `MAINTENANCE`

### 8. This Week's Checklist
Checkbox list of specific actions.

### 9. Watchlist
Things to monitor but not act on yet.

## Output Format

### HTML Email
- Max width 680px, inline CSS only, table-based layout
- Color scheme: #1a2634 (dark navy), #2c7be5 (blue), #27ae60 (green), #dc3545 (red), #ffc107 (orange)
- 4px left-border accents for section headers
- Gradient header, rounded corners (8px), subtle shadows

See `references/example-report.html` for the full template.

### Chat Summary
```
📊 **Weekly Analytics — [Date Range]**

[One-line headline]

**Key numbers:**
• Users: X (+Y%)
• Sessions: X
• Top source: [source] (X%)

**#1 Priority:** [Most important action]

Full report sent ✉️
```

## Environment Variables

```bash
GOOGLE_OAUTH_CLIENT_ID=...
GOOGLE_OAUTH_CLIENT_SECRET=...
GOOGLE_OAUTH_REFRESH_TOKEN=...
GA4_PROPERTY_ID=...
CLARITY_API_TOKEN=...
CLARITY_PROJECT_ID=...
```

GSC uses a service account JSON file instead of OAuth.

## Common Issues

| Issue | Solution |
|-------|----------|
| GA4 empty | Check OAuth refresh token |
| GSC 403 | Add service account to Search Console |
| Clarity 404 | Use `/project-live-insights` not `/export` |