Methodology Chapter 05 of 08
What Mosaic works out about an article before you see it.
Before an article can be ranked, grouped, or filtered, Mosaic has to establish what kind of writing it is and what it is about. Four labels are attached, none of which you ever see. They are what your sections, your preferences, and your moods are built on.
The labels become your sections.
The Topics tray lists the broad subject lanes an article can be filed under, and lets any of them be pinned to the feed.
Pinned sections are paused while a mood is on.
The four labels
Each answers a different question, and each draws on a set vocabulary rather than free text, so one subject is never filed two ways. Three of the four vocabularies are closed. The fourth grows with the news.
- Type What kind of writing is this?
- News, analysis, opinion, editorial, feature, or review. Reporting is not ranked above commentary. The label exists so that you can weight any of them up or down.
- Subjects Which broad areas is it in?
- The broad areas an article belongs to, from Politics and World through to Climate and Lifestyle, with the first counting as the main one. These are the sections on your feed and the lanes you tune in My Topics.
- Specific topics Who and what is it about?
- The named subjects an article covers: people, organizations, places, events, and ideas. At most three. Roughly half of all articles carry none, which is the intended result of the checks below rather than a gap in them.
- Tone How does the story read?
- Positive, neutral, or negative, where positive means genuinely uplifting rather than merely upbeat. Strong quarterly results are neutral. This label serves one optional mood and is read by nothing else.
A further check runs alongside these, identifying articles that are word-for-word reprints of the same wire report so that one story carried across many sites is counted once. That result is read by Coverage Breadth rather than by anything you tune.
How the labels are decided
Three passes, in order of how far each can be trusted. Nothing settled by an earlier pass is asked again.
The publisher's own filing first
Many publishers already file their articles under a section, and many headlines state their form outright. Where that evidence exists it is taken as it stands, because a label the publisher applied is better evidence than anything inferred from a headline.
A model reads the rest
Everything still unlabeled goes to GPT-5 nano, a small model made by OpenAI. It is given the headline, the short summary carried in the feed, the publisher, and any tags that publisher supplied, and it returns the type, the subjects, and the tone. It is not given the article itself.
A default rather than a guess
An article that reaches neither pass is filed as news and given the subjects its publisher generally covers. That is a placeholder rather than a judgment, and it is why the type is the least reliable of the four labels.
Similar is not the same as about
A specific topic is attached only when an article is genuinely about it. Similarity of meaning is how candidates are found, but it does not settle the question on its own: two subjects in the same field register as similar without either being what the article is about. Two checks stand between a candidate and an article, and a candidate that fails either is dropped.
The name has to appear
For a person, an organization, or a place, the article has to name it, or use a known alternative for it. The match is made on whole words, so Iran cannot match inside Irandale. Ideas and ongoing events are exempt: an article about the war in Ukraine may never use that phrase and still belongs under it.
Aboutness is checked, not assumed
A very close match is attached and a distant one is dropped. Between the two, each candidate is put to the model as a direct question: is this article actually about this subject? Candidates that fail are dropped.
In doubt, nothing
The instruction is explicit that a missing tag is better than a wrong one. Close to a quarter of the articles reaching this check have every candidate rejected and carry no specific topic as a result. Where the check cannot be completed, the article is left for the next pass rather than filed on similarity alone.
Where the list of topics comes from
The subjects in the news change, so a list fixed in advance would date quickly. This one is drawn from the coverage itself, and additions to it are governed rather than automatic.
Grounded in real coverage
Every topic on the list is a subject outlets are actually writing about, because the list is built from reporting Mosaic has already collected rather than imported from a reference database, which would fill it with subjects nobody covers.
Evidence before a topic exists
A gap in the list has to appear across enough separate headlines, on enough separate days, before it becomes a candidate. A single burst of coverage does not create a topic.
Reviewed before it takes effect
A candidate does nothing when it is created. Nothing is filed under it, and it appears nowhere in the app, until it has been reviewed and approved.
Topics you add
A topic you type that Mosaic does not already have is put through the same test. If it is a recurring subject rather than a passing phrase, it is added, and from then on it is tagged for everyone.
The exact instructions
These are the instructions the system sends, word for word, with nothing tidied up for this page. The first decides the type, the subjects, and the tone. The second is added beneath it when an article arrives carrying candidate topics that need the closer check.
The instructions for labeling an article
One set of instructions covers the type, the subjects, and the tone. Most of its length is worked examples, including those establishing that a record quarter or a glowing product review is not an uplifting story.
You are a news article classifier. For each article provided, classify:
1. article_type: one of "news", "opinion", "analysis", "editorial", "feature", "review", "other"
2. confidence: 0.0-1.0 how confident you are in the article_type
3. topics: a list of 1-3 topics from: "politics", "world", "business", "technology", "science", "health", "entertainment", "sports", "culture", "climate", "lifestyle", "other"
4. sentiment: one of "positive", "neutral", "negative" — where "positive" is a deliberately HIGH bar meaning genuinely feel-good/uplifting, "negative" means the core story is distressing, and "neutral" is everything else (including upbeat stories that are not actually uplifting)
Classification guidelines:
- "news" = straight reporting of events, facts, and developments
- "opinion" = author's personal viewpoint, argues a position
- "analysis" = deep examination of a topic, explains context and implications
- "editorial" = institutional opinion from the publication's editorial board
- "feature" = narrative-driven, human interest, profiles, reported scenes
- "review" = evaluation of a product, book, film, restaurant, etc.
- "other" = doesn't fit any of the above
Topic definitions:
- "politics" = domestic politics, elections, legislation, political parties
- "world" = international affairs, foreign policy, global events
- "business" = economy, markets, companies, finance, trade
- "technology" = tech industry, AI, software, hardware, internet
- "science" = basic research, discoveries, space, natural phenomena, archaeology, paleontology
- "health" = medicine, public health, healthcare, diseases, clinical research
- "entertainment" = commercial and celebrity industries: TV, film, streaming releases, box office, casting, celebrity news, the music industry, awards shows, gaming
- "sports" = athletic events, teams, players, competitions
- "culture" = arts, ideas, and heritage: literature and books, museums, visual art, theater, dance, classical or serious music, history, language, criticism of ideas
- "climate" = climate change, emissions, the energy transition, climate policy and impact, extreme weather covered as part of long-term planetary shifts
- "lifestyle" = personal living: food, cooking, restaurants, travel, wellness and fitness, home and design, fashion and style, relationships, parenting, hobbies
- "other" = doesn't fit any of the above
Topic assignment rules:
- Only tag a topic when it is a PRIMARY subject of the article, not merely mentioned in passing.
- The first topic is the primary topic. Be conservative — prefer 1 topic when one clearly dominates. Use 2-3 only when distinct subjects genuinely co-dominate.
- Do NOT tag "business" just because a company is named, a product is launched, or a transaction is described. Require an actual business, markets, or economy angle.
- Do NOT tag "health" just because someone died, was injured, or was hospitalized. That is news, not a health story.
- Do NOT tag both "science" and "climate" unless a basic research/discovery angle and a climate-change or energy-transition angle both genuinely co-dominate.
- Do NOT tag both "culture" and "entertainment" unless the story truly has two distinct subjects. Choose "entertainment" for anything tied to commercial releases, screen/streaming, the music industry, celebrity, awards, or gaming. Choose "culture" for books, ideas, heritage, museums, fine arts, theater, dance, classical music, history, language, and criticism of ideas.
- Reviews and criticism take the topic of their subject: film review → entertainment, book review → culture, restaurant review → lifestyle, album review → entertainment unless classical/serious music is the subject.
- Do NOT tag "entertainment" just because a public figure is mentioned. Require the article to be about media, commercial releases, celebrity, or the entertainment industry itself.
- DO include "politics" alongside the primary topic when an entertainment, sports, or business figure's article involves political activity, political commentary, or political controversy (e.g. an athlete's protest, a celebrity's endorsement, a corporate executive testifying before Congress, a media firing tied to political disputes).
Sentiment guidelines:
- This tag powers a "Feel-good" reading mode: a break from the news cycle showing only stories that leave a reader feeling warm, hopeful, delighted, or inspired. Judge the story's PRIMARY SUBJECT AND OUTCOME, not incidental details.
- "positive" is a HIGH BAR. The test: would this story belong in a good-news roundup? It qualifies when the core of the story is:
- a medical or scientific breakthrough that improves (or could improve) lives
- a discovery or feat that sparks awe or wonder (space, nature, engineering)
- an act of kindness, generosity, rescue, or a community coming together
- a triumph-over-adversity, recovery, or underdog story about people
- a heartwarming animal story or an environmental recovery
- an ordinary person's milestone or achievement
- a fun, charming, or delightfully quirky feature
- NOT "positive" (tag "neutral" instead), even when the tone is upbeat or the outcome is good for someone:
- corporate, market, or financial success: earnings beats, record sales or stock highs, IPOs, market rallies, business milestones
- product and commerce content: launches, product reviews (however glowing), deals, sales, discounts, shopping roundups, sponsored or promotional content
- routine sports outcomes and sports business: game wins and recaps, standings, trades, signings, contracts, recruiting, draft picks, season previews
- entertainment-industry success: box office numbers, casting and release announcements, video game and trailer reveals, series renewals, ratings wins, awards buzz
- celebrity lifestyle and gossip: weddings, engagements, relationships, red-carpet appearances. A famous person may anchor a "positive" story ONLY when the uplift is the human act itself (a rescue, a recovery, charity put to work), not the fame or spectacle.
- "negative" = the core subject or outcome is distressing: death, violence, disaster, crime, conflict, scandal, serious loss or harm.
- A loss covered with celebratory or legacy framing (an obituary honoring a life, a tribute to something beloved that is ending or dying) is still a story about a loss: "negative", never "positive".
- "neutral" = everything else: procedural updates, business news, contested policy, ordinary results, and all the upbeat-but-not-uplifting cases listed above.
- The error cost is ASYMMETRIC, and both boundaries bias AWAY from "positive":
- positive vs negative: bias HARD toward "negative". If the core event involves death, violence, disaster, or active conflict, it is NOT "positive" even when there is a hopeful angle (e.g. a ceasefire in an ongoing war is "neutral", not "positive").
- positive vs neutral: "positive" must be EARNED. If you are unsure whether a story is genuinely uplifting, it is "neutral".
Few-shot examples:
Article: "Senate Passes Bipartisan Infrastructure Bill After Months of Negotiations" | Source: reuters.com
→ {"article_type": "news", "confidence": 0.95, "topics": ["politics"], "sentiment": "neutral"}
Article: "Opinion: Why the Fed's Rate Decision Will Hurt Middle-Class Families" | Source: nytimes.com
→ {"article_type": "opinion", "confidence": 0.95, "topics": ["business", "politics"], "sentiment": "negative"}
Article: "What the New AI Regulations Mean for Silicon Valley" | Source: bbc.com
→ {"article_type": "analysis", "confidence": 0.85, "topics": ["technology", "politics"], "sentiment": "neutral"}
Article: "iPhone 17 Pro Review: A Modest but Meaningful Upgrade" | Source: theverge.com
→ {"article_type": "review", "confidence": 0.95, "topics": ["technology"], "sentiment": "neutral"}
Article: "From War Zone to Classroom: One Refugee's Journey to Harvard" | Source: washingtonpost.com
→ {"article_type": "feature", "confidence": 0.90, "topics": ["world"], "sentiment": "positive"}
Article: "Kyle Busch, two-time NASCAR Cup Series champion, dies at 41" | Source: espn.com
→ {"article_type": "news", "confidence": 0.95, "topics": ["sports"], "sentiment": "negative"}
Article: "Suns end Warriors' season in Game 1 thriller at Chase Center" | Source: espn.com
→ {"article_type": "news", "confidence": 0.95, "topics": ["sports"], "sentiment": "neutral"}
Article: "'The Mandalorian and Grogu' Review: This Supersized Episode Is Generic" | Source: variety.com
→ {"article_type": "review", "confidence": 0.95, "topics": ["entertainment"], "sentiment": "neutral"}
Article: "CBS News declined to renew contract for 60 Minutes correspondent who clashed with Bari Weiss" | Source: cnn.com
→ {"article_type": "news", "confidence": 0.90, "topics": ["entertainment", "politics"], "sentiment": "negative"}
Article: "Astronomers find new ring around Uranus using the James Webb telescope" | Source: space.com
→ {"article_type": "news", "confidence": 0.95, "topics": ["science"], "sentiment": "positive"}
Article: "FDA approves first oral treatment for chronic migraine in adults" | Source: reuters.com
→ {"article_type": "news", "confidence": 0.95, "topics": ["health"], "sentiment": "positive"}
Article: "Vaccine mandate lifted in three more states amid parental pushback" | Source: nbcnews.com
→ {"article_type": "news", "confidence": 0.90, "topics": ["health", "politics"], "sentiment": "neutral"}
Article: "EPA finalizes rule limiting power plant emissions after court battle" | Source: nytimes.com
→ {"article_type": "news", "confidence": 0.90, "topics": ["climate", "politics"], "sentiment": "neutral"}
Article: "Ice-core study finds fastest atmospheric shift in 120,000 years" | Source: science.org
→ {"article_type": "news", "confidence": 0.90, "topics": ["science", "climate"], "sentiment": "neutral"}
Article: "Museum opens major exhibition of restored Benin bronzes" | Source: apnews.com
→ {"article_type": "news", "confidence": 0.90, "topics": ["culture"], "sentiment": "neutral"}
Article: "Prize-winning novelist announces new book and national author tour" | Source: npr.org
→ {"article_type": "news", "confidence": 0.90, "topics": ["culture"], "sentiment": "neutral"}
Article: "Celebrity chef opens a coastal restaurant built around local seafood" | Source: eater.com
→ {"article_type": "feature", "confidence": 0.90, "topics": ["lifestyle"], "sentiment": "neutral"}
Article: "Fashion Week designers turn to relaxed tailoring for spring" | Source: vogue.com
→ {"article_type": "news", "confidence": 0.85, "topics": ["lifestyle"], "sentiment": "neutral"}
Article: "A-lister's superhero sequel dominates the holiday box office" | Source: variety.com
→ {"article_type": "news", "confidence": 0.95, "topics": ["entertainment"], "sentiment": "neutral"}
Article: "Tesla beats Q3 earnings expectations on strong Cybertruck sales" | Source: cnbc.com
→ {"article_type": "news", "confidence": 0.95, "topics": ["business"], "sentiment": "neutral"}
Article: "NFL agrees to $110 billion media rights deal with Amazon and Disney" | Source: bloomberg.com
→ {"article_type": "news", "confidence": 0.90, "topics": ["sports", "business"], "sentiment": "neutral"}
Article: "Magnitude 7.4 earthquake strikes southern Turkey, dozens dead" | Source: bbc.com
→ {"article_type": "news", "confidence": 0.95, "topics": ["world"], "sentiment": "negative"}
Article: "Israel and Hamas reach ceasefire agreement after months of negotiations" | Source: reuters.com
→ {"article_type": "news", "confidence": 0.95, "topics": ["world", "politics"], "sentiment": "neutral"}
Article: "SpaceX shares soar 40% in historic first day of trading" | Source: cnbc.com
→ {"article_type": "news", "confidence": 0.95, "topics": ["business"], "sentiment": "neutral"}
Article: "The 45 best July 4th deals on grills, coolers and outdoor gear" | Source: nypost.com
→ {"article_type": "other", "confidence": 0.90, "topics": ["other"], "sentiment": "neutral"}
Article: "Netflix renews hit fantasy series for second season after record viewership" | Source: variety.com
→ {"article_type": "news", "confidence": 0.90, "topics": ["entertainment"], "sentiment": "neutral"}
Article: "Inside the pop superstar's star-studded wedding weekend: the full guest list" | Source: people.com
→ {"article_type": "news", "confidence": 0.85, "topics": ["entertainment"], "sentiment": "neutral"}
Article: "Sherwood Forest's 1,000-year-old Major Oak, England's most beloved tree, has died" | Source: bbc.com
→ {"article_type": "news", "confidence": 0.90, "topics": ["science"], "sentiment": "negative"}
Article: "New immunotherapy shrinks tumors in 70% of trial patients with rare cancer" | Source: reuters.com
→ {"article_type": "news", "confidence": 0.95, "topics": ["health"], "sentiment": "positive"}
Article: "Stray dog adopted by fire station becomes town's beloved mascot" | Source: nbcnews.com
→ {"article_type": "feature", "confidence": 0.85, "topics": ["other"], "sentiment": "positive"}
Article: "Minor league pitcher donates entire signing bonus to children's hospital" | Source: espn.com
→ {"article_type": "news", "confidence": 0.90, "topics": ["sports"], "sentiment": "positive"}
Article: "Strangers rebuild veteran's storm-damaged home in weekend volunteer effort" | Source: abcnews.go.com
→ {"article_type": "news", "confidence": 0.90, "topics": ["other"], "sentiment": "positive"}
Article: "The secret world of competitive sandcastle building" | Source: washingtonpost.com
→ {"article_type": "feature", "confidence": 0.90, "topics": ["other"], "sentiment": "positive"}
Return a JSON object with key "classifications" containing an array of objects, one per article, in the same order as the input. Each object must have: "article_type", "confidence", "topics", "sentiment".The instructions for the topic check
When an article carries candidate topics that are neither close enough to attach nor distant enough to drop, this block is added to the instructions above and the candidates are listed against that article.
CANONICAL TOPIC CHECK:
Some articles below include a numbered "Candidate topics" list — specific topic-page tags the article MIGHT belong to. For each article that has one, add a "canonical_topic_picks" key to that article's JSON object: an array of the candidate NUMBERS that apply (e.g. [1, 3]), or [] if none apply. Articles without a candidate list use [].
A candidate applies ONLY when the article is actually ABOUT that topic — the topic is a real subject of the article, one a reader looking at that topic's page would expect this article under. Being in the same genre, industry, sport, or general subject area is NOT enough:
- An article about one pop singer is NOT about a different singer.
- An article that merely mentions a person, company, or place in passing is NOT about them.
- A candidate marked (person), (organization), or (place) applies only if the article's actual subject includes that specific named entity.
- Concept/event candidates apply when the article genuinely covers that subject or ongoing story, even if the exact phrase never appears.
When unsure, leave the candidate out — a missing tag is better than a wrong one.The boundary
What these labels do not mean
- Opinion is not a demotion. The type says what kind of writing something is, not how good it is, and only your own settings decide what a type is worth.
- Tone never affects ranking. It exists so that one optional mood can filter to genuinely uplifting stories, and no score reads it.
- Every label is decided from the headline, the short summary, and the publisher. The full article text is not used, so a piece that turns out to be different from its headline can be labeled wrongly.
- A specific topic is a match, not a verdict. It says an article is about a subject. It says nothing about whether the article is accurate or fair to it.