Optimize
Articles
How a topic becomes a brief, a draft with its claims checked against the sources it names, and a published page tied back to the gap it closes.

What this is for
Citation gaps finds the prompts where a
competitor is cited and you are not. Articles
is where you decide what to do about it: not "write a blog post," but
which page should actually exist to win that prompt. On plans that draft
it grounded in evidence, that means building from the sources already
winning it today. A topic starts one of three ways: accepting a citation
gap opportunity creates a candidate topic on the Articles screen
(api/routers/citation_gaps.py#accept_citation_gap,
api/services/citation_gap.py#create_article_topic_from_opportunity), you
type your own title directly
(api/services/articles.py#submit_custom_topic), or you press Write a page
on a search plan topic, which fills in that
same form and links the article to the topic
(frontend/src/lib/search-plan.js#writePageHref). Either way, nothing is
written until you pick it: choosing a suggested topic or submitting your
own is what creates the Article row and starts generation
(api/services/articles.py#select_topic,
api/tasks.py#generate_article_task). How many articles you can start in a
week is bounded by your plan; see Pricing for what each plan
includes (api/services/limits.py#check_article_limit).
From a topic to a brief
Before anything is written, DiscoveredBy reads two sets of pages: the
pages currently cited for the prompt behind the topic, and pages of
yours: first the search plan topic's own page when the article came from
Write a page, then up to five more of your own pages picked for this article,
then the citation gap opportunity's own target page, pages already
mapped to that prompt during gap analysis (an explicit mapping, a page of
yours already cited for it, or a similarity match:
api/services/citation_gap.py#_resolve_owned_page), and, filling out the
rest, the project's own highest-scoring optimization opportunities that
have not been dismissed, whether or not they relate to this particular
topic (api/services/article_writer/corpus.py#_owned_pages). A page only
counts once it is long enough to say something
(api/services/article_writer/corpus.py#_useful_page). On a plan that
grounds drafts in evidence, if fewer than two of the cited pages count
yet and at least one of them still has no usable text, the brief itself
waits: generation defers at most twice, 180 seconds apart, before
a third and final attempt proceeds regardless of how many pages came back
(api/services/article_writer/service.py#generate_article_with_writer,
api/tasks.py#_run_generate_article,
api/tasks.py#MAX_ARTICLE_GENERATION_ATTEMPTS). A topic you typed
yourself has no prompt behind it, so it has no cited pages to wait on.
A topic from Write a page does have one: of the search plan topic's
tracked prompts, the one whose answers cited other sites most often in the
last 30 days (the window the writer reads cited pages from), or the oldest
of them when none was cited
(api/services/articles.py#_best_evidenced_prompt_id).
Your own pages are picked once per article, before the brief. The list
comes from the Sitemap lines in your robots.txt, or from /sitemap.xml when
there are none, keeping only pages on your own domain, shallowest paths
first, up to 400
(api/services/article_writer/site_pages.py#sitemap_page_urls). A model
then picks up to five that most likely say what you offer for the
question, how it works, proof such as case studies, and how a buyer
contacts you. It answers with numbers from that list, never with
addresses of its own, and anything outside the list is dropped
(api/services/article_writer/site_pages.py#choose_site_pages,
api/services/article_writer/site_pages.py#picked_site_pages). A site with
no readable sitemap, or a failed pick, leaves the writer with the pages
above. A rewrite picks again.
Your own pages have a wait of their own, on every plan: when the topic's
page or a picked page has never been scraped, generation defers on the
same schedule until it has been, so nothing about your business is
written without them. Those pages are scraped ahead of the queue of other
pages waiting to be read, and a page whose scrape failed is not waited for
(api/services/article_writer/corpus.py#_pending_own_page_ids,
api/tasks.py#_enqueue_web_pages). Your approved brand facts from
Fact check go to the writer as well
(api/services/article_writer/corpus.py#_brand_facts).
The brief itself decides the asset, not just the content: which asset to
build, from updating a page you already own to publishing something new
to holding off entirely, starting from a deterministic guess based on the
gap's own diagnosis and the prompt's shape and then confirmed or
overridden by the writer
(api/services/article_writer/asset_decision.py#deterministic_asset_recommendation,
api/services/article_writer/briefs.py#brief_prompt). Four outcomes get
drafted: a brand new article, a comparison page, a service page (shown as
"Product page"), and an update to a page you own. An update is drafted
only when the writer has that page's scraped text to rewrite: the page the
brief names when it is one of yours the writer has read, otherwise the
first of your pages listed above
(api/services/article_writer/asset_decision.py#can_draft_asset,
api/services/article_writer/asset_decision.py#update_target_page). For a
docs page, an FAQ-only addition, holding off entirely, or an update whose
page the writer could not read, the brief itself is the deliverable: why
that page and not a new one, what the cited pages have that yours does
not, and what sections or proof to add, with no markdown draft to copy.
Such an article reads "Brief only" rather than "Ready"
(frontend/src/lib/article-status.js#getArticleStatus).
You can overrule the writer's choice. The "Write your own topic" form and
Rewrite both have a "Write as" choice: the writer decides, a new article, a
comparison page, a product or service page, or an update to a page of
yours. The brief and draft then follow that choice, even when the brief
call itself fails, and on an article the choice stays selected for the next
Rewrite until you change it (api/services/articles.py#submit_custom_topic,
api/services/articles.py#regenerate_article,
api/services/article_writer/briefs.py#normalize_brief_payload).
A service page or a page update is written as copy for your own site, not
as an article. On every plan, every draft (an article too) is shown up to
six of your own pages listed above and your brand facts, and a page update
also gets the page it rewrites, read whole. A service page answers the
buyer's question in your own voice; an update keeps what the existing page
already says. The draft is meant to be published as it stands: it states a
fact about your business only when one of your pages or brand facts says
it, and it carries no bracketed placeholders, no notes to an editor and
no em dashes: one the model writes anyway becomes a comma in the page, its
meta description and its FAQ
(api/services/article_writer/drafting.py#normalize_draft_payload).
Something the brief wanted that nothing you have published supports, such
as a client result or a price, is left out of the copy and listed under
"Fill the gaps" beside the draft
(api/services/article_writer/drafting.py#draft_prompt). A bracket the
writer leaves in anyway is a blocker
(api/services/article_writer/readiness.py#citation_readiness).
When it stops and asks you first
On a plan where the draft is meant to be grounded in real source pages,
and only when the brief calls for a brand new article or a comparison
page (not a service page, and not an update to a page you own), generation can pause
instead of drafting: when the brief itself asks for proof only you can
supply, such as pricing or customer proof it has no way to invent on its
own (api/services/article_writer/briefs.py#_owned_input_requests), when
it flags that it needs your input outright, or, failing safe the same
way, when the brief call itself did not come back, rather than let a full
draft get written from a generic fallback brief with no real proof behind
it (api/services/article_writer/service.py#_should_pause_for_user_input).
When that happens the article's status reads "Needs your input," and the
page says plainly that the brief is ready but the draft needs proof only
you have. When the brief actually named what it needed, that proof is
listed under "Proof only you have" so you know what to add before you
rewrite it. The other two triggers do not guarantee anything there: the
model can flag that it needs input without naming what, and a failed
brief call falls back to a generic brief whose own request list is empty
unless the prompt is pricing, vendor, or comparison-shaped
(_owned_input_requests names five of the nine prompt intents; the rest,
including the default, get nothing). In either case no proof list appears,
and the status and the instruction to rewrite are what you have to go on. On other plans, or for any other outcome,
generation never pauses this way. A service page or a page update is left
out on purpose: a page about your business always needs facts only you
have, so pausing would mean it is never drafted. It is drafted from what
your pages and brand facts say, with the rest listed under "Fill the
gaps".
If the writing model does not return a draft, because it timed out or
failed, the article is marked Failed with the reason, and Rewrite tries
again. Nothing stands in for the missing draft
(api/services/article_writer/service.py#generate_article_with_writer).
Grounding and claim checks
A draft is written only from the brief and the pages already read for it,
with an instruction not to reuse a competitor's own phrasing or claims
(api/services/article_writer/drafting.py#draft_prompt). Every claim the
writer reports gets one of six labels, and what decides the label is
whether the writer is allowed the last word on it. Four labels stand as
the writer reported them: that a claim needs your own proof, that it
conflicts with the source, that it rests on a source that may be stale,
or that its wording is promotional. Any claim not carrying one of those
four goes through a deterministic test, and the label it comes out with
is the code's. It earns "verified by source" only when its quoted
evidence is at least four words long, appears in the actual scraped text
of the source page it names, and shares real terms with the claim it is
supposed to back, so a fabricated statement paired with a generic quote
does not pass. Your own pages the draft was shown, and your brand facts,
count as sources here too, so a claim quoting what your site or your facts
already say can be verified
(api/services/article_writer/drafting.py#own_evidence). Words are
compared without punctuation or a plural "s", so "React," in a claim
matches "React" in its quote; at least two words of four letters or more
must still be shared
(api/services/article_writer/verification.py#_terms). Failing that, it is labelled "promotional" if its wording
matches a fixed list of superlatives (best, leading, guaranteed, and the
like), and "unsupported" if not
(api/services/article_writer/verification.py#verify_claims,
_quote_supports_claim, _is_promotional_claim). So the writer cannot
certify its own work: "verified by source" and "unsupported" are the two
labels only the code ever awards, and a claim the model hands back as
verified whose quote fails the test comes out "unsupported" instead, or
"promotional" if the wording is superlative. The test only ever looks at
the claims list the writer handed back, not the rest of the draft, so a
factual statement in the prose that never made it into that list is not
checked either way. No claim is ever dropped from the draft over any of
this: what shows on the article is the label next to the claim's own
text, and any claim that does not come out "verified by source" counts
against the citation readiness score and raises one of the checks listed
at the top of "Publish it" beside the draft
(api/services/article_writer/readiness.py#citation_readiness).
Before you publish, and after
Every article that reaches "ready" status carries a publish checklist,
even a brief-only outcome with no draft to copy: a suggested slug, title
tag and meta description, which schema blocks actually validated and are
worth including, internal links to add, and indexation steps to take
once it is live (api/services/article_writer/publishing.py#publish_checklist).
The suggested slug for a new page is the draft's own suggestion when none
of your pages the writer knows of already uses it, otherwise the one from
the draft's headline, otherwise the one from the article's title; when
every one is taken, the checklist names the page that already has it, so
you choose another. For a page update the slug gives way to the page to update, which keeps
its URL, the indexation steps say so, and that page is not listed among
the pages that should link to it. A service page or a page update never
lists Article schema, which describes an article rather than a page about
your business
(api/services/article_writer/service.py#generate_article_with_writer).
An article paused at "Needs your input" has no checklist yet: generation
stops before one is ever built, and it only appears once you rewrite the
article past that point. DiscoveredBy never publishes the page for you.
You copy the draft out, or, on Starter and up, send an article straight
into a connected WordPress site as a new draft post with one click (a
service page or a page update is not a post, so it is not sent:
api/services/cms/wordpress.py#send_draft), carrying over
the article's own title and meta description plus the checklist's
suggested slug; see WordPress drafts for what
that does and does not do. Either way, the draft still has to be put live
on your own
schedule, inside WordPress or wherever else it belongs, before it links to
anything here: paste the live URL back in afterward. For an article
written from a citation gap that is still open, doing that links the
article back to that gap, moves the opportunity into monitoring right away,
and records the day 7, 14 and 30 checkpoints it will be compared against
once something checks back
(api/services/articles.py#update_article_publication,
_attach_publication_monitoring). Outcome checks exist only for citation
gaps, so nothing else is measured: an article from the
search plan's "Write a page" has a prompt
but no gap, a dismissed gap is never checked, and a topic you typed
yourself has neither. "Track it" says which case you are in before you
save the URL and after: "Saved, but nothing measures this page" for those,
the checkpoints while checks run, and that measuring has finished once the
gap has its verdict (api/services/articles.py#publication_monitoring_payload).
What you see
Two controls sit in the page header: a button that turns weekly suggestions
on or off for this project, and the day they arrive
(api/routers/articles.py#update_article_schedule). Turned on, a daily job
picks up the projects whose chosen day is today and generates that week's
topics for them
(api/tasks.py#_enqueue_weekly_topics_for_eligible_projects). Turned off,
that job skips your project entirely
(api/tasks.py#_run_generate_topics_for_project).
The day is UTC, not your local timezone. A project that has never set a day
gets one derived from its id, so not every account lands on Monday
(api/services/articles.py#scheduled_day_for_project).
Suggestions arrive at most once a week per project, even if that job runs
again in between: a project that ran within the last six days is skipped
(api/tasks.py#WEEKLY_TOPICS_MIN_INTERVAL_DAYS). Neither control gates either
of the two paths above, which are what put a topic on this screen.
Articles opens on the strongest
topic still waiting on you, ranked by the topic's own opportunity score
when one exists (api/routers/articles.py#list_article_topics; see
"What the numbers mean" below for what that score is not),
with a button to start it, or, if it already has an article, to open the
draft instead, plus two tiles counting finished drafts ready to publish (a
"Brief only" article is not one) and ones still queued or being written
(frontend/src/lib/article-view.js#readyDraftCount). Where the plan has a
weekly article allowance the screen shows how much of it this week has
used, such as "1 of 4 articles this week", and once it is used up, or the
plan has no articles, every button that starts writing is disabled with
the reason beside it, the same message the API would give
(frontend/src/lib/article-view.js#articleQuota). Rewriting an article you
already have is not counted against the week and stays available. If the topics cannot be
loaded the screen says so and offers Retry instead of reporting no
suggestions. Other topics list below it, and a form
lets you start from your own title and angle at any time. Below that,
your 50 most recent articles, each with its status ("Brief only" when
there is no draft) and a readiness score once one exists, which is also
the list the two tiles are counted from.
Each article's own page leads with the draft itself, as it will read on
your site, under its status, the kind of page it is and its address, and
one line saying how many of its claims a source backs, how many facts it
left out, and its readiness score (frontend/src/lib/article-view.js#claimCounts,
frontend/src/lib/article-view.js#pageAddress). Beside the draft (below
it on a phone) are "Publish it", with what to check first, the address,
page title, meta description and structured data to copy, the steps once
it is live and, for an article, a WordPress draft; "Fill the gaps";
"Track it", where the live URL goes; and "What it read", with your pages,
the cited pages and every claim check, the ones without a source first.
The writer's plan sits closed under the draft as "How the writer planned
it". A brief with no draft shows the brief where the draft would be.
Rewrite, with its "Write as" choice, and Copy markdown sit at the top of
the page. Rewrite asks first, because the draft, brief, claim checks,
publishing checklist and the pages it read are all replaced and the current
version is not kept; the dialog offers Copy markdown to keep it. Deleting an
article asks first too. While an article is being written its page checks
back on its own and updates when the draft is done.
What the numbers mean
Citation readiness, out of 100, starts full and loses points for a thin
source corpus, for claims left unsupported or unresolved, for FAQ schema
that failed to validate, and for a draft that reads short
(api/services/article_writer/readiness.py#citation_readiness). Read it
as a checklist score for this one draft, not a ranking against other
articles. A brief has no score: there is no draft to grade. It used to be
graded as though its missing body were a short draft, which put 65 out of
100 on a page with no words
(api/services/article_writer/service.py#generate_article_with_writer).
A topic's opportunity score is a different figure from the opportunity
score on Optimizations, which scores one of
your pages out of 100 and ranks it against your other pages: the two are
separate numbers that happen to share a name, so a figure there does not
translate into one here. This one belongs to the topic, comes from the
citation gap opportunity behind it
(api/services/citation_gap.py#create_article_topic_from_opportunity), and
is what orders the topic list above, strongest first
(api/routers/articles.py#list_article_topics).
It is now carried across on the gap's own scale of 1 to 100, unchanged,
which is what lets the badge beside the leading topic read as a real score
out of 100 (frontend/src/routes/(app)/articles/+page.svelte#topScore).
The same code used to divide that score by 100 before storing it, so every
topic created this way held a fraction below 1, and a badge rounding it to
a whole number could only ever print 0 or 1. Only topics written after that
correction carry the new scale: rescaling the rows already stored is a
separate database step, not something the code change does on its own. A
topic you typed yourself has no score at all
(api/services/articles.py#submit_custom_topic records none), and the
screen says "Suggested this week" with no badge rather than showing a zero
when the leading topic is one of those.
For how to read a change against a baseline in general, see How to read any number here.
Related
- Citation gaps: where a topic comes from, and how accepting one hands it to the writer
- Optimizations: the other route from a citation gap, for when the fix is smaller than a new page
- Metrics defined: the citation concept behind the prompt an article is written to win
- WordPress drafts: sending a finished draft into WordPress instead of copying it out by hand
- Pricing: how many articles a week your plan includes
Last verified 2026-10-14