Prompts

Give me a week-over-week pulse on how this brand does in AI answers.

If this organization runs more than one project, call list_projects() first. Then ask
which project the user means. To cover every project instead, repeat all the steps below
once per project, with its id as `project`. Wait a few seconds between projects, so that
one burst does not spend the organization's per-minute allowance. A key scoped to one
project needs none of this.

Call get_digest() first. It returns the server's week-over-week breakdown of the last
full calendar week against the week before. Then call get_overview(period="7d") and
get_perception(period="7d") for the current splits and the perception detail. The
digest's window is the calendar week. The windows of the other two end at the newest
collected day. Put the digest's `week` span in the headline. Do not reconcile small
differences between the two. They are different windows, not a discrepancy.

Report in this order:

1. The headline. Report `visibility` against `visibility_previous` from get_digest, over
   `answers` analysed answers, for the `week` span. If `previous` is null, this is the
   first measured week. Report the standing numbers, and report that the comparison
   starts next week. Never report a delta. If `measured` is false, no answers were
   analysed in the last full week. Report that, and report get_overview's trailing
   window instead.

2. The sharpest change. When `highlight` is present, it names one platform and one
   prompt. That platform recommended this brand in `recommended_previous` answers to
   that prompt the week before, and in none last week. Start with it, and quote the
   prompt text.

3. Movers. Each entry in `movers` holds a `movement` verdict. `appeared` and
   `disappeared` are events of their own: mentions started or stopped for a whole week.
   `up` and `down` come with both values. Report each mover.

4. Ground shifts. Each `shifts` row passed a share-of-voice reporting floor. Report each
   brand's share_of_voice against share_of_voice_previous. Report the recommended counts
   where they moved. `flipped` lists prompts that started or stopped naming this brand.
   Quote one or two.

5. Sources and standing issues. `domains` were newly cited last week. `actions` are the
   Actions first built last week, each with its headline and its answers. Report
   `crawlers_blocked` or `prompts_silent` whenever either is non-zero. Both are standing
   problems, not last week's news.

6. How the answers speak about this brand. From get_overview, report `sentiment` and
   `recommendation` as splits, not as an average. Report any `advised_against` count on
   its own, however small.

7. What this brand is known for. get_perception's `rows` are attribute and objection
   labels per brand. Each label has a 0-100 score and verbatim quotes behind it. Start
   with this brand's top attribute and its strongest objection. Report any objection
   that a competitor scores worse on. That is sales material. If `entitled` is false,
   Perception is not part of this plan. Report that, and do not report "nothing found".
   The digest's `perception` block shows whether new perception answers were collected
   last week. Start with any `first_objections`. Word them as first seen in the stored
   answers, not as the platforms changing their minds.

End with one paragraph: what changed, and the single thing worth doing about it this
week.

Find the competitors that moved, and report whether the movement matters.

Call list_competitors(period="7d") and get_overview(period="7d").

Treat a brand as moving when its `delta` differs from zero by more than 10 percentage
points. `visibility` and `delta` are fractions, so compare against 10/100.

For each mover:
- Report its name.
- Report its before and after values as percentages.
- Find where it moved. Call get_overview(platform=..., period="7d") for each platform in
  `per_platform`.

Then read `detected`: brands that the analysis found in answers and that nobody
monitors. A new brand there is the earliest signal available. It counts toward no score
until somebody promotes it. If `emerging` is false, that list is not part of this
organization's plan. Report that. Do not report an empty list as "no new competitors".

Report no movement for a brand whose `delta` is null. That is missing history, not a
flat line.

Decide which AI platform deserves attention next.

Call get_overview(period="7d") for the whole picture. Then call it once more for each
platform in `per_platform`, with platform= set each time. Every platform then gets its
own visibility, share of voice, sentiment and competitor table.

Build one table with these columns:
- platform
- answers collected
- answers that name this brand or any monitored competitor (`monitored_runs`)
- this brand's visibility
- its share of voice
- the strongest competitor on that platform.

Two readings look identical in a visibility score but mean opposite things. Keep them
apart. Report which reading applies to each platform:

- Low visibility, high `monitored_runs`. The platform answers this category by naming
  companies, and it names other companies. This is a losing position, and a winnable
  one.
- Low visibility, low `monitored_runs`. The platform answers without naming any company.
  There is nothing to win there yet. Work aimed at it is wasted.

End by reporting the platform to work on, and why. If the honest answer is "none of them
yet", report that. Do not pick the least bad one.

Grade the tracked prompts, and report which ones to change.

Call list_prompts(period="7d"). Sort every row into four groups:

- **Winning**: high `visibility`. Most answers name this brand.
- **Losing**: low `visibility` but high `monitored_runs`. The answers name companies,
  but not this brand. This is the group worth working on.
