1---
2name: fixing-metadata
3description: >
4  Audit and fix HTML metadata including page titles, meta descriptions, canonical URLs, Open Graph
5  tags, Twitter cards, favicons, JSON-LD structured data, and robots directives. Use when adding
6  SEO metadata, fixing social share previews, reviewing Open Graph tags, setting up canonical URLs,
7  or shipping new pages that need correct meta tags.
8version: 1.0.1
9license: MIT
10---
11 
12## Workflow
13 
141. Identify pages with missing or incorrect metadata (titles, descriptions, canonical, OG tags)
152. Audit against the priority rules below — fix critical issues (duplicates, indexing) first
163. Ensure title, description, canonical, and og:url all agree with each other
174. Verify social cards render correctly on a real URL, not localhost
185. Keep diffs minimal and scoped to metadata only — do not refactor unrelated code
19## when to apply
20 
21Reference these guidelines when:
22- adding or changing page titles, descriptions, canonical, robots
23- implementing Open Graph or Twitter card metadata
24- setting favicons, app icons, manifest, theme-color
25- building shared SEO components or layout metadata defaults
26- adding structured data (JSON-LD)
27- changing locale, alternate languages, or canonical routing
28- shipping new pages, marketing pages, or shareable links
29 
30## rule categories by priority
31 
32| priority | category | impact |
33|----------|----------|--------|
34| 1 | correctness and duplication | critical |
35| 2 | title and description | high |
36| 3 | canonical and indexing | high |
37| 4 | social cards | high |
38| 5 | icons and manifest | medium |
39| 6 | structured data | medium |
40| 7 | locale and alternates | low-medium |
41| 8 | tool boundaries | critical |
42 
43## quick reference
44 
45### 1. correctness and duplication (critical)
46 
47- define metadata in one place per page, avoid competing systems
48- do not emit duplicate title, description, canonical, or robots tags
49- metadata must be deterministic, no random or unstable values
50- escape and sanitize any user-generated or dynamic strings
51- every page must have safe defaults for title and description
52 
53### 2. title and description (high)
54 
55- every page must have a title
56- use a consistent title format across the site
57- keep titles short and readable, avoid stuffing
58- shareable or searchable pages should have a meta description
59- descriptions must be plain text, no markdown or quote spam
60 
61### 3. canonical and indexing (high)
62 
63- canonical must point to the preferred URL for the page
64- use noindex only for private, duplicate, or non-public pages
65- robots meta must match actual access intent
66- previews or staging pages should be noindex by default when possible
67- paginated pages must have correct canonical behavior
68 
69### 4. social cards (high)
70 
71- shareable pages must set Open Graph title, description, and image
72- Open Graph and Twitter images must use absolute URLs
73- prefer correct image dimensions and stable aspect ratios
74- og:url must match the canonical URL
75- use a sensible og:type, usually website or article
76- set twitter:card appropriately, summary_large_image by default
77 
78### 5. icons and manifest (medium)
79 
80- include at least one favicon that works across browsers
81- include apple-touch-icon when relevant
82- manifest must be valid and referenced when used
83- set theme-color intentionally to avoid mismatched UI chrome
84- icon paths should be stable and cacheable
85 
86### 6. structured data (medium)
87 
88- do not add JSON-LD unless it clearly maps to real page content
89- JSON-LD must be valid and reflect what is actually rendered
90- do not invent ratings, reviews, prices, or organization details
91- prefer one structured data block per page unless required
92 
93### 7. locale and alternates (low-medium)
94 
95- set the html lang attribute correctly
96- set og:locale when localization exists
97- add hreflang alternates only when pages truly exist
98- localized pages must canonicalize correctly per locale
99 
100### 8. tool boundaries (critical)
101 
102- prefer minimal changes, do not refactor unrelated code
103- do not migrate frameworks or SEO libraries unless requested
104- follow the project's existing metadata pattern (Next.js metadata API, react-helmet, manual head, etc.)
105 
106## review guidance
107 
108- fix critical issues first (duplicates, canonical, indexing)
109- ensure title, description, canonical, and og:url agree
110- verify social cards on a real URL, not localhost
111- prefer stable, boring metadata over clever or dynamic
112- keep diffs minimal and scoped to metadata only
113