User:Sadads/Lead Balancer

Lead Balancer (found at User:Sadads/LeadBalancer.js) is a user script that helps you find articles whose lead sections are good candidates for expanding, shortening or rebalancing, and helps you review one lead at a time across a collection of topics. It measures, flags and points to passages; it never edits, and never writes lead text for you.

The project comes after a discussion on Wikipedia:Discord about what we would need to learn to improve the Wikipedia:Lead, and what kinds of custom Suggestion mode edits might be appropriate to make lead sections more useful for readers. Based on the current manual of style recommendations, something like 18-20% of articles have an under or over developed lead -- most of which (nearly 1,000,000 articles) are shorter than 100 words recommended by the manual of style or shorter than related peer-reviewed Wikipedia articles (FAs or GAs of similar topics or WikiProjects).

For editors, the tool is to give you a second opinion on the gaps on a Wikipedia article's lead, especially for longer-articles with poorly maintained leads. Any feedback you give on the tool will help User:Sadads finetune the heuristics so that we can maybe build edit suggestions more directly into the user experience.

Getting started

How do I install it?

Add this line to your common.js, save, then reload any article:

importScript('User:Sadads/LeadBalancer.js');

A Review lead tab appears next to Article and Talk. (On skins without that tab row, look in the Tools menu.)

How do I review one article?

Open the article and click Review lead. A sidebar opens; click the tab again (or press Esc, or ×) to close it.
The This article tab shows, without any AI:
- whether the lead is too long, too short or OK for an article of this size, and what it was compared against;
- a Body vs. lead table showing how much of the body each section takes up, and how much of the lead is about it. Click a section's name to jump to it in the article (this also works in the visual editor, and in the source editor it selects the heading);
- each lead sentence, and whether it is cited;
- if the article has no infobox, an Infobox card (see below).
Optionally click Run AI review for a list of things included well and things missing, each missing point with a short quote from the article that you could emphasise.
If you decide to edit, Open lead editor opens the lead with an edit summary noting the tool's help. You can change the summary.
Before saving, click Check lead balance (next to Show changes) to see whether your draft improves the balance. See below.
If the lead is fine as it is, click Lead is fine: hide from scans. It won't come up in your scans for 90 days.
If the analysis looks wrong, use Report a problem with this analysis. See below.

What if this article doesn't need work?

When a lead looks fine, the article is excluded (for example a Good or Featured Article), or it can't be analysed, the sidebar shows Find other leads to review with one-click starting points taken from that page:

Articles linked from this page: good for broad topics and Good/Featured Articles, which link to many related articles;
its WikiProjects (B- and C-class articles);
its biggest topic categories (maintenance and tracking categories are skipped).

Clicking one opens Scan a list with that source filled in and starts the scan. You can change the options there and scan again.

How do I build a list of articles to work on?

Open the sidebar and choose the Scan a list tab.
Pick a source: a Category, a WikiProject (by assessment class, e.g. B- and C-class), articles linked from a page (e.g. a worklist), current Good Article nominees, or a pasted list of titles. Start typing and choose from the suggestions, so the names are exact.
Set Articles wanted (default 50) and click Scan. No AI is used for scanning.
The results appear as a table, and a small worklist box follows you in the bottom-left corner of every page (see below).

How are articles picked?

In short: articles are checked for eligibility, their leads are measured against Good and Featured Articles on similar topics, and only articles with a clear length or balance problem are listed, most-viewed first.

Step 1: Which pages are considered at all?

The tool reads the pages in your source (up to 5,000). Some pages are never given suggestions and are listed under excluded with the reason:

Good articles, Featured articles, A-class articles and Featured lists;
lists (list-class, or titles starting "List of", "Timeline of", "Index of", "Glossary of"), disambiguation pages and set indices;
edit-protected pages (including semi-protection);
Contentious topics and pages under an Arbitration Committee restriction;
articles currently at Featured article candidates. (Good Article nominees are included and marked GA nominee: a lead that summarises the body is part of GA criterion 1b. Choose Current Good Article nominees as the source to scan all of them.)
articles tagged {{In use}} or {{Under construction}};
optionally: articles larger than Max size (default 130,000 bytes) and articles with fewer than Min views / month (default: no minimum).

Step 2: Is the lead too long or too short?

The tool compares the length of the lead with the length of the rest of the article (prose words only; infoboxes, tables, references and "See also" are ignored; text shown from other articles by {{Excerpt}} is included).

