Turn a technical AI audit finding into a developer-ready ticket (with a template)

A developer-ready ticket from an AI search site audit rests on four things: the exact affected URL, an observation someone else can reproduce, the behaviour you expect instead, and an acceptance check that says how everyone will know it is fixed. An audit finding on its own is a prompt for review, not a work order. Your job is to convert it into a request a developer can finish and verify without a meeting, and to say plainly what the finding does and does not prove. The template below does that.

In short

• Write one ticket per exact URL and per cause. Bundling ten findings into "fix the audit" gives a developer nothing to close.
• Reproduce before you file. State what the audit observed, how it observed it, and how the developer can see the same thing.
• Give the expected behaviour as a plain rule, not as "improve AI visibility". A rule can be checked; a hope cannot.
• Make the acceptance check a recheck of the same exact URL. Do not promise a citation or ranking outcome.
• Say what is uncertain. A finding is an observation from one lab request and one lab browser load, not proof of how any AI engine treats the page.

Why do audit findings fail as tickets?

Audit findings often fail because they describe a symptom in the auditor's words, without a URL the developer can open, a way to see it, or a definition of done. "Content needs JavaScript" is accurate, but a developer reading it cannot tell which page, what they should see instead, or when to close the ticket.

A site audit is a crawl of your own site that checks each page it finds and compares the raw HTML response with a browser render of the same page. In DiscoveredBy, Site audit does this as DiscoveredByBot and marks each check as Check passed, Needs review or Unknown. "Needs review" is a prompt to look, not a verdict: the docs describe the structure, response and render checks as disclosed heuristics from one lab request or one lab browser load, not Core Web Vitals, accessibility certification, a citation prediction or a grade.

That caution has to survive the trip into the ticket. If the ticket reads as "AI crawlers cannot see our pricing page", it claims something the audit never measured. The audit does not record whether real AI crawlers visited, and the HTTP delivery check does not simulate another crawler or establish access through a firewall for it.

If you are still deciding which findings deserve a ticket at all, that is a separate question, covered in an AI search site audit: which issues should you fix first?. This post starts once you have decided a finding is worth a developer's time.

What does a developer-ready ticket contain?

It contains eight fields, and four of them do most of the work: the affected URL, the observation, the expected behaviour and the acceptance check. A developer can start from the first three; they can only finish the ticket, and you can only accept it, if the acceptance check is there too.

Enlarge image

• Affected URL. The one exact URL, including path, capitalisation, trailing slash and query string. In DiscoveredBy's saved page diagnostics, history and recheck belong to the exact URL you requested, and paths, capitalisation, trailing slashes and query parameters are preserved. /pricing and /pricing/ are therefore different URLs there, so copy the URL from the audit, not from memory.
• Observation. What the audit saw, the check name, its state, and the evidence. Include the date and audit or run reference so the developer knows which snapshot you mean.
• How to reproduce. Steps a developer can follow without your tools. For raw HTML findings, that means viewing the delivered source rather than the rendered page in a browser inspector, because the whole point is the difference between the two.
• Expected behaviour. The state you want, stated as a rule.
• Acceptance check. How the ticket will be verified, in terms of a recheck.
• Scope and non-goals. What the developer should not change, such as content or design.
• Uncertainty. What the finding does not prove.
• Owner and follow-up. Who verifies, and who to ask if the fix needs a content decision.

How do you write the observation so it can be reproduced?

Write the observation as what was delivered versus what was rendered, with the audit's own wording for the check. The difference between the raw HTML response and the browser render is the most useful thing an audit can tell a developer, and it is easy to lose.

Crawlers that do not run JavaScript only ever see the raw HTML response, according to the site audit docs. A person opening the page in a browser sees the rendered result, so a developer who checks the page in the browser will often say "it looks fine". Tell them where to look:

• To see the delivered HTML, use the browser's view-source, or fetch the page with a command-line tool that does not run scripts. Both show a raw response, though a server can answer different clients differently. The browser's element inspector shows the page after scripts have run, which is the wrong view for this kind of finding.
• To see the rendered result, use the normal page or inspector.
• Name the check exactly as the audit does, for example "Content that needs JavaScript" or "Canonical URL", so the developer can match it to the documented rule.

Enlarge image

Quote the documented rule for the check in the ticket. The docs give specific review rules, for example that "Content that needs JavaScript" needs review when rendering adds at least 200 extra characters of text and at least doubles the raw HTML's text.

How do you state the expected behaviour?

State the expected behaviour as the negation of the review rule, plus any constraint the developer must respect. Most checks have a documented review rule, so the expected behaviour is usually "the page no longer meets that rule".

Some examples, taken from the documented rules:

