Site Auditor

interface SiteAuditorInput {
  tenantId:          string;
  clientDomain:      string;           // e.g. "acme.com" — no protocol, no trailing slash
  previousAuditDate?: string;          // ISO date — used to surface what has changed since last audit
  focusAreas?:       FocusArea[];      // optional — narrows scope; if omitted, all areas are audited
  campaignId?:       string;
}
 
type FocusArea =
  | 'crawlability'
  | 'on-page'
  | 'speed'
  | 'structured-data'
  | 'mobile';

interface SiteAuditorOutput {
  tenantId:            string;
  clientDomain:        string;
  auditDate:           string;          // ISO timestamp
  previousAuditDate?:  string;
  technicalScore:      number;          // 0–100 composite score
  scoreDelta?:         number;          // change vs. previous audit (positive = improved)
  summary:             string;          // 3–5 sentence executive summary
  criticalIssues:      AuditFinding[];
  warnings:            AuditFinding[];
  opportunities:       AuditFinding[];
  prioritisedActionList: ActionItem[];
  focusAreaScores:     FocusAreaScore[];
}
 
interface AuditFinding {
  id:              string;
  category:        FocusArea | 'security' | 'links' | 'content';
  title:           string;
  description:     string;
  affectedUrls:    string[];          // up to 5 example URLs
  affectedCount:   number;            // total pages/items affected
  impact:          'critical' | 'high' | 'medium' | 'low';
  effort:          'low' | 'medium' | 'high';
  recommendation:  string;            // specific fix instruction
  changedSinceLast?: boolean;         // true if this issue is new or worsened since previous audit
}
 
interface ActionItem {
  priority:       number;             // 1 = highest
  title:          string;
  rationale:      string;             // why this is ranked at this priority
  estimatedImpact: string;            // e.g. "Fix 42 pages with missing H1 — likely +3–5% organic CTR"
  effort:         'low' | 'medium' | 'high';
  owner:          'dev' | 'content' | 'dm-agency';
}
 
interface FocusAreaScore {
  area:    FocusArea | 'security' | 'links' | 'content';
  score:   number;   // 0–100
  delta?:  number;   // change vs previous audit
}

## Technical SEO Audit — acme.com
**Audit Date:** 2026-03-01 | **Previous Audit:** 2026-02-01
**Technical Score:** 68/100 (▲ +4 vs. last month)
 
---
 
### Executive Summary
acme.com has improved its crawlability score following the February canonical tag fixes (+8 points).
The primary outstanding issues are 34 pages returning 3xx redirects in chains of 2+ hops, which
waste crawl budget and dilute link equity. Core Web Vitals remain a concern — LCP averages 4.2s on
mobile against a Good threshold of 2.5s, driven by uncompressed hero images on product pages.
Structured data coverage is strong (87% of blog posts have Article schema), but 12 product pages
are missing Product schema entirely. This month's priority is redirect chain resolution — a dev
task estimated at 2–3 hours.
 
---
 
### Critical Issues (2)
 
**1. Redirect chains (2+ hops) — 34 URLs**
- Category: Crawlability | Impact: Critical | Effort: Low (dev)
- Affected examples: /old-pricing → /pricing-2024 → /pricing (3 hops)
- Recommendation: Update all internal links pointing to intermediate URLs to point directly
  to the final destination. Update the sitemap to use final URLs only.
- ⚠️ New since last audit — 34 URLs have been added to chains since 2026-02-01
 
**2. LCP > 4s on mobile — 18 product pages**
- Category: Speed | Impact: Critical | Effort: Medium (dev)
- Average LCP: 4.2s | Good threshold: 2.5s
- Recommendation: Compress and serve hero images in WebP format; implement lazy loading for
  below-the-fold images; consider preloading the LCP element.
 
---
 
### Prioritised Action List
1. [Dev] Fix redirect chains — 34 URLs, 2–3 hours effort, high crawlability impact
2. [Dev] Compress hero images to WebP — 18 product pages, 4–6 hours, Core Web Vitals impact
3. [Content] Add Product schema to 12 product pages — 2 hours, structured data + rich result eligibility
4. [DM Agency] Submit updated sitemap to GSC after redirect fixes — 15 mins

You are a technical SEO auditor working for a digital marketing agency. Your job is to
analyse crawl data, Search Console coverage, and spot-checks to produce a prioritised
SEO audit report for a client website.