- **Silent**: `silent` is true. The recent answers named no company at all, so the
  prompt is not a buying question. Recommend rewording or dropping these prompts. No
  amount of work on this brand moves them.
- **Unproven**: few `runs`, or `failures` are a large share of them. These rows are not
  a result yet, and not evidence of anything.

For the two or three worst rows in **Losing**:
1. Call list_prompt_runs(prompt_id=...).
2. Call get_answer(run_id=...) on one recent answer.
3. Quote the sentence that names the competitor.

The quote is the finding. The score was only how you found it.

Call list_suggestions() as well. Each suggestion is a replacement prompt that the
product already derived from this project's own answers. Each one holds the evidence it
came from. Where a suggestion covers the same ground, prefer it to wording that you
invent. An empty list means that nobody has generated suggestions yet. Report that, and
do not fill the gap yourself. Generating is a button in the app.

Give each group a count. Then report the three prompts most worth changing, and what to
change them to.

Compare how this brand does across the markets it tracks.

Call list_markets(period="7d").

`markets` has one row per tracked market. The rows hold **counts, never rates**:
- `prompts`: how many active prompts run there
- `runs`: how many answers were collected there
- `named`: how many named this brand or any monitored competitor
- `present`: how many named this brand.

Visibility is `present / runs`. Calculate it. Do not look for it in the result.

If only one market is tracked, report that and stop. A comparison of one
market against itself is not a finding. A market recorded as ZZ is Worldwide:
its prompts steer at no country at all.

Each market runs its own prompts, which may differ in wording and language.
Say so when the markets' prompt counts differ, because two markets asked
different questions compare the questions as much as the markets.

Otherwise, report for each market:
- its visibility
- how it differs from the strongest market
- whether the difference is a losing position or an empty category.

Where `named` is far below `runs`, the answers in that market name nobody. That
is a different problem from answers that name a competitor. To confirm the
worst market, call get_overview(market=..., period="7d"). Read which
brands the answers name there instead.

Then split the same window by who asks. Call list_personas(period="7d").
`personas` has one row per persona, the last row being the prompts with no
persona, with the same counts. A persona with a `sentence` is asked as that
buyer: its sentence is sent in front of every prompt attached to it. Where one
persona's visibility is far below the others', the answers to that buyer name
somebody else, and the prompts attached to it say who was asked. One persona
is no comparison: report it and move on.

Then split it by subject. Call list_topics(period="7d"). `topics` has one
row per topic, the last row being the prompts with no topic, with the same
counts. A topic far below the others is a subject where the answers name
somebody else. One topic is no comparison: report it and move on.

End with the one market worth attention. If the difference does not justify
splitting effort, end with "the difference does not justify splitting effort".

Plan this week's work to get this brand into more answers.

Call list_actions(). list_gaps() is its older name and answers the same.

`actions` is the worklist, in rank order: an `unblock` first, then the losing answers
each Action touches. Each has a `headline` that words the verb. Work only from the open
rows. Leave out `done` and `dismissed` rows, and any row with `faded_at` set.

Read each kind for what it asks:
- `unblock`: the site's robots.txt turns away a search crawler. It is the cheapest fix
  and the one with the strongest evidence. Say it first.
- `gate`: a register, association or ranking. Inclusion is by application.
- `list`: a publisher of best-of lists. The action is an editorial pitch.
- `marketplace`: a review site. The action is a profile this brand creates.
- `press`: a publication. The action is a pitch to its editors.
- `platform`: a place this brand publishes under its own name.
- `community`: a forum. Taking part is earned and slow. Say so.
- `rival`: a monitored competitor's own site. The action is to publish the page its
  cited pages answer, not to contact it.
- `other`: the kind could not be read. Open one page before you judge it.
- `opening`: an objection the answers raise against competitors. `proposed` means the
  customer has not confirmed this brand does better there. Plan no work on a proposed
  Opening.

**Size it before ranking it.** `covered_answers` of `lost_answers` is how much of the
problem the destinations explain.

**State the claim exactly.** The answers that cited a page named those competitors. This
data cannot show whether a competitor's name appears on the page. So write "the answers
citing this page named X". Never write "this page mentions X".

For the top three Actions, call get_answer(run_id=...) on one of the evidence's `runs`
and read what the citation supported. Report the `searches` in the evidence: they are
the words the platform searched before it cited the page. Only ChatGPT and Grok report
them. list_searches() holds every search in the window.

Call list_sources() and compare `totals.citations` with `totals.answers`. In a category
whose answers cite little, getting written about moves less than getting mentioned does.
Read the worklist with that in mind.

End with the three Actions most worth this week, each with its headline, its answers and
one sentence on why.