# Visibility Diagnosis

Visibility Diagnosis answers one question for a prompt where your brand isn't getting cited: *why not, and what should I do about it?* It turns a lost prompt into specific work - a page to write, a page to fix, or a ranking to get onto.

![Visibility Diagnosis](/docs/images/prompt_diagnosis.png)

---

## What it does

An AI assistant doesn't search your prompt as written. It **fans the prompt out** into several smaller search queries, each covering a different angle, and answers from whatever it finds for those. Visibility Diagnosis reproduces that fan-out and checks you query by query.

For each fan-out query it decides whether you're **covered**, **weak**, or **missing**. It also reads the pages the AI actually cited for the prompt and sorts them into competitor pages and third-party rankings. The run returns one report per thing to act on:

WRITE NEW PAGE

Content brief

You have no page for the query, or the page you have is the wrong format for it. An outline of the page to write, built against the page currently winning that angle.

IMPROVE YOUR PAGE

Gap report

You have a page on the right topic, but it's losing. Your page compared with the competitor page that wins, and what yours is missing.

GET LISTED · STRENGTHEN

Listing report

The AI cited a third-party ranking (G2, Capterra, a "best X" round-up). Who it ranks, whether you're on it, and what to send the publisher.

One run can return any mix. A prompt that's partly covered gets briefs for the angles you're missing, gap reports for the ones you're weak on, and listing reports for any rankings the AI leaned on. If every query comes back covered and no ranking was cited, the run finishes with **No action needed**.

---

## How it works

1. **Check your standing.** Pulls your visibility for this prompt from the last 30 days of monitoring, and any of your own pages the AI has already cited for it.
2. **Fan out the prompt** into up to **5 search queries**. GrackerAI runs the prompt through a live AI web search and keeps the real queries the assistant issued. Only if that returns nothing does it generate queries itself. Each query is tagged with the page format that tends to earn the citation - **listicle**, **comparison**, or **blog**.
3. **Search your own site** for each query and **read your actual pages** - up to 8, always including any of your pages the AI has already cited - and mark every query covered, weak, or missing from the real page text.
4. **Pull the citations** the AI gave for this prompt over the last 30 days. Pages from vendors on your competitor list are **competitors**; other vendor pages are **cited pages**; rankings and review sites are **third-party listings**.
5. **Audit the listings.** Up to 3 third-party rankings are read to see who they rank, whether you're on them, and what the top entry has that yours doesn't.
6. **Branch per query:**
   - **Missing** → a **content brief**, written against the competitor page winning that query.
   - **Weak, wrong format** (you have a blog post, the query wants a listicle) → also a **content brief**.
   - **Weak, right format** → a **gap report** comparing your page with the winning competitor page. With no competitor page to compare against, GrackerAI audits your page on its own. It also kicks off an [AEO Audit](/docs/using-gracker/aeo-audit) on that page, so its score is ready next to the gap report.
   - **Covered** → nothing.

Two rules keep "covered" honest:

- A page only counts as covered when your monitoring shows you actually winning the prompt. If your measured visibility for it is low, or the prompt hasn't run yet, a covered query is downgraded to **weak** and the reason says so.
- A page that merely shares vocabulary with the query - a home page, a pricing page - is not a match. Unless the AI has already cited it, it's treated as **missing**.

Near-identical briefs are merged before you see them, so a run can return fewer reports than queries.

Because steps 1 and 4 read what your monitors captured, a diagnosis is only as complete as your recent monitoring. If a prompt hasn't run lately, [run its monitor](/docs/using-gracker/working-with-monitors/monitors) first so the diagnosis has fresh citations to work from.

---

## Running a diagnosis

1. **Find a prompt you're losing.** Open **Actions → Prompts Visibility** and look for a prompt with low score or presence.
2. **⋮ menu → Diagnose Visibility** on the row, or from the header of the Prompt Details drawer. Click **Run Agent**. The run is queued and finishes in the background.
3. **Open the result.** Once a report exists the same menu shows **Diagnosis report** and **Diagnose again**. Each run shows what it produced: *n to write*, *n to improve*, *n to get listed*, or *No action needed*.
4. **Act on it** - send a brief to [Articles](/docs/using-gracker/content/articles), open **View AEO audit** on the page you need to improve, or send anything to [Tasks](/docs/using-gracker/tasks).

Every diagnosis is saved as a **run**, so you can compare before and after. **Diagnose again** starts a fresh one. In [Prompt Management](/docs/using-gracker/working-with-prompts/prompts), any diagnosed prompt shows a chevron; click it to see the fan-out queries it was broken into.

