/alignment-audit — Content ↔ structured data alignment

Target: $ARGUMENTS

Basis: Google's structured-data guidelines require markup to describe content visible on the page; non-representative markup, or FAQ/HowTo content users cannot see, can trigger a manual action and loses rich-result eligibility (CONFIRMED tier — ${CLAUDE_PLUGIN_ROOT}/skills/seo-fundamentals/references/patent-signals.md, G4). Aligned markup also strengthens entity identity (sameAs, Person/Organization).

Extraction

1. Run python3 ${CLAUDE_PLUGIN_ROOT}/scripts/fetch_page.py "<url>" --json — returns parsed JSON-LD blocks, headings, and body text from the raw HTML (WebFetch strips <script>, so never use it for this step). For a local file: fetch_page.py <file.html> --json.
2. If no JSON-LD is returned, check Microdata/RDFa attributes in the raw HTML, then say "not detected in static HTML — confirm with Rich Results Test (renders JS)". Never report "no schema" from static HTML alone.
3. Body: headings, paragraphs, lists, tables, byline, visible dates, prices, ratings.

Modules

1. Numeric claims — every price, percentage, count, duration, date, rating in the body vs the corresponding schema field. Status per claim: MATCH / MISMATCH / TEXT-ONLY / SCHEMA-ONLY; action: keep / fix text / fix schema / add / remove.
2. Named entities — people, organizations, products, places, versions: declared in schema? name consistent ("Anthropic" vs "Anthropic Inc.")? sameAs present? Status: VERIFIED / INCONSISTENT / NO SCHEMA / WEAK ENTITY.
3. FAQ / HowTo presence — each schema Q/A pair or step must appear in the body verbatim or near-verbatim; missing → SCHEMA SPAM (policy violation). Note that these types no longer yield rich results for most sites; recommend removing them unless the content is genuinely on the page and useful as entity data.
4. Completeness — required and recommended fields per type (Article: headline, author, datePublished, image; Product: name, image, description, offers; Person: name + sameAs, jobTitle, url; Organization: name, url + sameAs, logo; Review: itemReviewed, reviewRating, author; FAQPage: mainEntity[]). Missing required → CRITICAL; declared without body counterpart → HOLLOW.
5. sameAs — each URL authoritative (Wikidata, LinkedIn, ORCID, Crunchbase, official registries), resolving, and about the same entity; missing for Person/Organization/Brand/LocalBusiness → WEAK ENTITY.

Verdict

Output

1. Schema inventory (type, key properties, where found).
2. Findings per module in the formats above, each with evidence (field path ↔ body quote).
3. Verdict.
4. Prioritized fixes — Critical (schema spam, missing required, wrong-entity sameAs) → High (numeric mismatch, missing sameAs for Person/Organization) → Medium (name inconsistency, hollow fields) → Low (recommended fields).
5. Corrected JSON-LD when the fix is mechanical (or hand off to /schema-gen); re-test with Rich Results Test and the Schema.org validator.

Caveat: some schema legitimately carries richer data than the body (accessibility, machine-readable variants). The rule is: schema must not claim what the body contradicts or omits entirely.