pSEO Codebase Audit

Perform a structured audit of the codebase to assess readiness for programmatic SEO at 1000+ page scale. Produce a concrete gap analysis with actionable findings.

If pseo-discovery was run first, use its output to focus the audit: check whether the codebase can support the specific page types, data models, and URL structures the discovery proposed. If discovery was not run, audit generically.

Audit Procedure

1. Identify the Framework and Architecture

• Detect the framework (Next.js, Astro, Nuxt, Remix, etc.) from config files
• Identify the rendering strategy: SSG, SSR, ISR, or client-side
• Map the routing structure: file-based, dynamic segments, catch-all routes
• Check for generateStaticParams, getStaticPaths, or equivalent

2. Assess Data Architecture

• Locate data sources: CMS, database, API, local files (JSON, MDX, CSV)
• Check for a centralized data-fetching layer vs. scattered inline fetches
• Evaluate whether data models have the fields needed for SEO (title, description, slug, category, FAQ, etc.)
• Look for a slug/URL generation strategy and whether it enforces uniqueness

3. Evaluate Routing and Page Templates

• Count dynamic route segments and template pages
• Check if templates produce unique content per page or rely on the same copy with minor variable swaps
• Look for catch-all routes that may create orphan or thin pages
• Verify 404 handling for invalid slugs, and for empty or nonsensical combinations (faceted/filter/location combos with no data must return a real 404 at the URL, not a redirect to a generic error page)
• Next.js streaming soft-404 (notFound() after Suspense returns 200 + noindex): existence check must run before any Suspense fallback. Rules in pseo-templates section 6a
• Raw-HTML parity: for a sample URL per template run curl -s URL | grep -i -E '<h1|<a href' and confirm the H1, main body text and internal <a href> links are in the server HTML, not client-only. Body checks are also covered by seo-regression-guard
• URL check: slugs use hyphens, not underscores (Google URL structure doc, 2026-10-23); flag _ in generated URLs

4. Review SEO Foundations

• Check for dynamic metadata generation (title, description, canonical)
• Look for Open Graph and Twitter card tags
• Search for JSON-LD structured data or schema markup
• Check for a sitemap generator (static or dynamic)
• Look for robots.txt configuration
• Verify canonical URLs are set and self-referencing by default
• Metadata placement: Next.js may stream generateMetadata output into <body> for JS-executing bots. Google respects robots meta in the body (2026-03-24) but its canonical docs specify <head>, and the canonical in the original HTML must match the JS canonical. Prefer static or use cache metadata so canonical and robots render in the head shell (this is a recommendation, not a Google statement), or set htmlLimitedBots
• noindex in the initial HTML: confirm no page ships noindex that JS later removes (Google may skip rendering and never index it). Check loading.tsx/streaming fallbacks that inject noindex
• Googlebot 2MB HTML limit (includes headers) and sitemap rules (lastmod, 50,000 URLs / 50MB, index file): check against pseo-templates section 6b and pseo-linking section 6
• Structured data: flag FAQPage and HowTo generation (FAQ rich results stopped showing 2026-05-07; HowTo removed 2023)
• AI features controls: check nosnippet, max-snippet, data-nosnippet use matches intent (they limit use in AI Overviews and AI Mode); robots.txt and CDN do not block Googlebot; note the Search Console "Search generative AI" setting and that Google-Extended does not control AI Overviews or AI Mode. llms.txt has no effect on Google Search

5. Evaluate Internal Linking

• Look for breadcrumb components
• Search for related-pages or hub-spoke linking patterns
• Check for programmatic cross-linking between pages
• Assess whether link structures create topical clusters

6. Assess Performance at Scale

• Check build configuration for page generation limits or timeouts
• Look for image optimization (next/image, sharp, etc.)
• Check for code splitting and lazy loading
• Identify large dependencies that bloat the bundle
• Look for caching headers or ISR/revalidation configuration

7. Check Content Quality Safeguards

• Look for content length or quality validation
• Search for duplicate content detection or prevention
• Check if pages have sufficiently differentiated titles and descriptions
• Check that thin pages are not generated or return 404/410; noindex only on utility/share/tool-output pages
• Look for doorway-shaped page types (city/region combos with only the place swapped, query-variation pages) and for a policy of excluding low-value pages from Search
• Check for a build-time or CI quality check (see pseo-quality-guard)

Output Format

Structure the audit report as:

## pSEO Audit Report

### Framework & Rendering
- [findings]

### Data Architecture
- [findings]
- Readiness: [Ready | Needs Work | Missing]

### Routing & Templates
- [findings]
- Readiness: [Ready | Needs Work | Missing]

### SEO Foundations
- [findings]
- Readiness: [Ready | Needs Work | Missing]

### Internal Linking
- [findings]
- Readiness: [Ready | Needs Work | Missing]

### Performance at Scale
- [findings]
- Readiness: [Ready | Needs Work | Missing]

### Content Quality Safeguards
- [findings]
- Readiness: [Ready | Needs Work | Missing]

### Priority Actions (ordered)
1. [most critical gap]
2. [next priority]
...

### Recommended Skill Sequence
Based on findings, recommend which pseo-* skills to run and in what order.
If discovery was run, confirm which proposed page types are feasible given codebase state.

Scope Parameter

If $ARGUMENTS specifies a scope, narrow the audit:

• full (default): Run all sections (1-7)
• routing: Sections 1, 3 only
• data: Sections 1, 2 only
• seo: Sections 4, 5, 7 only
• performance: Sections 6 only

Important Constraints

• Read files and analyze; do NOT modify any code during audit
• Be specific: cite file paths and line numbers for every finding
• Flag risks that would surface only at 1000+ pages (build time, memory, URL collisions)
• Distinguish between "not implemented" and "implemented incorrectly"