Site Consistency — Offer-Aligned Text Audit
Goal: every piece of text on the site tells the same story — the offer stated on the home page — to the same customer, with the same promise, names, and terms. Audit first; fix only what the user approves.
Two hard boundaries:
- Audit before fix. The audit is read-only. No file is modified until the user approves specific rows of the audit table.
- Text only. This skill changes words — never layout, styles, components, images, routes, or page structure. See "Text-Only Editing Rules".
Languages
- Talk to the user in the language they use in the conversation. The report, table headers, severity labels, and the "why" column are in that language.
- Quotes of the current text are verbatim, in their original language.
- Proposed site text is written in the language of the text it replaces, natively and idiomatically (never a literal translation), keeping the site's form of address (e.g. Polish "Ty"/"Państwo", German "du"/"Sie") and voice.
- Detect the site language(s) from
<html lang>, i18n config, locale files, and the visible copy. On multi-locale sites, identify the primary locale; if it is unclear which locales to audit, ask.
Workflow
Follow the steps in order. Steps 1–6 never modify files.
Step 1 — Reconnaissance
Read references/text-inventory.md. Establish:
- the stack and routing (how URLs map to files),
- where the text lives: components/templates, i18n files, Markdown/MDX/content collections, metadata, email templates, external CMS,
- locales and the primary site language,
- existing offer documents:
docs/offer/offer-brief.md(written by the grand-slam-offer skill) or any brief/positioning doc indocs/.
If most of the text lives in an external CMS and there is neither an export nor a URL to read the rendered site, tell the user what can and cannot be audited before continuing.
Step 2 — Extract the offer from the home page
Read the home page the way a first-time visitor would: hero first, then every section in order, plus <title>, meta description, header, and footer. Fill in the Offer Statement:
| Field | What it answers |
|---|---|
| What is sold | product/service and its format |
| For whom | the customer/avatar, segment, market |
| Core promise | the outcome the customer gets (+ timeframe, if stated) |
| Mechanism / differentiator | how it's delivered, why this instead of alternatives |
| Names | exact spelling of the offer, product, method, and package names |
| Key terms | price/packages, guarantee, scarcity/deadlines, delivery time — only those stated |
| Primary conversion | the main CTA and what happens after clicking it |
| Voice | tone, form of address, positioning (premium, budget, expert, friendly…) |
For each field record the value and the source (quote + location). If a field is not on the home page, write "not stated". If an offer brief exists, compare it with the home page field by field.
On a site with several distinct offers (e.g. separate services for different audiences), record the umbrella offer from the home page and list the sub-offers; each sub-offer page will be checked against its own offer and against the umbrella.
Step 3 — Offer clarity gate
The offer is clear when all of these hold:
- "What is sold", "For whom", "Core promise", and "Primary conversion" can be answered from the home page alone.
- The home page presents one main offer (or one clear umbrella with sub-offers) — no competing offers.
- The home page does not contradict itself (two prices, two audiences, two different promises).
- The home page does not contradict the offer brief, if one exists.
Clear → continue. The Offer Statement is the benchmark; it goes at the top of the report so the user can correct it.
Not clear → stop and ask the user about the offer before auditing anything else. Never guess the offer to get past this gate.
- Use the
AskUserQuestiontool if available (max 4 questions per round), with options built from the candidates you actually found on the site plus room for a custom answer. Otherwise ask in chat. - Ask only about fields that are missing or conflicting, e.g. "The home page sells both X and Y — which is the main offer?", "Is the main customer A (hero) or B (services section)?", "The brief says a 30-day guarantee, the home page 14 days — which is current?". For multiple offers, confirm the hierarchy (main offer vs. sub-offers).
- Record the answers in the Offer Statement with the source "confirmed by user". The unclear or contradictory home page text then becomes findings — the home page is audited against the confirmed offer like every other page.
Step 4 — Page and text inventory
List everything a visitor can read (details in references/text-inventory.md):
- every route/page, including dynamic routes and content collections,
- shared text: header, navigation, footer, banners, modals/popups, forms (labels, placeholders, validation, success/error messages), 404/500 and empty states,
- text visitors see indirectly:
<title>, meta description, Open Graph/Twitter tags, JSON-LD text fields,alt,aria-label, web manifest name/description, - transactional emails and notifications, if their templates are in the repo.
Give each page its narrative role (see references/consistency-checklist.md) — the role decides what "consistent" means for that page.
Large sites: audit every core page in full. For large collections of the same type (e.g. more than 20 blog posts or products), audit the shared template plus each item's title, description, intro, and CTA; say in the report exactly what was covered this way and offer a full pass. If the Agent tool is available, you may split the inventory among subagents — give each one the confirmed Offer Statement, the checklist, and its list of pages, then merge their findings into a single table.
Step 5 — Audit
Read references/consistency-checklist.md. Check every text unit against the Offer Statement on all dimensions (D1–D10), in the context of its page's role. For each finding record: location, verbatim quote, dimension, severity, why it's a problem (tied to a specific Offer Statement field), fix type, and the proposed text.
- Build the fact matrix first (every mention of price, guarantee, deadlines, spots, delivery time, names — side by side) so contradictions between pages are caught systematically, not by chance.
- Proposed text follows the Text-Only Editing Rules and never invents facts. A missing fact becomes a placeholder in the site's language (e.g.
[TO FILL IN: …], Polish[DO UZUPEŁNIENIA: …]). - Conflicting facts where the truth isn't established → fix type Decision: list the options, don't pick one.
- Problems that text can't solve (image showing a different product, missing section or CTA button, a page that shouldn't exist, wrong link target, URL slug) go to "Outside text scope" — reported, never fixed by this skill.
Step 6 — Audit report, then stop
Present the report exactly as in "Output Format". The report always ends with the findings table. The only thing allowed after the table is the approval question. Then stop and wait — do not modify any file in this turn.
Approval question (use AskUserQuestion if available):
- Apply all
- Apply Critical and Major only
- Apply selected rows (the user lists the #s and may edit any proposal)
- Don't apply — audit only
Every Decision row that the user wants applied needs an answer; ask for these in the same round when possible.
Step 7 — Apply approved fixes
- Apply only the approved rows, with the user's edits, following the Text-Only Editing Rules.
- Before changing a string, check where else it renders (shared i18n key, shared component, reused Markdown partial). If the new text doesn't fit one of those contexts, stop and ask.
- If an approved fix turns out to need a non-text change, or can't be applied as approved, skip it and report it. Don't improvise a different fix.
- Text stored in an external CMS: don't try to edit it; prepare a copy-paste list (CMS entry/field | current text | new text).
Step 8 — Verify and report
- Re-read every changed passage with the text around it — it must read naturally in context.
- Search for leftovers of the old variants (old names, old terms, old promise) within the approved scope.
- Validate changed files: JSON/YAML parse, locale files keep the same keys, interpolation variables are intact. Run the project's lint/typecheck/build if one is available and quick.
- Multi-locale: list the other locales whose strings need a matching update, unless the user approved updating them too.
- Finish with the summary table: # | Where | Status (Applied / Skipped — reason / Needs CMS update) | Change (short). Don't commit unless asked.
Text-Only Editing Rules
Allowed:
- user-visible string content: text nodes in JSX/templates, string literals rendered to users, i18n values, Markdown/MDX prose, frontmatter text fields (title, description), in-repo CMS/content files,
- text attributes and metadata:
alt,title,aria-label,placeholder,<title>, meta description, OG/Twitter text, JSON-LD text values, manifest name/description, - form, system, and email template messages,
- rewriting, shortening, or deleting sentences inside an existing text element.
Not allowed (report under "Outside text scope" instead):
- adding, removing, reordering, or restyling elements, sections, or components; changing markup, classes, CSS, or non-text props,
- emptying an element — an empty element is a layout change; rewrite it instead,
- i18n keys, variable names, file names, routes, URL slugs, anchors (slugs are text, but changing them breaks links and SEO),
- link targets (
href) — only the link text may change, - images, icons, video, and other media,
- code logic, conditions, data fetching.
While editing:
- Preserve interpolation and syntax:
{name},{{count}},%s,:attribute, ICU plural/select, HTML entities, inline tags inside strings (<strong>,<br>,<0>…</0>), Markdown formatting, and escaping (quotes in JSX/JSON, apostrophes in PHP strings). - Keep the length close to the original (roughly ±30%) because the layout isn't changing. If a fix needs much more text, say so in the proposal.
- Match the site's typographic conventions (quotation marks, dashes, non-breaking spaces).
Mandatory Rules
- R1. Read-only audit. No edits and no file writes (report files included, unless the user asks for one) before explicit approval. Approval covers only the approved rows.
- R2. Text only. Everything outside the Text-Only Editing Rules is reported, never changed.
- R3. Benchmark first. Never audit against a guessed offer: the Offer Statement is either clear from the home page or confirmed by the user.
- R4. Evidence. Every finding quotes the current text verbatim and gives a precise location (
file:lineor i18n key). - R5. The table always comes last. Every audit report ends with the findings table, also when there are no findings — then it ends with a coverage table (Page | Role | Verdict).
- R6. No invented facts. Proposals never add numbers, results, testimonials, guarantees, or terms the user hasn't provided or the site doesn't already state consistently. Conflict → Decision. Missing → placeholder.
- R7. Consistency, not uniformity. Don't paste the hero promise everywhere or force a sales pitch onto every page. Flag only text that contradicts, dilutes, drifts from, or distracts from the offer, given the page's role. Legal pages are never rewritten for narrative — only their fact conflicts with marketing copy are flagged, with a recommendation to have the legal text reviewed.
- R8. Align to the offer, don't redesign it. This skill aligns the site with the confirmed offer. If the offer itself is weak (vague promise, no proof, price-led), say so in one line of the summary and suggest the
grand-slam-offerskill; don't rebuild the offer here. - R9. Language. Communication in the conversation language; proposed site text in the language of the text it replaces.
Output Format
Audit report
Sections in this order, written in the conversation language:
- Benchmark offer — the Offer Statement (compact table) + its source (home page / offer brief / confirmed by user).
- Scope — pages and text sources audited (count + list or grouping), locales, what was covered by sampling, what lives outside the repo and wasn't audited.
- Summary — findings count by severity; the 2–3 biggest narrative problems, one sentence each; optionally one line about the offer itself (R8).
- Full rewrites (only if needed) — proposals longer than ~40 words, in full, labeled with the finding #.
- Outside text scope (only if any) — short bullets; this skill won't fix them.
- Findings table — the last element of the report.
Findings table — headers translated into the conversation language:
| # | Where | Severity | Today | Why it shouldn't be like this | Proposed fix |
|---|
- # — stable ID used for approval.
- Where — page · section ·
file:lineor i18n key. - Severity — Critical / Major / Minor (see checklist).
- Today — verbatim quote of the relevant fragment; shorten with "…" beyond ~25 words.
- Why it shouldn't be like this — the concrete conflict with the benchmark, e.g. "home page: for dental clinics; here: for any business".
- Proposed fix — the exact new text in the site's language, "see Full rewrites #N", or
DECISION: A) … / B) ….
Sort by severity, then by the page order of the inventory.
For example, in a Polish conversation the three core headers become "Jak jest dziś", "Dlaczego tak nie powinno być", "Jak to poprawię".
Example rows (English site, English conversation):
| # | Where | Severity | Today | Why it shouldn't be like this | Proposed fix |
|---|---|---|---|---|---|
| 1 | /about · intro · src/app/about/page.tsx:14 | Critical | "We build custom websites for any business." | The home page sells a 6-week local SEO program for dental clinics; this sells a different service to a different audience. | "We help dental clinics fill their calendars with patients from Google — it's the only thing we do." |
| 2 | /pricing · guarantee · messages/en.json pricing.guarantee | Critical | "14-day money-back guarantee" | The home page promises 30 days; visitors see two different guarantees. | DECISION: A) 30 days everywhere / B) 14 days everywhere |
| 3 | Footer · tagline · src/components/Footer.tsx:22 | Minor | "Web design & more" | Leftover from the old offer; the footer frames every page. | "Local SEO for dental clinics" |
Fix summary (after Step 8)
| # | Where | Status | Change |
|---|
Status: Applied / Skipped — reason / Needs CMS update. Below the table: CMS copy-paste list and locales needing matching updates, if any.
Avoid
- Editing anything during the audit.
- Auditing against a guessed offer.
- Treating every difference as a problem — pages have different roles.
- Turning a text audit into a redesign: new sections, new CTAs, new images.
- Choosing between conflicting facts on the user's behalf.
- Writing proposals in the conversation language instead of the site's language, or as literal translations.
- Burying the table — nothing but the approval question comes after it.