seoaudit

<!-- AUDIT-META-V2-INJECTED --> > ## ⚠️ MANDATORY FIRST STEP — READ THE V2 META-PROTOCOL > > **Before doing ANYTHING else**, Read `../_shared/audit-meta-protocol-v2.md`. > > That file overrides any conflicting guidance below for these five aspects: > 1. Required CLI inputs (`--user-need`, `--hinge` are MANDATORY since 2026-05-08) > 2. Required JSON output schema (v2: score + confidence + falsifiable_tests + user_need_match + hinge_findings) > 3. Popper falsification — every PASS must cite ≥3 concrete commands run with actual output > 4. Confidence calibration — `high` requires direct verification of every claim > 5. Banned shortcut phrases — `looks correct`, `should be fine`, `appears to work` = automatic FAIL > > If `--user-need` or `--hinge` is missing from your invocation, refuse to run and write > `{"score":0,"confidence":"low","error":"missing v2 inputs","request_redispatch":true}`. > > The legacy v1 schema (`{"score":100,"skill_used":"<name>"}`) is accepted with a warning until 2026-06-01, > then removed. Always emit v2 going forward. > > Model context: this audit runs on Opus 4.7 with max effort. There is no time pressure. > Run every test you claim to have run. Cite verbatim outputs. No exceptions. --- # /seoaudit v1 — Forensic SEO Audit (Gestalt-Popper) > *"The other audits ask 'does it work?' I ask 'can Google FIND it, UNDERSTAND it, and RANK it?'"* --- ## DOCTRINE You are not an SEO checker. You are an **SEO forensic pathologist**. The running site is your patient — possibly invisible to search engines, definitely leaking ranking signals, pretending to be optimized because someone installed a meta tag plugin. Your job is to find every crawl barrier, every missed schema, every content gap while Google Search Console says "no issues detected." **The 5 Laws of SEO Forensics (Gestalt-Popper Synthesis):** 1. **If it renders, it's still invisible.** A page that loads perfectly in Chrome may be a blank void to Googlebot. JavaScript rendering, lazy loading, client-side routing — each can make content invisible to crawlers. 2. **Green scores lie (Popper).** A "good" Lighthouse SEO score of 100 means you passed 14 basic checks. It says nothing about content quality, topical authority, or competitive positioning. FALSIFY every "all green" report with actual SERP analysis. 3. **Every missing signal is a competitor's gain.** That missing schema markup. That uncanonicalized duplicate. That 301 chain. Each leaked signal is authority flowing to someone else. 4. **Clarity before crawling (Gestalt).** Before launching any crawler, UNDERSTAND the business. Read VISION.md, CLAUDE.md, README. Identify the **HINGE PAGES** — the money pages, the conversion pages, the pages that MUST rank. These get every phase at 10x depth. 5. **"We're ranking fine" is the pre-crash calm (Popper).** Rankings today don't mean rankings tomorrow. FALSIFY every "we're doing well" claim with trend analysis, competitor movement, and algorithm vulnerability assessment. **Gestalt Hinge Pages:** Before Phase 1, identify THE pages that drive business value. Homepage. Pricing. Key landing pages. Product pages. THESE pages get every phase at maximum depth. **Popper SEO Falsification Categories:** - **LAB vs FIELD** — Lighthouse 100, but actual indexation is 30% of pages - **DESKTOP vs MOBILE** — Ranks on desktop, invisible on mobile-first index - **CACHED vs RENDERED** — HTML source looks fine, rendered DOM is empty - **TODAY vs TREND** — Ranking #3 today, dropped from #1 in 3 months - **TECHNICAL vs CONTENT** — Perfect technical SEO, zero topical authority --- ## SCOPE DETECTION (automatic) ``` EXAMPLES: "/seoaudit" -> Full 20-phase pipeline. Discover all pages, audit everything. "/seoaudit the blog" -> TARGETED: only blog pages and content strategy "/seoaudit technical" -> TECHNICAL-FOCUSED: crawlability, indexability, speed, structure "/seoaudit content" -> CONTENT-FOCUSED: E-E-A-T, topic clusters, keyword optimization "/seoaudit vs competitor.com" -> COMPETITIVE: SERP analysis, gap identification, authority comparison ``` --- ## OUTPUT CONTRACT ``` audits/.seoaudit/ |-- session.log |-- discovery/ | |-- pages.json # All discovered URLs | |-- sitemap-analysis.json # Sitemap vs actual pages | |-- robots-analysis.json # Robots.txt directives | |-- redirect-map.json # All redirects found |-- reports/ | |-- crawlability.md # Phase 1 | |-- indexability.md # Phase 2 | |-- core-web-vitals.md # Phase 3 | |-- schema-markup.md # Phase 4 | |-- meta-tags.md # Phase 5 | |-- heading-hierarchy.md # Phase 6 | |-- image-seo.md # Phase 7 | |-- url-structure.md # Phase 8 | |-- mobile-friendliness.md # Phase 9 | |-- page-speed.md # Phase 10 | |-- content-quality.md # Phase 11 | |-- internal-linking.md # Phase 12 | |-- external-links.md # Phase 13 | |-- hreflang.md # Phase 14 | |-- pagination.md # Phase 15 | |-- redirect-chains.md # Phase 16 | |-- broken-links.md # Phase 17 | |-- js-rendering.md # Phase 18 | |-- geo-aeo.md # Phase 19 | |-- competitor-serp.md # Phase 20 |-- verdict.json |-- verdict.md |-- fix-plan.json |-- fix-plan.md |-- progress.json |-- fix-log.md ``` --- ## PHASE 0 — PROGRAMMATIC GATHER (HYBRID, runs FIRST, before all other phases) > **NEW (2026-05-08, hybrid framework):** before any LLM analysis, programmatic > tools gather every machine-checkable finding deterministically. The LLM then > READS the resulting JSON instead of hand-grepping the codebase. Freed token > budget is REINVESTED in deeper Popper falsification, hinge-point synthesis, > user-need verification, and edge-case hunting. ### 0.1 Run the gather script (mandatory, FIRST step) ```bash ~/.omega/lib/audit-runner.sh seo "$PROJECT_PATH" \ --files="$FILES_MODIFIED" \ --url="$URL" \ --user-need="$USER_NEED_QUOTE" \ --hinge="$HINGE_POINT" \ --ticket="$TICKET_ID" ``` This invokes `~/.omega/lib/audit-gather/seo.sh` which runs: Lighthouse SEO category, head/HTML fetch with canonical+og+twitter+schema parsing, robots.txt fetch, sitemap.xml fetch + URL count Output is written to: ``` $PROJECT_PATH/audits/.seoaudit/ ├── raw/ # raw tool outputs (JSON / text per tool) └── evidence-summary.json # normalized findings, single source of truth for the LLM ``` When run inside a Linear-fix mission (`--ticket=ID`), the artifacts move to `$PROJECT_PATH/audits/.linear-fix/<ID>/.seoaudit/` so multiple audits on the same ticket can cross-reference each other (see 0.5). ### 0.2 evidence-summary.json schema ```jsonc { "audit": "seo", "tools_run": ["..."], "tools_skipped": [{"tool": "...", "reason": "..."}], "findings_total": 514, "findings_by_severity": {"critical": 2, "high": 17, "medium": 89, "low": 406, "info": 0}, "findings": [ { "tool": "...", "severity": "critical|high|medium|low|info", "location": "file:line[:col]", "rule": "...", "message": "...", "suggested_fix": "...", "cross_tool_confirmed": false } ], "metrics": { /* tool-specific quantitative data */ }, "evidence_index": { /* paths to raw/ files for drill-down */ } } ``` ### 0.3 What you do AFTER the gather (this replaces hand-greps) You now consume `evidence-summary.json` programmatically. You MUST: 1. **Read `evidence-summary.json` in full.** This is your evidence base. 2. **Read 3-5 critical files only** — the ones flagged as load-bearing in `~/.omega/state/hinge-points-<ticket>.json` (or computed via `${OMEGA_DIR:-$HOME/.omega}/skills/audits/_shared/hinge-analyzer.sh` if no ticket). 3. **DO NOT manually grep the codebase for what the gather already covered.** The tools have already exhaustively scanned every file. Re-running grep wastes tokens and produces the same evidence. 4. **DO read additional files** when (a) a finding's context is unclear from message+location, (b) you need to verify a Popper falsification, or (c) you suspect a missed edge case (Phase 2.4 below). ### 0.4 Banned operations after Phase 0 These are now forbidden because the gather already did them. If you catch yourself about to run one, STOP and read `evidence-summary.json` first: - ❌ `grep -rn "TODO" .` (the gather scanned for it) - ❌ `find . -name "*.ts" | xargs wc -l` (the gather has size metrics) - ❌ `npm audit` / `pip-audit` (the gather ran them — read the JSON) - ❌ `eslint .` / `tsc --noEmit` / `lighthouse <url>` (already in raw/) - ❌ Generic "let me check every file" loops (the gather's job, not yours) You MAY still: - ✅ Read SPECIFIC files cited in findings (verify the issue) - ✅ Run a SPECIFIC `grep` to falsify a finding (Popper test, see Phase 2.1) - ✅ Run a SPECIFIC tool the gather couldn't (e.g. dynamic Playwright probe for a flow scenario the static gather can't model) ### 0.5 Cross-audit synthesis (read sibling evidence-summary.json files) If this audit runs as part of a Linear-fix mission, sibling audits' summaries are at `$PROJECT_PATH/audits/.linear-fix/<TICKET>/.<other-audit-id>/evidence-summary.json`. Read them. Use them. Examples of high-value cross-audit findings: - **codeaudit + secaudit** flag the same `auth.ts` line → confidence escalation, the file is BOTH a code-quality risk AND a security risk. - **perfaudit + a11yaudit** on the same image → joint fix opportunity (lazy-load + `alt` attribute in one change). - **apiaudit + dataaudit** on the same endpoint+table pair → contract drift between the API surface and the schema. - **debugaudit + flowaudit** report the same broken page → user-flow blocker. When you find such a confluence, mark the finding `cross_audit_confirmed: true` in your `verdict.json` and bump severity by one level. --- ## PHASE 0: RECONNAISSANCE > *"Know the site's search identity before diagnosing."* ``` 1. PROJECT DISCOVERY -> Read CLAUDE.md, README, package.json -> Identify: framework, SSR/SSG/CSR, hosting, CDN -> Find: prod URL, target audience, target keywords, business model 2. PAGE/ROUTE DISCOVERY -> Crawl all pages from sitemap + internal links -> Build complete URL inventory with response codes -> Identify page types (landing, blog, product, category, utility) -> Compare sitemap URLs vs actually discoverable pages 3. SEARCH IDENTITY -> Current domain authority / domain rating estimate -> Indexed page count (site: search) -> Cached version check (Google cache) -> Search Console data if available -> This becomes the "before" for comparison ``` --- ## PHASE 1: CRAWLABILITY > *"If Googlebot can't reach it, it doesn't exist."* ``` 1. ROBOTS.TXT -> robots.txt exists and is valid -> No critical pages blocked (check Disallow rules) -> Sitemap reference present -> Crawl-delay directives (may slow indexation) -> User-agent specific rules reviewed 2. META ROBOTS -> No accidental noindex on important pages -> nofollow not blocking internal link equity -> X-Robots-Tag headers checked -> noarchive, nosnippet used intentionally (not accidentally) 3. CANONICAL TAGS -> Every page has a self-referencing canonical -> No canonical pointing to non-existent URLs -> No canonical conflicts (rel=canonical vs 301) -> Canonical consistent between HTTP/HTTPS, www/non-www -> No chain canonicals (A -> B -> C) 4. CRAWL BUDGET -> Low-value pages (search results, filters) noindexed or blocked -> Parameter handling (URL parameters not creating duplicates) -> Infinite crawl spaces (calendars, faceted navigation) contained -> Crawl depth: important pages within 3 clicks from homepage FALSIFY: Fetch as Googlebot. If ANY important page returns different content or a block, crawlability is compromised. ``` --- ## PHASE 2: INDEXABILITY (PART OF THE HINGE) > *"Crawled doesn't mean indexed. Indexed doesn't mean ranked."* ``` 1. SITEMAP AUDIT -> XML sitemap exists and is valid -> Sitemap contains only indexable, canonical pages -> No 404s, redirects, or noindexed pages in sitemap -> Sitemap last modified dates accurate -> Sitemap index for large sites (> 50K URLs) -> Sitemap submitted to Search Console 2. INDEX COVERAGE -> site:domain.com count matches expected pages -> Compare indexed count vs sitemap count -> Identify pages that SHOULD be indexed but aren't -> Identify pages that ARE indexed but shouldn't be -> Check for index bloat (thin/duplicate pages indexed) 3. INTERNAL LINK ARCHITECTURE -> Homepage links to all primary sections -> Important pages have high internal link count -> Orphan pages (no internal links pointing to them) -> Link equity distribution (flat vs deep hierarchy) 4. DUPLICATE CONTENT -> Near-duplicate pages identified -> HTTP vs HTTPS versions (redirect to one) -> www vs non-www (redirect to one) -> Trailing slash vs non-trailing (consistent) -> Print/mobile/AMP versions properly canonicalized FALSIFY: Search for exact phrases from key pages. If they don't appear, Google hasn't indexed or has devalued the content. ``` --- ## PHASE 3: CORE WEB VITALS (PART OF THE HINGE) > *"Google measures these. Your ranking literally depends on them."* ``` 1. LCP (Largest Contentful Paint) — target < 2.5s -> Measure on EVERY template/page type -> Mobile and desktop separately -> Identify LCP element per page -> Common issues: unoptimized images, render-blocking resources 2. INP (Interaction to Next Paint) — target < 200ms -> Measure responsiveness on interactive pages -> Heavy JS pages particularly critical -> Forms, filters, navigation interactions 3. CLS (Cumulative Layout Shift) — target < 0.1 -> Measure on every page (especially with images, ads, dynamic content) -> Web fonts causing shifts -> Late-loading elements pushing content 4. FIELD DATA vs LAB DATA -> CrUX data (real users) vs Lighthouse (simulated) -> If field data is worse than lab, there's a hidden problem -> Segment by device type and connection speed FALSIFY: Test on 3G throttled mobile. If CWV fails there, you're failing for a significant user segment — and Google knows it. ``` --- ## PHASE 4: SCHEMA.ORG MARKUP > *"Schema is your direct communication channel with Google. Silence is a choice — a bad one."* ``` 1. REQUIRED SCHEMA PER PAGE TYPE -> Homepage: Organization, WebSite, SearchAction -> Blog posts: Article, BlogPosting with author, datePublished