From issue found to issue fixed

Every one of the checks we run can be exported as a prompt or a markdown brief, written for a coding agent rather than for a meeting.

Generate my first fix Try a free search

fix-heading-hierarchy.md

# Fix: Heading Hierarchy Skip

**Site:** https://example.com

**Check:** `seo-heading-hierarchy-broken` · **Severity:** warning · **Category:** SEO · **Affected pages:** 1

## What's wrong
The heading hierarchy on the page https://example.com/ is broken, with a skip from H1 to H3 without an intervening H2. The crawler observed this skip, which is reported as "H1 → H3 (skipped H2)". This defect is detected by the "seo-heading-hierarchy-broken" check. The page's current heading structure does not follow the standard hierarchical order.

## Why it matters
The broken heading hierarchy hurts accessibility and SEO structure, making it difficult for screen readers and search engines to understand the content structure. This can lead to a poor user experience, especially for users relying on assistive technologies. Proper heading hierarchy is essential for conveying the organization and importance of content.

## How to fix
1. Find the code responsible for generating the headings on the page https://example.com/ by searching for the string "H1" and "H3" in the HTML template or rendering code.
2. Insert an H2 heading between the existing H1 and H3 headings to maintain the correct hierarchical order.
3. Ensure the final HTML output includes the corrected heading structure, such as: `<h1>...</h1><h2>...</h2><h3>...</h3>`.
4. If the wording or content of the new H2 heading requires human judgement, use a safe default such as "Introduction" or "Overview" to maintain the hierarchical structure.

## Acceptance criteria
- [ ] The page https://example.com/ has a corrected heading hierarchy with no skipped levels.
- [ ] The HTML source of the page includes an H2 heading between the H1 and H3 headings.
- [ ] The page's heading structure follows the standard order: H1 → H2 → H3.

## Affected pages

| # | URL | Observed value |
| --- | --- | --- |
| 1 | `https://example.com/` | `H1 → H3 (skipped H2)` |

## Ground rules for the agent

- Start by identifying the stack yourself (package manifest, config files, template extensions) and adapt every step below to it. The steps describe the required output, not the framework.
- Treat the URLs and observed values above as facts from a real crawl. Do not invent additional affected pages.
- Prefer fixing the shared template or layout over patching one page, then confirm the change reaches every affected URL listed.
- Change content and templates, not URLs — renaming a route creates redirects and breaks inbound links.
- If a fix needs copy written (titles, descriptions), draft it from the page's existing content rather than inventing claims about the product.
- Make one issue-type change per commit so a regression can be bisected.
- Do not mark an item complete until its acceptance criterion is actually verifiable.

A real export for a single failing check. Copy it into your agent, or download the same file.

Audits are good at finding. They're bad at fixing.

Every SEO tool on the market ends at the report. That's the moment the work actually starts.

A finding is not a task

"14 pages missing canonical tags" is a fact. Turning it into work means listing the URLs, deciding where the fix belongs, and defining done. That translation is where audits stall.

The context gets lost

By the time a finding reaches whoever fixes it, the evidence is gone: which tag, which page, what was expected. So they re-investigate what the crawler already knew.

Agents need scope, not vibes

Hand an agent "improve our SEO" and you get a refactor. Hand it one defect, the affected URLs, and acceptance criteria, and you get a clean diff.

Four steps, no copy-paste archaeology

Pick an issue

Open any failing check in your report, missing canonicals, unclaimed FAQ schema, 14 pages with no H1.

Export the fix

One click turns it into a prompt for chat, or a markdown brief you can drop into your repo.

Hand it to your agent

Paste the prompt, or point your agent at the file. It arrives with the affected URLs and the acceptance criteria already written.

Re-crawl and confirm

Run the audit again. The check either passes or it does not, no guessing whether the fix landed.

Written so an agent can act without asking

Each brief carries everything the crawler already knew, in the order an agent needs it.

