# IDEA.md – a news list of your own where every heavy story is weighed against a light one This is a self-contained brief. Give it in full to Claude Code (or a similar tool) to build an implementation of your own. It draws on Good News Morning, a Swedish news list that was designed in Claude Design, built with Claude Code and given its icon by Codex. ## 1. What to build A morning edition with two columns, the heavy and the light, where every heavy story stands next to a light one. The content is only what the news sites publish in their own RSS feeds: headline, lead, date, link and picture. The article text is never fetched. In Good News Morning: - **one morning edition per day**, built twice a day, with a permanent address per morning and an archive - **pairs on five levels**: the same event, the same subject, the same place or group, a related subject and today's bright spot, with the level shown on the centre line - **trend cards**: a long-term figure with its source as the counterweight when there's no fresh light article in the same subject - **eight subjects** with a filter, and "the morning's scale": how heavy the feed was against the balance here - **"How we weigh the news"**, an open explanation of the levels - light and dark theme, a home-screen app, RSS and a sitemap - **no JavaScript required**, and nothing loaded from other hosts ## 2. Stack and architecture What **matters** is marked; the rest can be swapped. - **PHP 8.3 with no framework, MariaDB and Apache.** Server-rendered pages, cached whole until the next build. - **Important: a three-step pipeline**, each step a CLI tool run by cron: fetch (conditional GET against every feed), classify (only unclassified articles) and build (pair today's edition and clear the cache). A lock file keeps two runs from overlapping. - **Important: classification with Claude, pairing in PHP.** Claude classifies each article once with a structured answer against a schema, several articles per call. The matcher is deterministic and testable. - **One shared vocabulary** in one file: the subjects, which are related, which are light, and the levels with their names. The classifier, the matcher and the views all read the same file. - **A fallback classifier** without an API key, so everything runs locally. - **The source register in the database**: name, feed, whether the source only publishes light news, and a subject hint. ## 3. Decisions that turned out to matter **AI where it makes a difference, code where it has to be explainable.** A text algorithm (TF-IDF and cosine similarity) finds articles about the same thing but can't tell the tone – "cancer cases rise" and "cancer deaths fall" sit in almost the same place. Let the language model classify tone (−2…+2), subject, a narrower label, places, groups and a normalised event label. Send the last few days' event labels along, so the same event gets the same label across runs. **Be honest about the fallback.** If there's no close counterweight, show today's bright spot and say so plainly. Light stories may be up to 30 days old and are used once per edition. **A pair belongs to the subjects of both sides.** Otherwise a subject with almost only light news (science) never gets a pair. **The law shapes the form.** Always link to the original and credit the source visibly. Shorten the lead to whole sentences under 240 characters. The pictures are the biggest risk: build the modes own thumbnail, the source's image or no image, and put the site behind a gate if the pictures may not be shown publicly. **A gate without accounts.** Without a key cookie every page answers 401 with just the logo. An address of its own shows a button; the click (a POST form, not a link) sets the cookie, so a link preview lets nobody in. `robots.txt` says `Disallow: /`. ## 4. Pitfalls - **Greedy assignment leaves stories without a counterweight.** Add a repair step where a heavy story with a free trend card gives up its article. - **The same story in several feeds often shares only a proper name.** Form groups on proper names in the headline too, within the same subject. - **Word stems** must match at the start of a word and be chosen with care: in Swedish, "kris" hits "Kristersson", "fred" "fredag", "hot" "hotell", "val" "valet". - **Feeds differ**: RSS 2.0 and Atom, the picture in `enclosure`, `media:content` or as an `` in the description – or not at all (then fetch the page's `og:image`). A feed may be gzipped. Tracking parameters in links create duplicates. - **Aggregators republish others' articles** under their own addresses. Catch duplicates on the headline. - **The home-screen app on iOS** doesn't share cookies with Safari, and iOS keeps old icons. Link icons and the manifest with the file's time in the address. - **iOS 26 puts a blur** over the top edge of a home-screen app; a fixed, opaque layer over the whole screen removes it. - **The cost of classification**: measure the number of new articles per day and do the sums before choosing a model. Only classify what isn't a duplicate. ## 5. Requirements and measurements - Every page works without JavaScript. - No resources from other hosts. - One cookie and only one: the gate's key. The theme is stored in the browser. - The lead at most 240 characters, in whole sentences. ## 6. How it's verified - `php -l` on every file. - Unit tests with no network and no database writes: feed parsing, classification and matching against fixtures. - A smoke test as a visitor: status codes, the cache, the base path, that nothing loads from other hosts. - The look in a real browser against the design, on desktop and mobile. ## 7. Way of working - **Research first**: which feeds exist and work, the law, and whether the matching should be AI or a text algorithm. Write the reasoning down. - **Design first** in a design tool, with several options to choose from. - **An issue board**, with decisions as issues of their own. ## 8. The prompt > Build a news list in [Swedish] where every heavy story stands next to a light one: fetch headline, lead, date, link and picture from [the news sites' RSS feeds], let [Claude] classify tone and subject, and pair the stories on levels with a deterministic matcher. [PHP with no framework and MariaDB], cached pages, no JavaScript. > > Read all of IDEA.md below first. > > Work like this: > 1. Research the sources and the law, and write the reasoning down. > 2. Split the build into issues and ask me about the decisions. > 3. Test the feed parsing, the classification and the matching against fixtures. > > [paste IDEA.md here]