OutlineDriven SEO / AEO audit
Contract
| Field | Bound contract |
|---|---|
| Trigger | Improve SEO, optimize for search, fix meta tags, add structured data, or improve AEO visibility. |
| Authority | Read-only. No file, VCS, credential, paid, published, deployed, or remote mutation. |
| Side effect | None: audit report only; no files are written, no services are modified. |
| Done | Report lists critical/high/medium issues, includes validated JSON-LD recommendations, and provides re-verification steps using Lighthouse, PageSpeed, and Search Console. |
Inputs
- URL(s) (required): The target page or site URL(s) to audit.
- Focus area (optional): Narrow the audit to one or more of:
technical,page,structured-data,aeo. Default: all four. - JSON-LD template (optional): A caller-supplied local template used to validate structured-data recommendations.
Procedure
- Confirm URL and scope. Require at least one target URL. Parse the scope argument or default to all four areas. Done when: the URL and scope are confirmed.
- Run technical SEO checks. Execute Lighthouse against the target URL. Parse the output for: crawlability signals, indexability, HTTP status, canonical tags, robots directives, hreflang, sitemap presence, and Core Web Vitals. Record every violation as critical, high, or medium. Done when: technical SEO violations are recorded with severity.
- Audit on-page elements. Fetch the page HTML. Parse title tags, meta descriptions, heading hierarchy (H1-H6), image alt attributes, internal/external link distribution, and content keyword density. Flag duplicate, missing, truncated, or over-stuffed elements. Done when: on-page element violations are recorded.
- Audit structured data. Extract all
<script type="application/ld+json">blocks from the fetched page. Validate each against the appropriate JSON-LD schema type (Article, BreadcrumbList, FAQPage, Product, Organization, LocalBusiness, HowTo, SpeakableSpecification, or others). Report malformed, missing, or conflicting markup. If JSON-LD templates are available, compare the live markup against the recommended template for each detected type. Done when: structured-data violations are recorded with corrected JSON-LD blocks. - Audit AEO visibility. Assess the page for answer-engine optimization signals: clear entity definitions in the first 100 words, FAQ or HowTo blocks, SpeakableSpecification in structured data, passage-level relevance, and citation eligibility signals. Do not fabricate rankings or citations. Done when: AEO visibility findings are recorded.
- Synthesize the report. Combine findings from steps 2-5. Assign every issue a severity: critical (blocks indexing), high (major ranking factor impact), or medium (improvement opportunity). Group under the four sections. For every structured-data finding, include the corrected JSON-LD block with the corrected fields shown. Done when: the report is synthesized with all findings grouped and severity-assigned.
- Add re-verification steps. After the findings, append a Verification section with step-by-step instructions using Lighthouse (command-line command to re-run the audit), PageSpeed Insights API (curl command to fetch the pagespeed API result), and Google Search Console (URL Inspection API steps to verify index status). Done when: the Verification section is appended.
- Return the report. Output the complete markdown report to the user. Do not write any file. Done when: the report is returned to the user.
Failure and recovery
- No URL provided: stop. Return
"error": "url_required"with the message "Audit requires a target URL." - Page unreachable: stop. Return
"error": "page_unreachable"with the URL and the response code or error text. - Script execution failure: catch the error. Return
"error": "tool_execution_failed"with the script name and error output. - Malformed JSON-LD detected: flag as a critical finding in the report. Include the raw block and the parsing error. Do not halt the audit.
- Zero findings in a category: state "No issues detected in this category" explicitly in the report rather than omitting the section.
- Partial tool results: include whatever data the tool returned. Mark any missing fields as
"status": "unavailable"in the tool output block.
Output
A markdown audit report with a header (target URL, audit timestamp, scope), four sections (Technical SEO, On-Page SEO, Structured Data, AEO Visibility) each with severity-labeled issues and fixes, validated JSON-LD code blocks for every structured-data fix, a Verification section with exact re-verification commands, and a summary table with issue count by severity.