Aeo Report

AEO Report

> Source: github.com/psyduckler/aeo-skills > Part of: AEO Skills Suite

Reads aeo-data/*.json (evidence files written by aeo-baseline) and produces a shareable visibility report. The skill that makes the daily cron actually useful.

Requirements

• Python 3.9+ (stdlib only)
• At least one aeo-evidence-v1 file in your data directory
• No API keys (this skill never calls a provider)

Usage

# Default: read aeo-data/, write Markdown + HTML to aeo-reports/
python3 scripts/report.py

# Specify directories
python3 scripts/report.py --data-dir custom-data --output-dir custom-reports

# Markdown only (good for piping)
python3 scripts/report.py --format md

# Print to stdout (good for one-off review)
python3 scripts/report.py --stdout

Output filenames are timestamped: -report.md and -report.html.

Options

| Option | Default | Description | |---|---|---| | --data-dir | aeo-data | Directory of evidence files | | --output-dir | aeo-reports | Where to write reports | | --format | all | md \| html \| all | | --stdout | — | Print Markdown to stdout instead of writing files |

What's in the report

Executive summary

• Average visibility score across all prompts (latest run)
• Trend vs. first run (if multiple runs)
• Count of decay alerts
• Count of hub-page candidates

Per-prompt detail

For each prompt:

• Latest visibility score, mention rate, citation rate (with Wilson 95% CIs)
• Average citation position (when cited)
• Embedded SVG chart of visibility score over time (when ≥2 runs exist)
• Top 5 entities from the entity universe
• Decay flag if citation rate has fallen
• Cannibalization flag if multiple owned URLs compete
• Competitor share-of-voice shifts

Cross-prompt sections

• Hub-Page Opportunities — owned URLs cited across multiple prompts
• Decay Alerts — prompts with declining citation rate

Detection thresholds

| Signal | Trigger | |---|---| | Decay | Trailing 3-run mean is ≥20% below leading 3-run mean (HIGH if ≥50%, MEDIUM ≥30%, LOW otherwise). Needs ≥4 runs. | | Cannibalization | ≥2 distinct owned URLs are each cited in ≥2 samples within the latest run. | | Hub page | A URL is cited for ≥2 prompts AND covers ≥30% of tracked prompts in the latest run. | | Competitor share shift | First-run vs latest-run share differs by >5 percentage points. |

All thresholds live as constants at the top of scripts/report.py. Bump them for your workspace if needed.

SVG charts

Charts are hand-rendered SVG (no matplotlib, no pip install). Each chart is embedded inline in the HTML output via a `` placeholder in the Markdown. Currently:

• One line chart per prompt showing visibility score over time (only when ≥2 runs exist)

Future charts (deferred): entity-frequency bar charts, competitor-share stacked area, citation-position over time.

Pure analysis

This skill is read-only. It never:

• Calls a provider API
• Mutates evidence files
• Requires an API key

So it's safe to run from CI, in pre-commit hooks, or anywhere else.

Pairs With

• aeo-init — sets up the workspace
• aeo-baseline — produces the evidence files this skill reads
• aeo-track — schedules baselines so trends accumulate
• aeo-optimize (coming) — reads the latest baseline + report and produces a Markdown work queue

Notes

• Reports are append-only by default (one file per invocation). Delete old reports manually if directory growth is a concern.
• The HTML output is a single self-contained file (inline CSS + SVG). Email-safe, easy to share.
• For very large workspaces (50+ prompts × 365 days), report generation is O(N) over evidence files — typically subsecond.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: psyduckler
• Source: psyduckler/aeo-skills
• License: MIT

Install and usage instructions live in the source repository linked above.