SEO: Technical and On-Page Audit to Strategy Brief

# Title: SEO: Technical and On-Page Audit to Strategy Brief
#
# Public workflow: diagnose a site or page across technical, on-page, off-page,
# and GEO/AI-citation lenses in one pass, turn the evidence-bound findings into
# a tiered, traceable, KPI-tagged strategy brief, then have a SEPARATE auditor
# check every recommendation against the finding IDs it claims to address and
# send the strategist back once if any is orphaned or KPI-less. Public roles only.

name        = "seo"
description = "Runs an SEO audit of a site or page across technical, on-page, off-page, and GEO (generative engine optimization) lenses, then turns the evidence-bound findings into a tiered, finding-traceable, KPI-tagged SEO strategy brief."

# ── 1. Audit ─────────────────────────────────────────────────────────────────
[[steps]]
name    = "audit"
role    = "seo:audit"
session = "fresh"
prompt  = """
Run ONE multi-lens SEO audit of the target below, covering all four lenses in a
single pass: TECHNICAL (crawlability, indexability, render, Core Web Vitals,
structured data, internal-link graph, robots/sitemaps), ON-PAGE (title/H1/meta,
content depth, E-E-A-T, thin/duplicate content, schema coverage), OFF-PAGE
(backlinks, brand mentions, authority gaps vs competitors), and GEO/AEO (is the
content AI-extractable: answer/TL;DR blocks, FAQ/HowTo schema, original
stats/quotes/citations, AI-citation presence).

Emit a flat, prioritized findings list. Give every finding a stable ID (F1, F2,
…) and tag it: {id, lens, evidence_url, observation, impact:H/L, effort:H/L}.
Every finding MUST cite a concrete URL or observed signal — if a check could not
run, mark it Unverified, never invent a finding.

<target>
{{input}}
</target>

Output only the audit report with its tagged, ID'd findings — no strategy.
"""

# ── 2. Strategy brief ────────────────────────────────────────────────────────
[[steps]]
name           = "strategy"
loop           = true
max_iterations = 2
exit_when      = { output = "trace", matches = '(?m)^VERDICT: TRACEABLE' }

  [[steps.run]]
  name    = "strategist"
  role    = "seo:strategist"
  session = "continue"
  prompt  = """
Turn the audit findings below into a prioritized SEO strategy brief.

Sequence the work by tier and keep that order: Tier 1 = crawl/index/critical
technical (these gate everything — schedule first); Tier 2 = on-page/content
quality and keyword gaps on high-traffic pages; Tier 3 = off-page links/brand and
GEO/AI-visibility. Float high-impact/low-effort quick wins to the top within each
tier. Build the forward plan from Tier 2/3 findings: keyword research mapped to a
topic-cluster model (1 pillar per core topic + cluster pages, bidirectional
internal links, no cannibalizing overlap), an off-page/link shortlist, and the
GEO content tactics needed to win AI citations.

Rules:
- Every recommendation must reference the audit finding ID(s) it addresses. Do
  not invent work that maps to no finding.
- Every action carries its validation KPI so success is verifiable later —
  classic (indexed pages, organic clicks/impressions, keyword position, Core Web
  Vitals pass-rate, referring-domain growth) and GEO (AI citation rate, AI
  share-of-voice across ChatGPT/Perplexity/AI Overviews/Gemini, AI-referred
  sessions, prompt coverage).

Close with the final roadmap: a sequenced action list (Tier 1 → 2 → 3, quick
wins surfaced) with the validation KPI attached to each item.

On a later iteration you will receive the auditor's findings: fix exactly the
flagged recommendations — re-map to a real finding ID, attach the missing KPI,
or drop the item. Do not invent findings to justify work.

<audit>
{{audit}}
</audit>

Output only the strategy brief — no preamble, no commentary.
"""

  [[steps.run]]
  name    = "trace"
  role    = "seo:audit"
  session = "fresh"
  prompt  = """
You are an independent traceability auditor in a fresh session. You did not write
this brief. Check it against the audit findings — never from memory.

<audit>
{{audit}}
</audit>

<brief>
{{strategist}}
</brief>

Checks, in order:
1. Every recommendation cites at least one finding ID that exists in the audit
   and actually addresses it. Orphaned or mismatched IDs are failures.
2. Every action carries a validation KPI.
3. Tier order holds (Tier 1 technical before Tier 2 content before Tier 3
   off-page/GEO) and no recommendation duplicates another.

List each failing recommendation with the fix needed — this goes straight to the
strategist. If every check passes, approve; do not invent new criteria.

Critique first, then end with exactly one line: VERDICT: TRACEABLE or VERDICT: REVISE. Nothing after it.
"""

# ── 3. Deliver — final brief with its audit status ───────────────────────────
# The loop's last output is the auditor's critique, so the brief is re-emitted
# as the final step's result.
[[steps]]
name    = "deliver"
role    = "seo:strategist"
session = "fresh"
prompt  = """
The traceability loop is finished. Output the strategy brief below verbatim,
whole, with no edits of your own. If the final audit does not end in
`VERDICT: TRACEABLE`, put one line above it — `Unverified: the traceability
audit still flagged recommendations; recheck these before acting:` — followed
by the auditor's remaining findings as a short list. If it does, add nothing
above the brief.

<brief>
{{strategist}}
</brief>

<final_audit>
{{trace}}
</final_audit>
"""