01The problem, stated preciselyWhat the check looks for, what your site does instead, and why it costs you, so the agent is not reverse-engineering intent from a title.
02Every affected URLThe exact list from your crawl, not a sample. An agent that can see all 14 pages fixes all 14 pages.
03The evidenceThe tag that was found, the tag that was expected, the status code, the depth, whatever the check actually measured.
04Acceptance criteriaA checklist the agent can verify itself, phrased so re-running the audit is the definition of done.
05Scope guardrailsWhat not to touch. Fix briefs are narrow on purpose, so a canonical-tag task does not turn into a refactor.

From brief to diff

The brief is the input. This is what comes out the other side, and the check that proves it landed.

the change an agent makes

  <section class="pricing">
    <h1>Warm up your sending domain</h1>
+   <h2>How the warmup works</h2>
    <h3>Week one: low volume, high engagement</h3>
    <p>...</p>
  </section>

Heading hierarchy: no skipped levels

Re-crawl the same check. It either flips to passing or it does not, which is the difference between shipping a fix and assuming one.

The diff is an example of the change an agent would make. Your agent writes the code, not us.

A brief for every kind of failure

Canonical tags are a markup fix. The export is not limited to markup, so here are three failures of genuinely different shapes.

config

Missing Content-Security-Policy

Not a code change at all. It gives both routes, a meta tag or a response header, because which one is right depends on a stack the crawler cannot see.

fix-missing-csp.md

# Fix: Missing Content-Security-Policy Header

**Site:** https://example.com

**Check:** `sec-missing-csp` · **Severity:** info · **Category:** SEO · **Affected pages:** 1

## What's wrong
The page at https://example.com/ does not send a Content-Security-Policy header, which is a crucial security feature to prevent cross-site scripting (XSS) and resource-injection attacks. The audit found that the page has no Content-Security-Policy header, leaving it vulnerable to these types of attacks. This was detected by the absence of the header in the page's HTTP response.

## Why it matters
The absence of a Content-Security-Policy header makes the site more susceptible to XSS and resource-injection attacks, which can compromise user data and site integrity. Search engines and AI answer engines may also view the site as less secure, potentially impacting its visibility and credibility. This can lead to a loss of user trust and potential security breaches.

## How to fix
1. Search for the HTML `<head>` tag or the template helper that generates it, as this is where the Content-Security-Policy header is typically defined.
2. Add a `<meta>` tag with the `http-equiv` attribute set to "Content-Security-Policy" and the `content` attribute set to a policy that defines the allowed sources for the site's resources, such as `default-src 'self'; script-src 'self' https://cdn.example.com;`.
3. Ensure the final HTML output includes a `<meta>` tag similar to: `<meta http-equiv="Content-Security-Policy" content="default-src 'self'; script-src 'self' https://cdn.example.com;">`.
4. Alternatively, configure the web server to send a Content-Security-Policy header in the HTTP response, with a policy that defines the allowed sources for the site's resources, such as `Content-Security-Policy: default-src 'self'; script-src 'self' https://cdn.example.com;`.

## Acceptance criteria
- [ ] The page at https://example.com/ sends a Content-Security-Policy header in its HTTP response.
- [ ] The Content-Security-Policy header defines a policy that allows resources to be loaded from the site's own domain ('self') and any other necessary domains (e.g., CDNs).
- [ ] The page's HTML does not contain any inline scripts or styles that are not explicitly allowed by the Content-Security-Policy.

## Affected pages

| # | URL | Observed value |
| --- | --- | --- |
| 1 | `https://example.com/` | `No Content-Security-Policy header` |

## Ground rules for the agent

- Start by identifying the stack yourself (package manifest, config files, template extensions) and adapt every step below to it. The steps describe the required output, not the framework.
- Treat the URLs and observed values above as facts from a real crawl. Do not invent additional affected pages.
- Prefer fixing the shared template or layout over patching one page, then confirm the change reaches every affected URL listed.
- Change content and templates, not URLs — renaming a route creates redirects and breaks inbound links.
- If a fix needs copy written (titles, descriptions), draft it from the page's existing content rather than inventing claims about the product.
- Make one issue-type change per commit so a regression can be bisected.
- Do not mark an item complete until its acceptance criterion is actually verifiable.

whole audit

The entire audit as one plan

Every failing check in one file, ordered errors first and widest blast radius first, so an agent can work straight down it.