**Audit → Visibility Diagnosis** lists every diagnosed prompt with its latest result, newest first. Filter by whether content exists, search by prompt text, and click a row to open its report and full run history.

Visibility Diagnosis runs count against your plan's limit.

---

## Reading the results

Results are three levels deep: **runs** → the **reports** in a run → one **report**. Each report targets one page cited for this prompt and links out to it. The label reads *competitor page* when the vendor is on your competitor list and *cited page* when it isn't.

### Content brief - "Write new page"

| Section | What it gives you |
|---|---|
| Title to use | The working title and meta description, with the page type and target word count |
| The answer to win | The answer your page has to own to earn the citation |
| Your angle to stand out | The differentiation angle against the page currently cited |
| Outline to write | Section-by-section outline |
| Points you must cover | Non-negotiable coverage |
| Claims to make | Citable claims - the statements that earn AI citations |
| Where the competitor falls short | Gaps in the page you're up against |
| Formats to use / Keywords | Page formats and the entities to name |

### Gap report - "Improve your page"

| Section | What it gives you |
|---|---|
| What to do first | Prioritised fixes, each tagged **quick** or **big** |
| Topics to add | Coverage the competitor has and you don't |
| Structure to improve | Layout and extractability problems |
| Evidence to add | Missing stats, sources, and proof |
| Freshness | Your page's date against the competitor's |

### Listing report - "Get listed" or "Strengthen your listing"

| Section | What it gives you |
|---|---|
| The listing | The ranking's title and publisher. Whether you're on it, and at what rank of how many |
| Who it ranks | Every vendor on the list, in order. Competitors you track are marked |
| What the top entry has | Concrete things the first entry includes that yours would need - a pricing table, named use cases, customer logos |
| What to send the publisher | Factual material you could supply to earn or improve your entry |

### Standards to cite

Cybersecurity brands get one more section on briefs and gap reports: the **NIST**, **MITRE**, and **CISA** references the page should cite, each linked to its official source. A reference is badged **Competitor cites this** when it was found on the winning competitor page, or **Named in this report** when the fixes above already ask for it. See [Cybersecurity Standards](/docs/advanced/industry-specialised/cybersecurity-standards).

### Acting from a report

The **⋮ menu** on a report offers **Add task**, **Create new content** (for a brief - the brief becomes the article instruction and the competitor page the reference), and **Improve existing content** (for a gap - your page is pre-filled). **View AEO audit** opens the audit of the page a gap report is about.

![Visibility Diagnosis Detail](/docs/images/prompt_diagnosis_on_click.png)

---

## Where Visibility Diagnosis fits

Visibility Diagnosis is the bridge between *seeing* a gap and *closing* it.

Having a page is not the same as covering the prompt. A page can answer the headline question and still miss three of the five angles an AI actually searches - which is why a run often returns **both** a brief and a gap report.

- **Prompt set unclear first?** [Prompt Diagnosis](/docs/using-gracker/working-with-prompts/prompt-diagnosis) checks whether the prompt is worth tracking at all before you diagnose its visibility.
- **No content?** → [Articles](/docs/using-gracker/content/articles) turns the brief into a draft.
- **Have content?** → the gap report shows what's missing; [AEO Audit](/docs/using-gracker/aeo-audit) scores the page and [Improve Visibility](/docs/using-gracker/improve-visibility) turns that into prioritised fixes.
- **The AI trusts a ranking, not vendors?** → the listing report tells you what the publisher needs from you.
- Zoom out with [Content Gaps](/docs/advanced/content-gaps) and [Improve Visibility](/docs/using-gracker/improve-visibility).

---

## Limits & gotchas

- Diagnosis reads the **citations and visibility your monitors captured in the last 30 days**. Run the prompt's monitor first if it hasn't run lately.
- It needs your **competitors set up** - the competitor list is what separates a competitor page from any other cited vendor.
- Every run is bounded: **5 fan-out queries**, **8 of your pages read**, up to **5 briefs**, **5 gap reports**, and **3 listing reports**. Deep prompts get the highest-probability angles, not all of them.
- **No citations in the last 30 days** → briefs are written from your own pages and the fan-out alone, without a competitor page to compare against.
- Results reflect the prompt **at diagnosis time**; re-run after you ship a fix to confirm you've closed the gap.

---

## Next Steps

- [Prompt Diagnosis](/docs/using-gracker/working-with-prompts/prompt-diagnosis): check the prompt set itself before diagnosing visibility
- [Citations](/docs/using-gracker/responses-and-citations/citations): the competitor pages and rankings behind a diagnosis

- [Articles](/docs/using-gracker/content/articles): turn a brief into a draft
- [AEO Audit](/docs/using-gracker/aeo-audit): score the page a gap report is about