• Canonical URL: the delivered HTML declares a canonical URL on the project domain, and any repeated canonical tags all declare the same URL. The docs note that declaring the same URL more than once is fine.
• Heading structure: exactly one H1, and no skipped heading level.
• Indexing directives: no noindex or none in a robots meta tag or X-Robots-Tag on this page, unless it is intentional.
• HTML response time and size: the full HTML response takes no more than 1,500 ms and is no more than 500,000 bytes.

Two cautions belong in the expected-behaviour field. First, some findings are deliberate. The docs say a deliberate crawler restriction can be appropriate, so a "Declared crawler policies" finding might be a decision, not a defect; confirm with the page owner before a developer removes a rule. Second, expected behaviour is a state of the page, not an outcome in AI answers. Do not write "so that ChatGPT cites us". You cannot promise that, and a developer cannot deliver it.

What makes a good acceptance check?

A good acceptance check is a recheck of the same exact URL that moves the finding from Needs review to Check passed, plus one manual confirmation from the delivered source. Saved recheck history is readable by every current project member, so it settles disputes.

DiscoveredBy's saved page diagnostics support this directly. When you recheck a URL, it compares the same check and destination with the previous completed run for that exact requested URL. A finding is labelled Resolved on recheck only when a previous review finding is followed by a passed check. You start it from Page diagnostics with Recheck and save on that URL. A later site audit also compares each page with the newest earlier audit result for the same exact URL, but the Resolved on recheck label belongs to saved page diagnostics, so name the method you will use in the ticket. Three details matter for your ticket wording:

• Unknown evidence never resolves a finding. If the recheck returns Unknown, the ticket is not accepted, and the cause of the unknown result becomes the next thing to investigate.
• A changed destination, a changed check version or a previously unknown result is labelled as lacking a comparable result. That is not a pass. Say in the ticket that a comparable result is required.
• These are observed response changes, not proof that a particular edit caused an outcome.

There are practical limits to plan around. A recheck needs a live release, so the acceptance check happens after deployment, not on a developer's branch. Starting a check needs owner or editor project access and, depending on your plan, robots diagnostics (see plans and limits), so tell the developer that verification is yours, not theirs, unless they have that access. Runs are also rate-limited: one start per minute, one active run per project, and 20 retained runs per exact URL. A recheck usually finishes within one to two minutes, and can take longer while a site audit is running.

Enlarge image

The ticket template

Copy this into your tracker. Fill every field; leave "n/a" rather than deleting a line, so a reviewer can see it was considered.

TITLE
[Check name] on [short page description]: [state], needs [one-line fix]

AFFECTED URL (one exact URL, as saved in the audit)
https://...

SOURCE OF FINDING
Tool and screen: (e.g. Site audit, page evidence)
Audit or run date:
Check name and state:  (Needs review / Unknown)
Evidence copied from the audit: (numbers, matched rule line, counts)

HOW TO REPRODUCE
1. Open the delivered HTML: (view-source, or a fetch that does not run scripts)
2. Look for: (the exact element, tag or text)
3. Compare with the rendered page: (what appears after scripts run)
Differences by user agent, login or region: (none known / describe)

DOCUMENTED RULE
The audit marks this Needs review when: (quote the rule)

EXPECTED BEHAVIOUR
After the fix, the delivered HTML: (state as a checkable rule)

ACCEPTANCE CHECK
1. Deployed to production.
2. Verifier reruns the check on the same exact URL.
3. Result is Check passed (or Resolved on recheck). Unknown or
   "no comparable result" does not count as done.
4. Manual confirmation in delivered source: (what to look for)

SCOPE AND NON-GOALS
In scope: (template, header, config)
Out of scope: (copy edits, design, other URLs)
Ask before changing: (anything that might be intentional)

WHAT THIS DOES NOT PROVE
- Not evidence of how any AI engine treats this page.
- Not a prediction of citations or visibility.
- Observed from one lab request and one lab browser load as DiscoveredByBot.

OWNER / VERIFIER / DUE
Requested by:
Verifier (has access to rerun the check):
Content decision owner:

Worked example: two tickets from one audit

Illustrative example: Quillstone and its competitors are fictional, and the numbers are made up to show the method.

Northfold Digital, a fictional agency, runs a site audit for Quillstone, which sells document-review software. The audit results include several Needs review items. Northfold picks two and files a ticket for each, rather than one ticket for the audit.

Ticket 1: Content that needs JavaScript on the pricing page. The audit shows that the raw HTML of https://www.quillstone.example/pricing/ has 310 characters of extractable text, while the browser render has 2,450. Rendering adds 2,140 characters, which is over the 200-character minimum, and 2,450 is more than twice 310 (double is 620), so the check needs review. The plan tables only appear after scripts run.