fix-plan.md

# SEO / AEO / GEO fix plan — https://example.com

**Site:** https://example.com

**Issue types:** 4 · **Affected pages:** 1

## Work order

Fix in the listed order: errors before warnings, and within a severity the widest blast radius first.

| # | Severity | Category | Issue | Pages | Check |
| --- | --- | --- | --- | --- | --- |
| 1 | warning | SEO | Heading Hierarchy Skip | 1 | `seo-heading-hierarchy-broken` |
| 2 | warning | AEO | Homepage Missing Organization or LocalBusiness Schema | 1 | `aeo-missing-organization-schema` |
| 3 | warning | SEO | Images Missing Width/Height Attributes | 1 | `seo-images-missing-dimensions` |
| 4 | info | SEO | Missing Content-Security-Policy Header | 1 | `sec-missing-csp` |

## Issues

### 1. Heading Hierarchy Skip

**Check:** `seo-heading-hierarchy-broken` · **Severity:** warning · **Category:** SEO · **Affected pages:** 1

### What's wrong
The crawler observed a heading hierarchy skip on the page https://example.com/, where an H1 heading is directly followed by an H3 heading, skipping the H2 level. This skip in heading levels can cause issues with the page's structure and accessibility. The current heading hierarchy is H1 → H3, which is not the recommended order.

### Why it matters
Proper heading hierarchy is important for screen readers and search engines to understand the content structure of a page. A broken heading hierarchy can lead to poor accessibility and negatively impact search engine optimization (SEO). This can result in a suboptimal user experience, particularly for users relying on assistive technologies.

### How to fix
1. Find the code responsible for generating the headings on the page https://example.com/ by searching for the string "H1" and "H3" in the HTML template or rendering code.
2. Insert an H2 heading between the existing H1 and H3 headings to maintain a logical heading hierarchy.
3. Ensure the final HTML output includes the corrected heading hierarchy, such as: `<h1>...</h1><h2>...</h2><h3>...</h3>`.
4. If the wording of the new H2 heading requires human judgement, use a safe default such as "Introduction" or "Overview" to maintain a coherent content structure.

### Acceptance criteria
- [ ] The page https://example.com/ has a corrected heading hierarchy with no skipped levels.
- [ ] The HTML output of the page includes an H2 heading between the H1 and H3 headings.
- [ ] The page's content structure is logical and accessible, with a clear heading hierarchy.

#### Affected pages

| # | URL | Observed value |
| --- | --- | --- |
| 1 | `https://example.com/` | `H1 → H3 (skipped H2)` |

### 2. Homepage Missing Organization or LocalBusiness Schema

**Check:** `aeo-missing-organization-schema` · **Severity:** warning · **Category:** AEO · **Affected pages:** 1

### What's wrong
The homepage of https://example.com/ is missing Organization or LocalBusiness schema, which is a type of structured data that provides information about a company or organization. The crawler observed that there is no JSON-LD markup on the homepage that includes the required properties such as name, url, logo, sameAs, and contact details. This deficiency was detected on the homepage, which is a critical page for search engines and AI assistants to understand the brand's identity.

### Why it matters
The absence of Organization or LocalBusiness schema on the homepage hinders AI assistants' ability to build knowledge-graph entries for the brand, making it harder for them to answer questions about the company. This can lead to incomplete or inaccurate information being presented to users. As a result, the brand's online presence and credibility may be negatively impacted.

### How to fix
1. Find the code responsible for rendering the homepage by searching for the `<html>` or `<body>` tag, or the template helper that generates the page content.
2. Add a JSON-LD script tag to the `<head>` section of the HTML document with the required Organization schema properties, such as `name`, `url`, `logo`, `sameAs`, and `contact` details.
3. Ensure the `name` property is set to a human-readable name for the organization, and the `url` property is set to the canonical URL of the homepage. If unsure about the canonical URL, use https://example.com/ as a safe default.

