polecat-x-report

PolecatX Report Generator

Generate a standalone HTML report from PolecatX media monitoring data, with bespoke D3 visualisations and analysis.

Before you start

1. Check POLECATX_API_KEY is set. If not, tell the user to add it to .claude/settings.local.json under "env" and stop.
2. Skim the templates you'll build from:
   • templates/report-shell.html — the canonical page shell (chrome, CSS, helpers). Copied verbatim.
   • templates/components.md — suggested body snippets (sections, cards, tables).
   • design-tokens.md — palette and conventions for the chart code you write.

Inputs

Ask for anything not already provided:

• Entity — name or ID (required). If a name, resolve to an ID first.
• Date range — start and end as UTC ISO 8601, e.g. 2024-01-01T00:00:00Z (required). Never invent or guess a range. If the user hasn't given one and none is clearly implied by their request (e.g. "last week", "Q1 2026"), stop and explicitly ask for it before fetching.
• Focus prompt (optional) — e.g. "focus on ESG risks" or "look for IPO coverage". If omitted, find what's most interesting in the data.
• Filters (optional) — sentiment, esg_controversies, locations, source_categories, etc.

Workflow

1. Resolve entity ID

If given a name (not an ID starting with organization_ / person_ / topic_):

curl -s -X POST -H "Authorization: Bearer $POLECATX_API_KEY" -H "Content-Type: application/json" \
  -d '{"name": "<name>", "limit": 5}' \
  "https://x.polecat.com/beta/entities/search"

If no match, offer to create the entity (see polecat-x-api skill for the create call) before continuing.

2. Fetch and save events

POST /events triggers a scan and returns fresh data. Pipe directly to file — do not load the full response into context:

curl -s -X POST -H "Authorization: Bearer $POLECATX_API_KEY" -H "Content-Type: application/json" \
  -d '{ "entity": ["<entity-id>"], "start": "<start>", "end": "<end>" }' \
  "https://x.polecat.com/beta/events" > <slug>.json

Filename convention: {entity-slug}-{start-date}--{end-date}.json where entity-slug = entity name lowercased with spaces replaced by hyphens, dates are YYYY-MM-DD only (e.g. spacex-2026-06-09--2026-06-15.json).

Add optional filter fields to the JSON body as needed. Then read a lightweight summary for analysis:

cat <slug>.json | python3 -c "
import json,sys
d = json.load(sys.stdin)
for e in sorted(d['data']['events'], key=lambda x: -x['score']):
    print(f\"{e['score']:.1f} {e['sentiment'][:3]} {e['summary'][:80]}\")
print('timeSeries points:', len(d['data']['timeSeries']))
"

3. Analyse

What the score is. Each event's score is the Net Sentiment Score, a 0–100 sentiment scale: 0 = very negative, 50 = neutral, 100 = very positive (docs). It is not a measure of importance or prominence — a 100 means most positive, not most newsworthy. Reach/prominence comes from the number of sources and the scoringFactors (traffic, spread, tier, credibility). The timeSeries is the Net Sentiment Score trended over the period.

Examine data.events and data.timeSeries. Apply the focus prompt if provided, otherwise look for:

• Overall sentiment lean (how far above/below the neutral 50 line) and its range
• The most positive and most negative events (extremes in either direction)
• Highest-reach events — by source count and spread/traffic
• Sharp moves in the time series (Net Sentiment Score spikes or dips)
• ESG controversies present
• Recurring themes or clusters in summaries

Identify 2–4 narrative threads that will become report sections.

4. Generate HTML report

Build the report from the templates — don't write the page from scratch:

1. Copy the shell. cp templates/report-shell.html <slug>.html. The shell carries the canonical <style>, header, lede, stat row, data note, tooltip, and standard JS helpers. Leave all of that as-is — it's what keeps every report visually identical.
2. Fill the {{PLACEHOLDERS}} in the header, lede, stat row and data note with real values (all derivable from DATA).
3. Compose the body inside <main id="report-body"> using the snippets in templates/components.md. Pick the sections, order, and charts that fit the data and the narrative — this is the part that should vary between reports. Drop or adapt any snippet; if the user asked for a specific structure, follow that.
4. Write the chart code in the <script> block where marked, drawing each chart into its .chart-wrap container. Follow the chart conventions in design-tokens.md.
5. Inject the data from the saved JSON file:

python3 -c "
f = '<slug>.html'
open(f, 'w').write(open(f).read().replace('__POLECAT_DATA__', open('<slug>.json').read()))
"

This replaces the placeholder with the raw file contents in one operation — no reading JSON into context, no risk of mangling special characters.

Choosing what goes in the body

Lead with what the data makes most striking — the strongest sentiment (very positive or very negative), the highest-reach story, a major ESG controversy, or a sharp move in the time series. Don't assume a high score means "biggest story" (see the score note above). Give each phenomenon the chart that shows it best:

Phenomenon	Good chart type
Net Sentiment Score over time	Line chart with sentiment-coloured dots
Sentiment split	Donut or horizontal stacked bar
Source breadth / reach	Horizontal bar (events or hostnames by count)
ESG breakdown	Bar or grouped bar by controversy type
Score distribution	Histogram
Top events	Styled table (no chart needed)

Hard rules

• Don't touch the shell's <style>, container width, header, lede, stat-row, data-note or tooltip unless the user explicitly asks — these are the consistency anchor.
• Call the score "Net Sentiment Score". Use that full name in chart titles, axis labels and tooltips, and the first time you mention the score in any paragraph; after that "score" is fine. Never describe a high score as more important or more newsworthy — it means more positive.
• Every number in prose must be computable from DATA — no hardcoded counts or scores.
• Charts read from events / timeSeries — never from numbers copied out of the data.
• Use only the colours, fonts and chart conventions from design-tokens.md; categorical series use the 12-colour palette in order.