CLIENT CONTEXT:
{{CLIENT_CONTEXT}}

TENANT SETTINGS:
{{TENANT_SETTINGS}}

KNOWLEDGE BASE CONTEXT:
{{RAG_CONTEXT}}

You have been provided with:
- SEMrush site audit results (crawl errors, redirect chains, on-page issues, Core Web Vitals)
- Google Search Console crawl errors and index coverage data
- Spot-check results for key pages (homepage, a product/service page, top blog post)
- The client's known technical context from their document library
- Previous audit data (if available) for delta comparison

Your output must be a complete technical SEO audit report containing:
1. Technical score (0–100) and delta vs. previous audit
2. Executive summary (3–5 sentences, written for a non-technical client)
3. Critical issues — findings that are actively harming rankings or crawlability
4. Warnings — issues that will cause problems if left unaddressed
5. Opportunities — improvements that would increase rankings or click-through rate
6. Prioritised action list — ranked by impact × effort, with owner (dev/content/dm-agency)
7. Focus area scores (crawlability, on-page, speed, structured-data, mobile)

Prioritisation rules:
- Critical impact + Low effort = Priority 1 always
- Critical impact + High effort = Priority 2–3 (important but acknowledge the effort)
- Medium impact + Low effort = Priority 3–4 ("quick wins")
- Low impact regardless of effort = Bottom of the list
- Issues new or worsened since the previous audit = bump one priority level

Do not fabricate findings. Every issue must reference data from the tool results provided.
For each finding, name the specific fix — "improve page speed" is not a recommendation;
"compress hero images to WebP and implement lazy loading" is.

If the client's document library mentions a known issue or planned fix, note it in the
relevant finding's recommendation as "Note: Client aware — fix in progress per [doc reference]."

Output valid JSON matching the SiteAuditorOutput schema.

# Technical SEO Standards
 
## Severity Classification
 
**Critical** — Issues actively harming crawlability, indexing, or rankings:
- Pages returning 5xx errors
- Redirect chains of 2+ hops affecting > 5 URLs
- Canonical tags pointing to non-canonical pages
- Sitemap containing noindex or 404 URLs
- Duplicate H1 tags site-wide
- Core Web Vitals in "Poor" range on mobile (LCP > 4s, CLS > 0.25, INP > 500ms)
- Pages with hreflang conflicts (multilingual sites)
 
**Warning** — Issues that will compound over time if unaddressed:
- Missing meta descriptions on > 10% of indexed pages
- Thin content (< 300 words) on pages meant to rank
- Broken internal links (404s in internal anchor tags)
- Missing alt text on > 20% of images
- Pages excluded from index without clear rationale (not noindex, not canonical — orphaned)
- Structured data errors (valid schema but with missing recommended fields)
- Redirect chains of exactly 1 hop (inefficient but not critical)
 
**Opportunity** — Improvements that would improve ranking or CTR:
- Pages missing Article, Product, FAQ, or HowTo schema where applicable
- Title tags not using the primary keyword in the first 60 characters
- Meta descriptions missing on ≤ 10% of pages
- Internal link opportunities (pages in the same cluster not linked to each other)
- Featured snippet gaps (queries the site ranks 1–5 for but doesn't hold the snippet)
 
## Technical Score Weighting
| Area | Weight |
|---|---|
| Crawlability | 30% |
| On-page (titles, metas, H1s, canonicals) | 25% |
| Speed (Core Web Vitals) | 20% |
| Structured Data | 15% |
| Mobile | 10% |
 
Score calculation per area: start at 100, subtract points per finding:
- Critical finding: −15 points each (capped at −45)
- Warning: −5 points each (capped at −20)
- Opportunity: −2 points each (capped at −10)
 
## Owner Classification
- **Dev:** Server-side fixes, image optimisation, redirect resolution, schema implementation
- **Content:** Meta descriptions, title tags, H1 copy, thin content expansion, alt text
- **DM Agency:** Sitemap resubmission, GSC disavow, internal linking recommendations
 
## Core Web Vitals Thresholds
| Metric | Good | Needs Improvement | Poor |
|---|---|---|---|
| LCP | < 2.5s | 2.5s–4.0s | > 4.0s |
| INP | < 200ms | 200ms–500ms | > 500ms |
| CLS | < 0.1 | 0.1–0.25 | > 0.25 |