### Acceptance criteria
- [ ] The homepage https://example.com/ contains a JSON-LD script tag with the `@type` property set to "Organization" or "LocalBusiness".
- [ ] The JSON-LD markup includes the required properties: `name`, `url`, `logo`, `sameAs`, and `contact` details.
- [ ] The `name` property is set to a human-readable name for the organization.
- [ ] The `url` property is set to the canonical URL of the homepage.

#### Affected pages

| # | URL | Observed value |
| --- | --- | --- |
| 1 | `https://example.com/` | `No Organization or LocalBusiness schema on homepage` |

### 3. Images Missing Width/Height Attributes

**Check:** `seo-images-missing-dimensions` · **Severity:** warning · **Category:** SEO · **Affected pages:** 1

### What's wrong
The audit found that 18 out of 19 images on the homepage of https://example.com/ are missing explicit width and height attributes. This defect causes layout shift when the images load, as the browser does not know the dimensions of the images until they are fully loaded. The affected page is the homepage, which is categorized as a critical page for user experience and search engine optimization.

### Why it matters
Missing image dimensions cause Cumulative Layout Shift (CLS), which is the #1 cause of layout shift. This can lead to a poor user experience, as the content of the page may shift or jump around while it is loading. Search engines may also penalize pages with high CLS, as it can negatively impact the overall user experience.

### How to fix
1. Find the responsible code by searching for `<img>` tags on the homepage of https://example.com/ that do not have `width` and `height` attributes.
2. Add `width` and `height` attributes to each `<img>` tag, for example: `<img src="image.jpg" width="100" height="100" />`.
3. Ensure that the `width` and `height` attributes are set to the correct values for each image, which may require human judgement to determine the correct dimensions.

### Acceptance criteria
- [ ] The homepage of https://example.com/ has no more than 0 images without `width` and `height` attributes.
- [ ] Each `<img>` tag on the homepage has both `width` and `height` attributes set to a valid integer value.
- [ ] The page source of https://example.com/ does not contain any `<img>` tags with missing or invalid `width` or `height` attributes.

#### Affected pages

| # | URL | Observed value |
| --- | --- | --- |
| 1 | `https://example.com/` | `18 of 19 images missing dimensions` |

### 4. Missing Content-Security-Policy Header

**Check:** `sec-missing-csp` · **Severity:** info · **Category:** SEO · **Affected pages:** 1

### What's wrong
The page at https://example.com/ does not send a Content-Security-Policy (CSP) header, which is a crucial security feature that helps prevent cross-site scripting (XSS) and resource-injection attacks. The audit found that the page has no CSP header, indicating a potential vulnerability. This defect was detected by the crawler, which observed the absence of the CSP header in the page's HTTP response.

### Why it matters
The absence of a CSP header makes the site more susceptible to XSS attacks, which can compromise user data and undermine trust in the site. Search engines and AI answer engines may also view the site as less secure, potentially affecting its ranking and visibility. This can have a concrete consequence on the site's reputation and user engagement.