• Reproduce: view the page source and search for the plan names; they are absent. Open the live page; they are present.
• Expected behaviour: the plan names and their descriptions are present in the delivered HTML.
• Acceptance: the "Content that needs JavaScript" check passes on a recheck of the same URL, and the plan names are visible in view-source.
• Non-goal: no change to visual design.

Notice what the ticket does not say. It does not say AI engines cannot read the plans. It says the delivered HTML lacks them, which matches crawlers that do not run scripts.

Ticket 2: Canonical URL on a blog post. The audit shows that https://www.quillstone.example/blog/contract-review-checklist declares two different canonical URLs, one with a trailing slash and one without. The docs say that several different canonical URLs is a review finding, while the same URL declared twice is fine.

• Reproduce: view-source and search for rel="canonical"; two tags with different URLs appear.
• Expected behaviour: exactly one canonical URL, on the project domain.
• Acceptance: recheck shows the Canonical URL check as Resolved on recheck.
• Ask before changing: which of the two URLs the content team treats as the preferred version. That decision is not the developer's.

The second ticket includes a content-decision owner because a developer can remove a tag but cannot decide which URL is preferred. If you find yourself writing a ticket that needs a content decision first, that is closer to an editor task; give an editor a page-fix task they can finish without another meeting covers that side.

What about Unknown results?

An Unknown result means the check could not reach a conclusion, so it is usually a request for more evidence before it is a request for a fix. The audit docs say a page is skipped, not checked, when robots.txt could not be read because of a server error, a network failure or a redirect loop, or when the response is not declared as HTML. The cause may be a real site fault, such as a redirect loop, or a limit of the check. Filing "fix the page" against it asks a developer to solve a problem nobody has confirmed.

Instead, write an investigation ticket: the URL, which check is Unknown, the likely reasons the docs list, and the acceptance check "the check returns a definite state on recheck". Whether the state is then pass or review is decided afterwards. If the cause turns out to be robots.txt, see review a robots.txt change before it reaches production.

Common mistakes

• Filing the score, not the URL. A tool screenshot with no exact URL is not a ticket.
• Copying the check description as the fix. "Improve heading structure" tells a developer nothing; the rule and the page do.
• Promising outcomes. "This will get us cited" turns a routine fix into a failed promise if nothing changes in AI answers. Suggested changes are hypotheses to test.
• Closing on a hunch. A developer saying "looks fine in the browser" is not acceptance for a raw HTML finding. Use view-source and a recheck.
• Treating a deliberate rule as a bug. Confirm intent for robots and indexing findings first.
• Reading a pass as a guarantee. Check passed means the check found nothing to review at that time. It does not establish indexing, citation eligibility or complete page health.
• Letting evidence go stale. Saved evidence can become outdated; the recheck is the current observation. Note the date on every ticket.

Frequently asked questions

How many findings should go in one ticket?

One cause per ticket, per exact URL. If the same template causes the same problem on 40 pages, file one ticket for the template and list the affected URLs as evidence, with an acceptance check on a small named sample. The docs say each exact diagnostic URL has its own history, so name the sample.

Should the ticket include the audit's severity?

Include the check state (Needs review or Unknown), because that is what the tool reports. The docs describe no citation-gap impact or optimisation score for a diagnostic bundle, so do not invent a severity number. Priority is your team's call; see which audit issues to fix first.

Can a developer verify the fix without access to the tool?

Yes, for the delivered-HTML part: view-source shows the raw response. The recheck itself needs owner or editor access on the project, so the person with access should run it. Ask the developer to confirm in source, then have the verifier recheck.

What if the recheck says "no comparable result"?

Do not accept the ticket. That label appears when the destination or check version changed, or the earlier result was unknown. Run the check again on the exact requested URL, and if a redirect changed the destination, record that in the ticket.

Does a passed recheck mean AI engines will now cite the page?

No. It means the check found nothing to review in one lab request and browser load. Citations depend on the engine and the answer, and a recheck is an observed response change, not proof that an edit caused any outcome.

What if the finding is about JavaScript rendering and the developer disagrees?

Ask them to compare view-source with the rendered page for the named element. If the two differ, the finding stands as an observation. If not, record the user agent, login state and time they tested, and rerun the check.

Next step

Open Site audit in DiscoveredBy, pick one Needs review finding, copy the exact URL and the evidence, and fill in the template above. Then recheck that URL after the release and record the result on the ticket. To start, sign in to DiscoveredBy and open Site health. For the checks and limits behind each field, the saved page diagnostics and page issue queue docs are the references. If a finding raises a JavaScript question that needs its own analysis, read can a crawler see the content on your JavaScript-heavy page?.