weekly-brief

Files (13)

• SKILL.md
• P1_output_schema.yaml · references/
• P1_prompt.txt · references/
• P1_render_package.html · references/
• P2_output_schema.yaml · references/
• P2_prompt.txt · references/
• P2_render_package.html · references/
• P3_output_schema.yaml · references/
• P3_prompt.txt · references/
• P3_render_package.html · references/
• assemble_pdf.py · scripts/
• download_thumbnails.py · scripts/
• qa_check.py · scripts/

SKILL.md (first lines)

# Weekly Competitive Intelligence Brief

Build a polished 3-page PDF competitive intelligence report from an Adology project's scope.
Each page is a self-contained "slide" with its own data pipeline, rendered as HTML via
WeasyPrint, then merged into a single PDF. Every page includes real post thumbnails.

## Architecture Rules

**DO NOT use subagents.** Build all 3 pages yourself, sequentially, in the main thread.
Subagents caused cascading failures in production — they made unchecked decisions,
crashed the sandbox disk, and couldn't be course-corrected.

**Thumbnails are MANDATORY.** Every scoreboard card, spotlight, trend card, and coaching
card must have a real thumbnail image from the actual post. The skill includes a bundled
script (`scripts/download_thumbnails.py`) that handles downloading, resizing, and
base64-encoding. You run this script — it produces a JSON file mapping image URLs to
small base64 data URIs. Then you insert those data URIs into the HTML `<img>` tags.
There is no alternative to this. Do not skip thumbnails. Do not use CSS placeholders.
Do not use colored rectangles with initials. Download the real images.

**Coverage is part of the brief, not a caveat you drop.** A weekly brief is a claim about
a window. Say which sources actually cover that window and name the ones that don't — by
name, on the page. A stale source that goes unmentioned turns a data gap into a false
finding ("Brand X went quiet this week" when nobody fetched Brand X).

## Path Conventions

This skill's shell examples use two literal placeholders that you must substitute
before running any command:

- `{skill_path}` — the absolute path to this skill's directory (the directory
  containing this `SKILL.md`). At runtime this resolves to something like
  `/Users/<you>/.../skills/weekly-brief`. Use it to invoke bundled scripts under
  `scripts/` and to read reference files under `references/`.
- `{output_dir}` — the working/output directory for this brief's HTML, JSON,
  and final PDF artifacts. Pick a fresh directory per run (e.g.
  `outputs/<project_name>-<week_end>/`) and substitute it consistently across the
  whole workflow.

If you see either placeholder in a command, **replace it with the actual path
before executing**. Do not pass the literal string `{skill_path}` to a shell.

## Overview

The brief has three pages:

- **Page 1 — Visual Scoreboard + Intel Strip**: Top 6 posts across brands (scoreboard
  grid with real thumbnails), primary brand spotlight, stat pills, insight bar, and a
  3-column intel strip with hook/creative/AI analysis.
- **Page 2 — Market Signals**: Industry news headlines with strategic signals, audience
  conversation, hook performance charts, brand engagement leaderboard, paid presence,
  and a 3-card action board (Defend / Attack / Watch).
- **Page 3 — Social Trends + Coaching**: 5 trend cards (with real thumbnails and source
  links), plus 3 coaching cards with real thumbnails showing how to optimize existing
  primary brand posts with specific data-backed tweaks.

## Workflow

### Phase 0 — Orient and Fix the Scope

1. **Ask for inputs** (if not already provided):
   - `primary_brand` — the brand being briefed
   - the portfolio or project to brief on
   - `week_start` / `week_end` — the Monday–Sunday window (default: last full week)

2. **Orient**: `whoami` → `list_portfolios` → `list_projects({ portfolioId })`. Reuse an
   existing project whose scope matches the brief, or `create_project` for a fresh one.
   The project IS the scope — everything the brief reports comes from what that project
   covers.

3. **Read the scope and its coverage**: `get_project({ projectId })` returns `dataScope`
   plus the full per-source access state — `access.expiredSources` (covered only through
   a date) and `access.ungrantedSources` (tracked but never acquired). Write these two
   lists down now; they become the coverage note on the delivered brief. A project with
   an empty scope reads the portfolio's whole tracked universe; `update_project_scope`
   with `replace` pins it to exactly the sources this brief is about.

4. **Check the window has enough behind it**: `aggregate` over the brief window —
   `groupBy: ['brand']`, `filters: { feedType: ['brand'], from: week_start, to: week_end }`,
   `measures: [{ field: '*', fn: 'count', as: 'n' }]`. Three or more brands and 20+ items
   is a workable brief. Below that, say so before building.

5. **If the window is thin because coverage is stale**, plan a pull: `pull_data({ projectId,
   candidates })` splits the targets into `readyNow` (attached free, already current) and
   the gap it quotes. **`confirm_pull` charges credits** — show the user the quoted cost
   and the sources it covers, and call it only after they approve. Then `check_pull({ runId })`
   to watch it land. If they decline, build the brief on what's covered and name the gap.

### Phase 1 — Pull Shared Data (One Pass)

Pull the core data once; multiple pages read from it. This keeps the pages consistent with
each other and keeps the round-trips down.

**Step 1A — Discover the label vocabulary.** Call `list_labels({ projectId })` (or
`get_table_data({ projectId, listDimensions: true })`) to see which dimensions this scope
actually carries. Use those exact dimension names in every later call — a dimension the
scope doesn't have produces an empty table, not an error.

**Step 1B — Time series and leaderboard (P1 stat pills + P2 leaderboard).**
`aggregate` with `groupBy: ['time','brand']`, `timeBucket: 'week'`,
`measures: [{ field:'*', fn:'count', as:'n' }, { field:'likes', fn:'median', as:'medianLikes' }]`,
`filters: { feedType:['brand'], from: week_start, to: week_end }`. Every row carries `n`.
A ranking call comes back split: `rows` cleared the reliability floor, `directionalRows`
sat below it. **Rank from `rows`.** A `directionalRows` entry may appear as texture with
its `n` stated ("two posts, so read it as a signal"), never as a leaderboard position.

Run the same call with `filters.excludeBoosted: true` for the organic-only cut. The
difference between the two is the paid-presence read on Page 2 — and if you report the
organic number, say that you excluded boosted posts.

**Step 1C — This week's outliers (P1 scoreboard + P3 trends).**
`query_items` with `projectId`, `feedType: ['brand']`, `startDate`/`endDate` set to the
window, `sortBy: 'likesMultiple'`, and `outlierMetric: 'likes'` + `minOutlierMultiple: 2`.
This ranks posts by lift against their own source baseline, so a small brand's breakout
can outrank a big brand's routine post — which is what a competitive brief is for. Each
row carries `likesMultiple` alongside `sourceMedianLikes`: **never print a lift multiple
without its baseline.** Rows also carry `isOutlier`, `boosted`, and `externalUrl`.

Walk the ranked list top-down and keep the first post per brand until you have 6 unique

From adologyai/content-intelligence-plugin, Apache-2.0.

More from adologyai/content-intelligence-plugin