1---2name: refresh-audit3description: >-4 Audits one published B2B SaaS page against today's search results and today's standards (claims and sources,5 coverage, format, answers near the top, voice, title and description, links, dates) and returns a ranked edit6 list in 3 tiers with NO CHANGE, STANDARD REFRESH, SIGNIFICANT REFRESH, FULL REWRITE, CONSOLIDATE or BLOCKED. Use it7 on a page content-triage marked for refresh, or any page someone wants to update. Not for choosing which pages to8 refresh (use content-triage) or for rewriting the page (the edit list goes to the writer).9license: MIT10compatibility: >-11 Works in Claude, ChatGPT, Codex, Cursor and any agent that reads SKILL.md. Reads the page and the live results if12 the agent can browse, otherwise pasted text and outlines. Python 3 is optional, for the gap count and the date rule.13metadata:14 author: SHAKEUP15 version: "1.0.0"16 stage: check17 plugin: seo-ai-search18 homepage: https://www.shakeuphq.com/skills/refresh-audit19---20 21# Refresh audit22 23Turns "this page needs updating" into a short, ranked list of the edits that matter, and protects the parts of the page that already work.24 25## Purpose26 27- One job: audit one published page and return a tiered edit list with a refresh verdict.28- Stage: check. It ends in a verdict with severities on every finding.29- A refresh is not a rewrite. Most pages need targeted edits; the audit calls for a rewrite only when the page serves the wrong intent.30- It never edits the page, and never moves a page's "updated" date without a substantial change.31 32## Use when / not33 34| Situation | Use |35| --- | --- |36| A page is in `content-triage`'s refresh bucket | this skill, on the priority refreshes first |37| A page's facts, tools or results have moved since it was written | this skill |38| Choosing which pages need work | `content-triage` |39| The page competes with another page on the site | `cannibalization-audit` first; consolidate before refreshing |40| Only the title and description lose clicks | `meta-serp-copy` alone is enough |41 42## Inputs43 44| Input | Required | Ways to provide, in order | If missing |45| --- | --- | --- | --- |46| The page: full text, title, description, headings, links, dates, author | yes | fetch the URL if the agent can browse; the page source or text the reader pastes | `BLOCKED`, ask for the text |47| Performance: position, clicks, impressions, CTR, trend, the queries it ranks for | no | the `content-triage` handoff; a connected Search Console; a Pages and Queries export | intent mismatch can't be checked from data; coverage `partial` |48| The live results for its main keyword: top 5 titles, URLs and outlines | no | browse the results; titles, URLs and H2s the reader pastes | coverage, depth and format gaps not checked; coverage `partial`; ask for them |49| The site's page list | no | a crawl or sitemap; a pasted list | link checks limited to the page's own links |50| Clash result | no | the `cannibalization-audit` handoff | say "clashes not checked" |51 52## Profile read53 54From `company-profile.md`: `## Company`, `## Buyers` and `## Buying moments` (whose questions the page should answer), `## Voice` (for the voice pass), `## Claims and proof` and `### Never say` (for the claim pass), `## Content` (authors, clusters, pillars), and every `## Learnings` entry for `refresh-audit` with status `noted`, `fact` or `accepted`.55 56No profile: ask for the buyer the page is for and the company's approved claims, in one message; continue without voice rules (coverage `partial`). Say that `company-profile` saves this next time.57 58## Steps59 601. **Apply learnings.** Read them first. Sections the reader marked as protected stay protected.61 622. **Read the baseline.** Read the whole page, not a skim. Record: title and character count, description and character count, H1, every H2 and H3, word count, every claim with its source, every internal and external link, published and updated dates, author. Take performance from the `content-triage` handoff when it exists instead of pulling it again.63 643. **Confirm the keyword and the intent.** The target keyword is in the title, H1 and first H2. The ranking keyword is the non-branded query with the most impressions. If they differ, compare intent: same need is fine (retarget the title), a different need is an intent mismatch (a critical finding).65 664. **Read the live results** for the target keyword: the top 5 organic pages. For each: format, its H2s as short subtopics, its date, and the result features shown (featured snippet, "People also ask", an AI Overview and the pages it cites). Without the results, skip to step 6 and mark coverage `partial`.67 685. **Count the gaps.** With Python, write the page's subtopics and each result's subtopics to JSON and run:69 70 ```71 python3 scripts/refresh_math.py gaps --json gaps.json72 ```73 74 Without Python: for each subtopic in the top 5, count how many cover it (2 subtopics match when they share half their words). Covered by 3 or more and missing from the page is a coverage gap. Subtopics only the page covers are its edge: protect them. Say which way you ran it.75 766. **Run the checks** in `references/checks.md`: claims and sources (run `claim-check` on every claim, or apply its rules inline), coverage and format, answers near the top, voice (run `voice-check` on sections that will stay), title and description, links, dates. Each finding gets the severity the file gives it.77 787. **Build the edit list.** One row per finding: tier, the problem, the exact edit, the section, why it matters. Order within each tier by impact: intent and accuracy first, then gaps on subtopics that carry the most impressions, then everything else.79 808. **Mark the protected passages.** Every section with no finding is protected. Sections that carry the page's top queries, or its edge, are protected even when a finding touches them: the edit is surgical, not a rewrite of the section.81 829. **Set the date rule for the writer.** After the edit, run:83 84 ```85 python3 scripts/refresh_math.py date --old old.md --new new.md86 ```87 88 The visible "updated" date may change only when 30% or more of the words changed or 2 or more sections were added. Without Python, count new H2 and H3 headings, and estimate the share of changed paragraphs; if unsure, leave the date. Google's own guidance asks whether a site changes dates to seem fresh when the content hasn't substantially changed.89 90## Check and verdict91 92| Verdict | Condition (first match wins) |93| --- | --- |94| `BLOCKED` | No page text after asking |95| `CONSOLIDATE` | Another page on the site serves the same intent: merge first, then audit the keeper |96| `FULL REWRITE` | An intent mismatch (the results serve a different job than the page); or more than half the H2 sections carry a critical or important finding |97| `SIGNIFICANT REFRESH` | 2 or more coverage gaps that need new sections; or a format change (a table, steps, a comparison); or critical claim findings in 3 or more places |98| `STANDARD REFRESH` | Any critical or important finding otherwise (depth, freshness, title, links, a claim or 2) |99| `NO CHANGE` | Optional findings only, or none: leave the page, and don't touch its date |100 101Named stops: `FULL REWRITE` and `CONSOLIDATE` wait for the reader before anyone starts, because both change the page's URL or most of its text. No other stops.102 103## Learn104 105Append a learning to the profile when:106 107- the reader rejects an edit as wrong for the page (a `proposal` with their reason);108- the reader reports the result of a refresh, such as position or clicks 30, 60 or 90 days later (a `fact` with its source and window);109- a source the audit relied on turns out dead or wrong (a `fact`, so later runs don't trust it).110 111Example: `- 2026-10-24 | refresh-audit | fact | Adding a pricing models section moved /blog/attribution-software-guide from position 9.4 to 4.8 in 60 days | Why: Search Console, Aug to Oct 2026 | Status: noted`112 113## Output114 115```116Verdict: <NO CHANGE | STANDARD REFRESH | SIGNIFICANT REFRESH | FULL REWRITE | CONSOLIDATE | BLOCKED> · Coverage: <complete | partial (what's missing) | blocked> · Gaps: <script | by hand>117Rule fired: <the condition, in words>118Page: <URL> · Target keyword: <keyword> · Ranking keyword: <query> · Position: <n> · Clicks: <n> · Impressions: <n> (each "not available" when missing)119 120Critical (fix before it ships):121| # | Problem | Edit | Section | Why |122 123Important (the refresh):124| # | Problem | Edit | Section | Why |125 126Optional:127| # | Problem | Edit | Section |128 129Protected passages: <sections, and why>130Edge (only this page covers): <subtopics>131Title: <current, n characters> → <hand to meta-serp-copy, or fine>132Date rule: change the updated date only if 30% or more of the words change or 2 or more sections are added133Learnings applied: <list, or none>134```135 136Then the handoff block.137 138## Hand off139 140```handoff141skill: refresh-audit142version: 1.0.0143verdict: SIGNIFICANT REFRESH144coverage: complete145for: https://example.com/blog/attribution-software-guide146outputs:147 critical: 2148 important: 5149 new_sections: [pricing models, CRM integration]150 protected: [the customer story section]151 meta_rewrite: true152next: [meta-serp-copy, internal-linking]153open: [replace the 2021 benchmark with a current source]154```155 156`next` adds `[cannibalization-audit]` for `CONSOLIDATE`, and `[keyword-selection]` for `FULL REWRITE` (the page needs a new target).157 158## Failure modes159 160| Problem | Do this |161| --- | --- |162| The reader asks only to bump the updated date | Refuse the date change without an edit; run the audit or return `NO CHANGE` |163| The top 5 includes the reader's own page | Read the next result instead, and say so |164| The results are all one brand's pages or directories | Format and coverage comparisons are weak; say so and lean on buyer questions from the profile |165| The page is a top performer marked PROTECT by `content-triage` | Audit only for critical findings; anything else waits |166| A competitor's page outranks on a claim the reader can't make | Don't add the claim; note the gap and route it to `company-profile` as a claim to confirm |167| No position data and no results | Run claims, links, voice, title and date checks only; coverage `partial` |168 169## Influenced by170 171- SHAKEUP's content engine: a tiered edit list instead of a rewrite brief, protected passages by default, every claim checked again on refresh, and a date that moves only on a substantial change.172- Google's guidance on helpful, people-first content, including its question on changing dates to seem fresh: https://developers.google.com/search/docs/fundamentals/creating-helpful-content173- Google's guide to its generative AI features, which says no special chunking, markup or AI files are needed: https://developers.google.com/search/docs/fundamentals/ai-optimization-guide