That lead-to-body ratio is compared with the leads of 30 Good and Featured Articles on similar topics. They're taken from the same list, the same WikiProject, or, if those don't have enough, related WikiProjects.
Too long: the ratio is higher than 9 in 10 of those GA/FA leads.
Too short: the ratio is lower than 9 in 10 of them, or the lead is under about 100 words (MOS:LEADLENGTH).
A lead over 400 words gets a note (most featured articles have 250–400 words) but isn't flagged for that alone.
Articles with less than about 400 words of body text aren't listed; they appear under looked fine as too small to judge. Such articles may not need much of a lead (MOS:LEADSTUB).

The sidebar shows the comparison, e.g. "Compared with 30 GA/FA leads: typical 4.1%–17.8%, median 8.7%"; open About this comparison to see which WikiProjects they came from. If fewer than 30 comparable GA/FA exist you'll see (small sample), and (widened) if related WikiProjects were used. If fewer than 8 exist, simple default limits (3%–15% of the body) are used and labelled as such.

Typically the length ranges are somewhere between 5-18% of articles, but I am leaving the heuristic in because some article types different conventions exist (i.e. long history articles).

Step 3: Is the lead balanced?

Following MOS:LEADREL (emphasis should reflect importance), the tool checks, without AI:

Missing sections: a section with at least 10% of the body that gets less than half its share of the body in the lead, and fewer than a third of whose distinctive terms appear in the lead. A section a large part of the lead is about is never called missing. Words used all through the article (such as the subject's name) don't count as coverage, so a lead full of "Google" doesn't hide a missing Criticism section.
Over-weighted sections: a section that takes up much more of the lead than of the body. Sections that open with {{Main}}, {{Excerpt}}, {{See also}} or {{Further}} summarise another article, so they're labelled and get more leeway. Text shown by {{Excerpt}} counts as part of the body (only the part actually shown: the other article's lead, a section, or the paragraphs chosen), so a short page built mostly from excerpts is measured by what readers see.
The subject's own words (e.g. "risk" in Global catastrophic risk) and words used all through the article don't count as coverage of any one section, and a lead sentence that matches several sections is shared between them. The opening sentence defines the subject (MOS:FIRST), so it doesn't count toward over-weighting, and leads under about 100 words aren't called over-weighted (they're already flagged as too short).

This is a word-overlap heuristic, meant to point you somewhere to look, not to give a verdict.

Step 4: Who goes on the list?

An article is listed if either:

its lead is too long or too short (Step 2), or
its length is fine but its balance problem is significant: sections missing from the lead make up at least a quarter of the body, or one section takes 40% or more of the lead while being a much smaller part of the body.

Everything else is reported as looked fine, with the reason (e.g. length OK; weight issues minor, or article too small to judge). Each listed article shows Why listed.

Step 5: In what order?

The table and worklist start with the most-viewed articles (last 30 days), so your work reaches the most readers first: lead sections are the most commonly read part of an article.
The # column is the candidate score: mostly how much of the article is missing from the lead, plus quality class (B and C first, since they have substantial bodies, but haven't gone through a review process by other experienced editors) and page views.
Click any column heading to re-sort. The worklist follows the order you choose.

Does it read the whole category?

Not necessarily. To keep scans quick, big sources (such as Categories or WikiProjects over 600 pages) are shuffled and checked in a random sample sized to what you asked for (about 8 pages per article wanted). The sample grows if it doesn't turn up enough candidates. You get the highest-traffic candidates within a representative sample. Tick Thorough to check every page first. That's slower on big categories, but gives strictly the highest-traffic candidates in the whole source. Small sources are always checked in full.

Common questions

Why wasn't a particular article listed?

Look in the two collapsible lists under the results:

Excluded: it matched Step 1 (the reason is shown).
Looked fine: the length was OK and there was no significant balance problem, or the article was too small to judge.

Why did the scan find fewer articles than I asked for?

The summary says why: either the source ran out of eligible articles, or the scan hit its safety limit of 1,500 articles analysed. Try a broader category, a subcategory depth of 1–2, more assessment classes, or a lower Min views.

Why don't articles I've already handled come back?

Lead reviewer remembers, in your browser only:

leads you marked fine in the sidebar, or Done in the worklist: hidden from your scans for 90 days, even if the article is edited (Skip doesn't hide anything);
leads a scan found fine: skipped while the article is unchanged (for up to 30 days), so re-scanning a category is faster. They still appear under looked fine.

The results summary lists what was hidden. Tick Include articles I've already marked fine or done to scan them anyway, or clear the memory in Settings → Remembered leads.

Can I check my edit before saving?

Yes. In the source editor, click Check lead balance next to Show changes. The sidebar compares your unsaved draft with the saved version: length verdict, lead words and ratio, whether it would still be listed in a scan, and the body-vs-lead table, with notes such as "Criticism: no longer missing". It works whether you're editing the whole page or one section. Nothing is saved or sent, and no AI is used. It doesn't work in the visual editor.

How do I report a wrong result?

Under the weight table, open Report a problem with this analysis. Pick what's wrong for any section (e.g. should be flagged missing), tick any general problem, and add a comment. Preview report shows the exact text. Post report adds it as a new section on User talk:Sadads/LeadBalancer/Feedback, signed with your username. If you're logged out, the report isn't posted automatically (it would publish your IP address); use Copy text instead. Reports are used to test and tune the rules.

Will I get the same results if I scan again?

Largely, within the same month. The random sample and the GA/FA comparison set are fixed for the month, and refresh each month. Results can still shift a little as articles are edited and page views change from day to day.

Why does it mention infoboxes?

When an article has no infobox, the sidebar automatically asks the Infobox recommender, a separate Toolforge tool (no AI), whether one might be useful, for example because most similar articles have one. It shows the recommender's verdict (may benefit from one, probably not needed or no clear signal), its confidence, a suggested template only when similar articles clearly share one, and its evidence (how many similar articles have an infobox, and which), with a link to the full report. This is advice only: whether an article has an infobox is decided case by case on each article (MOS:INFOBOXUSE), so check the talk page for any past discussion before adding one. Articles that already have an infobox aren't checked, and the infobox check never affects which articles are listed in a scan. The recommender keeps aggregate usage statistics and logs the title of each article it analyses for 90 days; it does not store IP addresses, user agents or cookies (its privacy note).

My WikiProject isn't found, or shows no classes

Choose the project from the suggestions (spelling and US/UK variants are handled, e.g. "Labor" finds Organized Labour). Projects without assessment categories still work: their articles are read straight from WikiProject assessments, just without counts.

The worklist

After a scan, a small box in the bottom-left corner follows you on every Wikipedia page and tab:

Prev / Next move through the list; Done › and Skip › mark the article and open the next unfinished one. Done also keeps the article out of your scans for 90 days.
An article is marked reviewed when you open its sidebar and edited when you save an edit to it.
It's stored only in your browser, and clears after 12 hours idle or when you click Clear list. A new scan replaces it.

The AI review

What does it do?

It reads summaries of the article's sections and the current lead, then lists things included well and things missing. Each missing point comes with a 2–3 sentence passage from the article that you could emphasise. It may also flag lead sentences that could be tightened, that may belong in the body, or that may be over-emphasised.

What will it never do?

It never suggests removing cited material. At most it notes possible over-emphasis, or suggests tightening while keeping the citation.
It never suggests reverting or undoing other editors' work.
It never writes lead text. Quotes are copied from the article and checked against it, and anything that can't be matched is dropped.

These rules are enforced in the tool's code, not just requested of the AI. The AI can still be wrong, so please check every point against the article and its sources.

Which AI, and what does it cost?

By default it uses Wikimedia's own Lift Wing service, free and without a key. In Settings you can instead use your own Claude, OpenAI or Gemini key, which is stored only in your browser. Results are cached in your browser, so re-checking after you edit only the lead costs a single request.

So far, in testing, the Lift Wing LLM tool does a good job in evaluating gaps in the lead sections of articles.

Do I need to disclose AI use?

The Open lead editor button pre-fills an edit summary saying the suggestions were LLM-assisted. Please keep a note like that in your summary, and follow any applicable guidance on using large language models.

Troubleshooting

The tab doesn't appear: check that the importScript line is saved, then hard-refresh (Ctrl+Shift+R, or Cmd+Shift+R on a Mac).
"Version mismatch" warning: the two script pages are from different releases. The version is shown in the sidebar header; see the changelog.
Something looks wrong: please report it on the talk page with the article name and the version number.

Versions

The current version is shown in the sidebar header and in Settings. Each release notes what changed and which script page(s) were updated.