SEO Review

Evaluate your application's search engine optimization and discoverability. This review catches SEO issues that are invisible during normal development — missing meta tags, broken structured data, poor crawlability, missing sitemaps, and social sharing problems. Many SPAs ship with zero SEO consideration.

When to use

Use /seo-review when:

• Before launching a public-facing website or application
• After redesigning or migrating a website
• When organic traffic is a growth channel
• After switching to an SPA framework (React, Vue, Angular)
• When social sharing (Open Graph) is important
• Setting up content marketing pages

Standards Referenced

• Google Search Central — SEO best practices and guidelines
• Schema.org — Structured data vocabulary
• Open Graph Protocol — Social sharing meta tags
• Twitter Card — Twitter sharing markup
• W3C Semantic HTML — Accessibility and SEO semantics
• Web.dev SEO Guidelines — Google's SEO recommendations

Phase Overview

Phase 1: EDUCATE   → Why SEO matters and what we check
Phase 2: SCOPE     → Identify key pages, content types, SEO goals
Phase 3: ANALYZE   → Browser-based SEO validation
Phase 4: REPORT    → Findings with impact assessment and priority
Phase 5: REMEDIATE → Fix guidance + YAML regression tests

Phase 1: Educate

Why this matters: 53% of all website traffic comes from organic search (BrightEdge). The first Google result gets 27.6% of all clicks; position 10 gets 2.4% (Backlinko). SPAs often render blank HTML to crawlers, making millions of pages invisible to search. Proper SEO doesn't require tricks — it requires making your content discoverable and understandable by search engines.

This review checks the technical SEO foundation — the things that must be correct before content strategy matters.

Phase 2: Scope

Gather context

1. Auto-detect from codebase:

   • Framework and rendering strategy (SSR, SSG, CSR, ISR)
   • Meta tag management (react-helmet, next/head, vue-meta, etc.)
   • Sitemap generation
   • robots.txt configuration
   • Structured data (JSON-LD, microdata)
   • i18n/hreflang setup
   • Canonical URL handling
   • Route structure and page types

2. Ask the user (one at a time):

   • Target URL: Where is the app running? (production preferred for realistic crawling)
   • Key pages: Which pages are most important for search? (homepage, product pages, blog posts, landing pages)
   • Target keywords: Any primary keywords you want to rank for? (optional, for content evaluation)
   • Social sharing important?: Is Open Graph / Twitter Cards needed? (default: yes for public sites)
   • Multi-language?: Does the site serve multiple languages? (auto-detected)

3. Identify page types:

   • Homepage
   • Content pages (blog, docs, about)
   • Product/listing pages
   • Dynamic pages (search results, user profiles)
   • Utility pages (login, 404, terms)

Phase 3: Analyze

Open a browser session with new_session using record_evidence: true. For each key page, run all check categories.

Category A: Meta Tags & Head Elements (META)

Browser validation: Use inspect_page to read the DOM. Extract all <head> elements via JavaScript.

Category B: Structured Data (SCHEMA)

Browser validation: Extract JSON-LD scripts via JavaScript. Parse and validate structure. Compare page content against schema claims.

Category C: Open Graph & Social Sharing (OG)

Browser validation: Extract all OG and Twitter meta tags. Verify og:image URL is accessible. Construct a preview representation.

Category D: Crawlability & Indexing (CRAWL)

Browser validation: Navigate to robots.txt, sitemap.xml. Follow internal links. Disable JavaScript to test server-rendered content. Check HTTP status codes.

Category E: Semantic HTML & Content (SEM)

Browser validation: Extract headings, links, images, and semantic elements via JavaScript. Analyze content structure.

Category F: Technical SEO (TECH)

Browser validation: Test redirects, measure performance metrics, check mobile rendering.

Phase 4: Report

Generate a structured report saved to shiplight/reports/seo-review-{date}.md:

# SEO Review Report
**Date:** {date}
**URL:** {url}
**Pages reviewed:** {list}
**Rendering:** {SSR/SSG/CSR/ISR}

## Overall Score: {X}/10 | Confidence: {X}%

## Score Breakdown
| Category | Score | Findings |
|----------|-------|----------|
| Meta Tags (META) | 7/10 | 1 high, 2 medium |
| Structured Data (SCHEMA) | 4/10 | 1 critical, 1 high |
| Social Sharing (OG) | 6/10 | 2 high |
| Crawlability (CRAWL) | 5/10 | 1 critical, 1 high |
| Semantic HTML (SEM) | 8/10 | 1 medium |
| Technical SEO (TECH) | 7/10 | 1 high |

## Page-by-Page Summary
| Page | Title | Description | OG Image | Schema | H1 | Score |
|------|-------|-------------|----------|--------|----|-------|
| / | ✅ | ✅ | ❌ missing | ❌ none | ✅ | 6/10 |
| /blog | ✅ | ⚠️ too short | ✅ | ✅ Article | ✅ | 8/10 |

## Findings
(structured findings with evidence and impact)

Confidence Scoring

• 90-100%: Verified in browser — tag present/absent, URL accessible/broken
• 70-89%: Content analysis suggests issue (e.g., thin content, generic alt text)
• 50-69%: Best practice recommendation without clear violation
• Below 50%: Don't report

Phase 5: Remediate

1. Fix guidance (example)

#### CRAWL-10: Content not visible without JavaScript
**Impact:** Search engines may not index your content (especially Google Discover, Bing, social crawlers)
**Current:** Client-side rendered React app, empty HTML shell
**Fix:** Implement SSR or SSG:
- Next.js: Use `getServerSideProps` or `getStaticProps`
- Nuxt: Default SSR mode
- Gatsby: Static generation
- Or: Add prerendering service (prerender.io, rendertron)
**Quick win:** Ensure critical content is in initial HTML response

2. YAML regression test

- name: meta-01-title-present
  description: Verify each key page has a unique, properly-sized title tag
  severity: high
  standard: Google-SEO-Guidelines
  steps:
    - URL: /
    - description: Assert the page title is present and 20-60 characters
      js: |
        const title = await page.title();
        if (!title || title.trim() === '') {
          throw new Error('Page has no title');
        }
        if (title.length < 20) {
          throw new Error(`Title too short (${title.length} chars): "${title}"`);
        }
        if (title.length > 60) {
          throw new Error(`Title too long (${title.length} chars): "${title}"`);
        }
        console.log(`Title OK (${title.length} chars): "${title}"`);
    - VERIFY: Page has a descriptive title between 20 and 60 characters

Save all YAML tests to shiplight/tests/seo-review.test.yaml.

Depth Levels

• --quick: Meta tags + canonical + robots.txt on homepage only. ~2 minutes.
• default: All categories on key pages. ~8-12 minutes.
• --thorough: All categories + full site crawl + all page types + content analysis. ~20-30 minutes.

Tips

• Test with JavaScript disabled to see what search engines see (especially for SPAs)
• Use inspect_page DOM output to extract <head> content efficiently
• Check sitemap.xml manually — auto-generated sitemaps often include pages that shouldn't be indexed
• OG image must be an absolute URL — relative URLs don't work for social sharing
• For SPA SEO, the critical question is: "Does the initial HTML contain the content?"
• Close session with close_session and use generate_html_report for evidence