### How to fix
1. Find the code responsible for generating the HTTP headers for the page at https://example.com/ by searching for strings related to HTTP header manipulation, such as "setHeader" or "header".
2. Define a Content-Security-Policy header that allows only the necessary resources to be loaded, using a syntax like `Content-Security-Policy: default-src 'self';`.
3. Set the CSP header for the page, ensuring that it is sent in the HTTP response, for example: `<meta http-equiv="Content-Security-Policy" content="default-src 'self';">` (note: this may not be the exact implementation, as it depends on the site's technology stack).
4. If the site loads resources from other domains, modify the CSP header to include those domains, using human judgement to determine which URLs are canonical and should be allowed.

### Acceptance criteria
- [ ] The page at https://example.com/ sends a Content-Security-Policy header in its HTTP response.
- [ ] The CSP header allows only the necessary resources to be loaded, with a syntax like `default-src 'self';`.
- [ ] The page does not load any resources that are blocked by the CSP header, indicating that the policy is correctly configured.

#### Affected pages

| # | URL | Observed value |
| --- | --- | --- |
| 1 | `https://example.com/` | `No Content-Security-Policy header` |

## Ground rules for the agent

- Start by identifying the stack yourself (package manifest, config files, template extensions) and adapt every step below to it. The steps describe the required output, not the framework.
- Treat the URLs and observed values above as facts from a real crawl. Do not invent additional affected pages.
- Prefer fixing the shared template or layout over patching one page, then confirm the change reaches every affected URL listed.
- Change content and templates, not URLs — renaming a route creates redirects and breaks inbound links.
- If a fix needs copy written (titles, descriptions), draft it from the page's existing content rather than inventing claims about the product.
- Make one issue-type change per commit so a regression can be bisected.
- Do not mark an item complete until its acceptance criterion is actually verifiable.

What we never touch

This page asks you to let an agent change your site. That deserves a straight answer about what PageInspection can and cannot reach.

The crawl is read-only
PageInspection fetches pages the way any crawler does, with its own user agent. It never submits a form, never sends a write request, and changes nothing on your site.
No repository access, and nothing to grant
There is no GitHub app, no OAuth scope, no deploy key and no CI integration. Not "we do not use it": there is no such integration in the product to connect.
The agent runs in your environment
PageInspection produces a text file. It does not execute anything, and it has no channel to your machine. Your agent runs where it already runs, with the permissions you already gave it.
You review the diff
The workflow ends at a change you approve, not a change that ships. Nothing here can deploy, and nothing here can open a pull request on your behalf.
Briefs are deliberately narrow
The exported file tells the agent to change templates rather than URLs, to make one issue-type change per commit, and never to invent affected pages beyond the ones the crawl observed. The guardrails in the anatomy above exist so a canonical-tag fix stays a canonical-tag fix.

The part nobody budgets for

The audit takes minutes. Turning it into work is what takes the week. Someone reads the report, decides what matters, writes the tickets, chases the context back down, and explains it to whoever is doing the fixing, who then has no reliable way to confirm it landed.

The export collapses that into a paste and a re-crawl. Nobody schedules the translation step, which is exactly why it is the one that slips.

It's plain markdown, so it works everywhere

No integration to install, no API key to paste, nothing to keep in sync. Copy the prompt into a chat, or commit the brief to your repo and point your agent at it.

Claude Code · Cursor · GitHub Copilot · Windsurf · Cline · Any LLM chat

Pair it with the 82-check audit and every failure on your site arrives as work you can hand off.

What you are actually agreeing to

Access, agents, and what happens when the change is wrong.

No, and there is nothing to connect it to. There is no GitHub app, no OAuth scope, no deploy key and no CI integration anywhere in the product. PageInspection crawls your site the way any visitor would and produces a text file. Whatever happens to that file afterwards happens in your environment, under your control.

Any of them, because the output is plain markdown. It is written for Claude Code, Cursor, GitHub Copilot, Windsurf and Cline in the sense that it assumes the reader can open your repository and grep it, but there is no integration to install: you paste the prompt into a chat, or commit the brief and point your agent at the file.

You see it before it ships, because the workflow ends at a diff you review rather than a change that deploys. The brief also constrains the work deliberately: it names only the URLs the crawl actually observed, tells the agent to change templates rather than URLs, and asks for one issue type per commit so a bad change is easy to isolate and revert. Then you re-crawl, and the check either passes or it does not.

No. Exporting a fix as a prompt or a markdown brief is available on a free account. You need an account rather than an anonymous free search, because a brief is built from a full crawl of your site.

Both. A single check exports as a focused brief covering just that defect and the pages it fired on. A whole audit exports as one plan with a work order at the top, the issues ordered by severity, and each one carrying its own affected pages, so an agent can work through it in sequence.

Partly, and it is worth being straight about where it stops. The brief describes the outcome your pages must have, deliberately without assuming a framework or a file layout, so the what and the why apply to any stack. What does not transfer is handing it to a coding agent that can grep a repository you do not have. On a hosted CMS the brief is still a precise, prioritized work order with the affected URLs and the acceptance criteria attached, which you or your developer apply through the admin, a theme editor or a plugin. Useful, but a paste-and-go workflow it is not.

Turn your next audit into a pull request

Run a crawl, pick an issue, export the brief. Free to start.

Try it free

No signup required. Each free search audits one page, paste any URL to see it in action.

Start free