Insights-Driven Refresh

The prompt

Use real traffic to decide which published pages need a refresh, then file a prioritized queue. Do not edit the posts themselves.

Step 1: find out what is actually underperforming.
1. Call read_performance with dimension=path, range=30d, metric=events, order=bottom, limit={{max_objects}}, and path_prefix={{path_prefix}}. These are the pages readers are not reaching.
2. Call read_performance with dimension=path, range=30d, metric=events, order=top, limit=5 and the same path_prefix, for context on what does work on this site.
3. Match each underperforming path to its object by slug: the last segment of the path is usually the object slug. Use get_objects to read the ones you matched. Say so in the queue entry if a path has no matching object, rather than guessing.

If Insights returns no data at all, the project either has no tracker installed or has no traffic yet. Do not stop and do not invent numbers. Fall back to age: pick published posts older than 180 days or with an empty last_reviewed field, oldest first, and record "selected by age, no analytics data" as the traffic_signal on every entry you file.

Step 2: judge each candidate.
4. Review at most {{max_objects}} posts. Stop when you reach that number, even if more remain. This keeps the run inside the token budget.
5. Read each body and look for concrete decay:
   - Facts tied to a specific year, quarter, or price that has since moved on.
   - References to deprecated APIs, versions, tools, or endpoints.
   - Claims hedged as "at the time of writing" that now need a number.
   - Sections that were thin when written and are now the reason the page underperforms.
6. Low traffic is not automatically a content problem. A page can be thin, badly titled, or simply about a topic nobody searches for, and the fix is different in each case. Say which one you think it is.

Step 3: file the queue.
7. Create one object in the refresh-queue type per post worth refreshing, with:
   - run_date: today
   - target_title and target_slug: the post you reviewed
   - priority: High, Medium, or Low. High means the post is actively misleading a reader today, or it is losing traffic it used to earn.
   - traffic_signal: the measured reason you picked it, with the number and the window, e.g. "31 visitors in 30d, bottom of the range". This is the evidence, so never leave it empty.
   - reasons: a short markdown list, one line per specific problem, quoting the phrase in the post that dates it.
   - suggested_edits: what to change, specific enough that a writer can act without rereading the whole post.
8. Skip posts that have aged well. An empty queue entry is worse than no entry.

Never modify the posts, their titles, or their metadata. This workflow proposes work; a human decides what to do with it.

If every post you reviewed has aged well, create a single refresh-queue entry with priority Low, target_title "No refresh needed", and reasons explaining what you checked. A run that reports honestly is more useful than one that invents work.

What it needs to be at its best

Install the Cosmic Insights tracker on the site this content publishes to, and give it enough traffic to rank. With that in place, candidates are chosen by what readers actually do, and every queue entry carries the number behind it.

Without it, the workflow still runs. It falls back to selecting the oldest unreviewed posts and labels each entry "selected by age, no analytics data", so you can tell the difference between a measured judgment and a guess.

Analytics windows go out to 90 days, so this finds what is underperforming now rather than comparing against last year.

Why it does not edit

Refreshing a post is an editorial decision. The queue gives an editor the evidence, the traffic number, and the specific change to make, which is the part that takes the longest, and leaves the judgment where it belongs.