refresh-peec-aeo-snapshot

name	refresh-peec-aeo-snapshot
description	Refresh the Peec AEO snapshot for the docs cross-link audit. Use when the snapshot in aeo-snapshots/docs/example-topic/ is stale (older than 14 days) or when the scheduled cloud audit posted a stale-snapshot Slack alert. Must run in a local agent session where Peec MCP is authenticated.

Refresh Peec AEO snapshot

Refresh the Peec snapshot that the scheduled AEO cross-link audit cloud agent reads before each run.

This skill must run in a local agent session. Peec MCP requires OAuth authentication, which is not available in cloud agent environments. Do not attempt to run this in a cloud agent — it will fail silently and produce a useless export.

Why this exists

The scheduled docs cross-link audit reads a pre-exported Peec snapshot from the buzz repo because cloud agents cannot authenticate with Peec directly. This snapshot must be refreshed on a cadence that keeps it under 14 days old. If it exceeds 14 days, the cloud audit agent aborts the run and posts a stale-snapshot Slack alert instead of auditing docs or opening a PR.

Pre-flight check

Before starting:

1. Verify Peec MCP is connected. You should see the Peec MCP server active in your local session. If it is not connected, add it to your local MCP configuration and restart the session before continuing.
2. Verify write access to the buzz repo.
3. Pull latest main in the buzz repo:

git -C <path-to-buzz> pull

Replace the path above with your local buzz repo path if different.

Workflow

Step 1: Collect raw Peec data

Run this prompt in your current local agent session using the Peec MCP:

Use Peec MCP to collect AEO source signals for your docs, focused only on your chosen <TOPIC_AREA>.

Create a raw JSON export at /tmp/peec-aeo-export.json with this structure:
- project: the Peec project id and name for your brand
- start_date and end_date: last 30 days
- summary: 2-4 sentence human-readable summary of the relevant Peec signals
- prompts: raw output from list_prompts, filtered or annotated for <TOPIC_AREA> relevance
- search_queries: raw output from list_search_queries for the relevant prompts or topic
- actions_overview: raw output from get_actions with scope=overview
- actions_drilldowns: follow-up get_actions outputs for the most relevant owned/editorial/reference/UGC slices
- url_report: relevant source URL rows from get_url_report if useful
- candidate_docs_areas: path hints in docs that likely matter
- open_questions: questions a docs reviewer should consider

Use source data only. Do not invent Peec recommendations. Keep the export compact enough for a cloud agent to consume.

Confirm that /tmp/peec-aeo-export.json was written and contains a non-empty project field and at least a few prompts rows before continuing.

Step 2: Normalize the snapshot

Run the normalization script from the buzz repo root:

python3 <path-to-buzz>/scripts/generate_peec_aeo_snapshot.py \
  --input /tmp/peec-aeo-export.json \
  --output-dir <path-to-buzz>/aeo-snapshots/docs/example-topic

Replace the paths above with your local repo path if different.

This writes four files:

• aeo-snapshots/docs/example-topic/latest.json
• aeo-snapshots/docs/example-topic/latest.md
• aeo-snapshots/docs/example-topic/history/YYYY-MM-DD.json
• aeo-snapshots/docs/example-topic/history/YYYY-MM-DD.md

Step 3: Spot-check the output

Verify the snapshot looks valid before committing:

python3 -c "
import json
d = json.load(open('<path-to-buzz>/aeo-snapshots/docs/example-topic/latest.json'))
print('generated_at:', d['generated_at'])
print('prompts:', len(d.get('prompts', [])))
print('query_clusters:', len(d.get('query_clusters', [])))
"

Expected: today's date in generated_at, and at least a few prompts. If the snapshot is empty or malformed, check whether the Peec MCP export in step 1 was complete.

Step 4: Commit and push

cd <path-to-buzz>
git add aeo-snapshots/docs/example-topic/
git commit -m "chore: refresh peec aeo snapshot $(date -u +%Y-%m-%d)"
git push

Confirm the push succeeds. The scheduled cloud audit agent reads the snapshot from the committed buzz repo, so the push must complete before the next audit run.

Step 5: Verify (optional)

git -C <path-to-buzz> show --stat HEAD

After refreshing

The next scheduled audit run will automatically pick up the fresh snapshot. No additional action is needed — the cloud agent runs on its own weekly schedule.

If you want to trigger the next audit immediately before the scheduled window, use the <CLOUD_PRODUCT> web app or CLI to start a new run of the aeo_crosslink_audit scheduled agent.

Freshness target

Refresh every 10–12 days to stay comfortably under the 14-day threshold, even if a scheduled run is slightly delayed. The current snapshot age is always visible in aeo-snapshots/docs/example-topic/latest.json under generated_at.