article

> **${var}** — Selector: `[angle:arg] [--visual]`. The **angle** prefix picks the article type; append **`--visual`** (or `visual`) anywhere to also generate a Replicate hero image. > > - **empty** → `standard` general long-form article on an auto-selected trending topic. If the resolved topic is a single explainable mechanism, it becomes a technical explainer instead. > - **`<topic>`** (no recognized prefix) → `standard` article on that topic. > - **`repo:<owner/repo>`** → `repo` thesis-driven article about that repo. `repo:<angle>` (e.g. `repo:architecture`) or bare `repo:` uses the repo from `memory/watched-repos.md` with that angle / an auto-selected angle — this preserves repo-article's original input. > - **`lens:<topic>`** → `lens` project-through-a-lens essay framed by that lens (e.g. `lens:unix philosophy`). Bare `lens:` auto-selects the lens. > - **`--visual`** appended to any of the above → after the body is written, generate a Replicate hero image (optional `REPLICATE_API_TOKEN`; ships text-only if absent). > > Examples: `""`, `"entropy trajectory reasoning --visual"`, `"repo:aeonfun/aeon"`, `"repo:roadmap"`, `"lens:regulation wave --visual"`. Today is ${today}. Write a high-quality, publication-ready article. No placeholders. ## Shared preamble (every run) 1. Read `memory/MEMORY.md` for context on what topics/articles have been covered recently. 2. Read the last 3–7 days of `memory/logs/` for recent activity — and **don't re-report** something already covered. 3. **Parse `${var}` into `angle` + `visual`:** - Detect a standalone `--visual` or `visual` token anywhere in `${var}`; if present set **`visual = true`** and strip that token. Otherwise `visual = false`. - From what remains: if it starts with `repo:` → `angle = repo`, `arg =` the rest. If it starts with `lens:` → `angle = lens`, `arg =` the rest. Otherwise → `angle = standard`, `arg =` the whole remaining string (empty ⇒ auto-select). 4. Dispatch to the matching angle section below. If `visual = true`, run the **Visual add-on** after the article body is written, regardless of angle. --- ## Angle: standard — long-form article / technical explainer A single long-form article. It takes one of two structures depending on the topic: - **General article** — a broad trend, development, or event. 600–800 words. - **Technical explainer** — a single explainable mechanism, technique, algorithm, or system. 600–1000 words, using the explainer structure below. ### Topic selection (standard) - If `arg` (the topic) is set, use it verbatim. If it clearly names a single mechanism/technique/system → **technical explainer** structure; otherwise → **general article** structure. - If `arg` is empty, pick deterministically — first hit wins: 1. **Explainer candidate:** a single most non-obvious mechanism inside the newest file in `output/articles/` from the last 3 days; else the newest "Paper Pick" in `memory/logs/` from the last 7 days (its headline mechanism); else a specific technique/algorithm/system surfaced in the last 7 days of logs. If a strong single-mechanism candidate exists → **technical explainer** on it. Reject any candidate broader than a single mechanism (e.g. "AI agents" — too vague; "MCP tool-routing via vector search" — usable). 2. **General candidate:** otherwise search the web for the most interesting recent development in AI, crypto/DeFi, or consciousness research — pick whichever has the most compelling story today (WebSearch) → **general article**. ### Voice (technical explainer) If a `soul/` directory exists, read the soul files for voice calibration: `soul/SOUL.md` (identity, worldview, opinions), then `soul/STYLE.md` (writing style, sentence structure, anti-patterns). This is *you explaining a mechanism to a smart friend* — more precision than a general article, same voice. No textbook tone, no "let's explore." If `soul/` is empty, default to clear, direct, neutral. ### Research **General article:** read 2–3 source articles with WebFetch to gather facts and quotes. **Technical explainer:** run **three distinct WebSearch queries** so you triangulate rather than echo one source: 1. `"<topic>" how it works` — mechanism explanations 2. `"<topic>" benchmark OR results OR latency OR cost` — concrete numbers 3. `"<topic>" limits OR criticism OR fails OR doesn't work` — failure modes and pushback If the topic is from a paper, also fetch the paper metadata and abstract: ```bash curl -s "https://api.semanticscholar.org/graph/v1/paper/search?query=TOPIC&limit=5&fields=title,authors,abstract,url,publicationDate,openAccessPdf" \ || echo "curl failed — use WebFetch on https://www.semanticscholar.org/search?q=TOPIC instead" ``` Use **WebFetch** to read the 2–3 best sources in depth. **At least one source must be primary**: a paper (arXiv / OpenReview / Semantic Scholar), official documentation, the project's own README, or a code repo. Blog summaries alone are not enough — they often mangle the mechanism. Extract: - The **single core mechanism** — the one move that, once you grok it, makes the rest fall into place. - A **vivid analogy** for the mechanism, and the precise place where the analogy breaks down (the breakage is the interesting part). - **3–5 specific numbers** — benchmarks, latencies, costs, error rates, training compute, parameter counts. Each number gets a source URL. - **What would falsify this** — what result, if observed, would mean the mechanism doesn't work as claimed. If you can't name one, the explanation isn't sharp enough — keep digging. ### Write **General article** — 600–800 words in Markdown. Include: - A compelling title - A short intro hook - 3–4 substantive sections - Cited sources (with URLs) at the bottom **Technical explainer** — 600–1000 words. Structure (every section required): ``` # <Title> **Key idea in one sentence:** <one-sentence claim about the mechanism> ## The Setup 2-3 sentences. What problem does this solve? Why now? ## The Intuition Pump A vivid analogy that builds the reader's mental model in 3-4 sentences. Then one sentence on **where the analogy breaks down** — that's where the real mechanism lives. ## How It Actually Works A numbered walkthrough of the mechanism in **3-7 steps**. Each step is one or two sentences. Use concrete examples — name the specific function, layer, message, opcode, contract. No "the system processes the input" — say what the system actually does. ## Numbers That Anchor It 3-5 bullet points. Each bullet is a specific number with a source link, e.g.: - 8.4× faster end-to-end than baseline at 4K context ([source](url)) ## What Would Break This 1-2 sentences naming a result that, if observed, would falsify the claim. This forces honesty. ## Why It Matters 2-3 sentences. What does this unlock? Who should care? ## Sources - [Title 1](url) — primary - [Title 2](url) - [Title 3](url) ``` **Voice rules (technical explainer):** First person where it fits. Explanatory > opinionated, but not bloodless. Technical precision > hedging — if you don't know, say so, don't fudge. Short paragraphs. Em dashes. Concrete > abstract. Reference specific systems, papers, people — no "researchers have shown," name them. Cite inline: every number, every claim that could be wrong, gets a link. ### Save & notify (standard) - **General article:** save to `output/articles/${today}.md`. - **Technical explainer:** save to `output/articles/explainer-${today}.md`. If a hero image was generated (see Visual add-on), put it at the very top: `` — relative path, skip the line if no image — and add an HTML comment with the image prompt used (for future audits). Update `memory/MEMORY.md` to record the article and its topic (add to the `Recent Articles` list/table). Append the consolidated log entry (see **Log**), then notify via `./notify`: - **General article:** ``` New article written: [title] https://github.com/${GITHUB_REPOSITORY}/blob/main/output/articles/${today}.md ``` Use the `$GITHUB_REPOSITORY` env var (GitHub Actions sets it to `owner/repo` of the running instance). - **Technical explainer:** ``` technical explainer: [title] [the one-sentence "key idea" line, verbatim] [hero image URL if generated — original Replicate URL still works for ~24h] read it: output/articles/explainer-${today}.md ``` --- ## Angle: repo — thesis-driven article about a watched repo <!-- autoresearch: variation B — editorial discipline: research → thesis → draft → self-edit, with a falsifiable claim and a quality gate --> ### Config Reads repos from `memory/watched-repos.md`. Resolve the target repo: - If `arg` looks like `owner/repo` (contains a `/`) → that's the repo to cover; the angle is auto-selected in Phase 2. - Else if `arg` is a non-empty keyword (e.g. `architecture`, `recent progress`, `roadmap`) → it's the **angle**; pick the repo from `memory/watched-repos.md` (if multiple are listed, the one with the most activity in the last 7 days). - Else (`arg` empty) → repo from `memory/watched-repos.md` (most active of the last 7 days), angle auto-selected. An article without a thesis is filler. This angle runs five phases and only advances when the current phase's gate passes. ### Phase 1 — Research (gather, don't write yet) Run these in parallel where possible (substitute the resolved `owner/repo`): ```bash # Repo metadata gh api repos/owner/repo --jq '{name, description, language, stargazers_count, forks_count, open_issues_count, topics, created_at, updated_at, pushed_at, default_branch}' # Commits in last 7 days (paginated) gh api repos/owner/repo/commits -X GET \ -f since="$(date -u -d '7 days ago' +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || date -u -v-7d +%Y-%m-%dT%H:%M:%SZ)" \ --jq '.[] | {sha: .sha[0:7], msg: .commit.message | split("\n")[0], author: .commit.author.name, date: .commit.author.date, url: .html_url}' --paginate # Merged PRs in last 7 days gh api 'repos/owner/repo/pulls?state=closed&sort=updated&direction=desc&per_page=50' \ --jq '[.[] | select(.merged_at and (.merged_at > (now - 86400*7 | todate))) | {number, title, user: .user.login, merged_at, additions, deletions, url: .html_url}]' # Open PRs gh api repos/owner/repo/pulls --jq '[.[] | {number, title, user: .user.login, created_at, draft, labels: [.labels[].name], url: .html_url}]' # Issues opened/closed in last 7 days (exclude PRs) gh api 'repos/owner/repo/issues?state=all&since='$(date -u -d '7 days ago' +%Y-%m-%dT%H:%M:%SZ)'&per_page=100' --paginate \ --jq '[.[] | select(.pull_request | not) | {number, title, state, created_at, closed_at, labels: [.labels[].name]}]' # Last 3 releases gh api repos/owner/repo/releases --jq '.[0:3] | .[] | {tag_name, name, published_at, body}' # README (fallback: WebFetch raw URL if base64 decode fails) gh api repos/owner/repo/readme --jq '.content' | base64 -d ``` From the commit list, find the most-frequently-touched files. Read the top 2–3 of those with `gh api repos/owner/repo/contents/<path>` plus any `CHANGELOG.md`, `ROADMAP.md`, or architecture docs. **External context** — three distinct WebSearch queries: 1. `"owner/repo" site:news.ycombinator.com OR site:lobste.rs OR site:reddit.com` 2. `"owner/repo" twitter OR x.com` (or the project name if distinctive) 3. One query to anchor positioning against a comparable/competing project. **Gate 1 — enough story?** If **all** of the following hold, abort and notify `REPO_ARTICLE_SKIPPED: insufficient activity` (log reason, write no article): - <3 commits in the last 7 days, AND - 0 merged PRs in the last 7 days, AND - no release in the last 30 days, AND - no external mentions surfaced in step 3. **Quiet-repo exception**: if the repo has historical importance but is currently slow (e.g. only 1–2 commits this week, no release), do **not** skip — instead narrow the article's focus to the single most substantive recent change (a specific commit, a contested issue thread, a roadmap update) and write a shorter piece around *that*. Prefer publishing a tight 600-word piece on one real change over skipping. ### Phase 2 — Thesis Write one **falsifiable claim** in ≤25 words. The claim must be disprovable by specific evidence — not a vibe. - Good: "aeonfun/aeon is pivoting from scheduled digests to reactive skill chains — 4 of 7 merged PRs this week added or consumed `output/.chains/*.md` contracts." - Bad: "Aeon is an interesting agent framework." (not falsifiable) If an angle is forced (from `arg`), the thesis must relate to it (e.g. angle `architecture` → an architectural claim). If no angle is forced, pick the one with the strongest evidence from: shipping velocity shift, architectural pivot, community growth inflection, roadmap commitment, deprecation/scope cut, performance or scale milestone. **Gate 2 — falsifiability.** Finish the sentence: "This claim would be wrong if ____." If you can't complete it with something concrete and checkable, rewrite the thesis. ### Phase 3 — Draft (600–900 words, Markdown) ```markdown # [Title that asserts the thesis or a consequence of it — not "A look at X"] [1-paragraph hook, ≤80 words: lead with the thesis or a surprising number that sets it up.] ## The claim > [The falsifiable thesis, verbatim, as a blockquote.] ## Evidence [Two to four sub-paragraphs. Each MUST cite at least one specific commit SHA, PR#, file path, release tag, or external mention. Link the source inline.] ## Counter-evidence / what would change my mind [One paragraph. What recent signals argue against the thesis? Be honest. If genuinely nothing does, say so — but only after looking.] ## Why it matters [One paragraph. Who benefits or loses if the thesis is true? Connect to an ecosystem trend, user need, or competing project.] --- *Sources* - [Label](url) - [Label](url) [≥4 total, ≥1 in-repo (commit/PR link) and ≥1 external (news/social/doc).] ``` ### Phase 4 — Self-edit (required) Run this checklist. Rewrite any line that fails. Target: 8/8 passing. 1. **Thesis visible in first 100 words?** If not, rewrite the hook. 2. **Every section has ≥1 specific number, SHA, PR#, filename, or date?** (generic adjectives don't count) 3. **Zero banned phrases** (see *Banned phrase lexicon* section below — check against that explicit list). 4. **Counter-evidence is real** — not a strawman like "some might say it's complex". 5. **Sources ≥4 links, ≥1 in-repo, ≥1 external.** 6. **Title asserts something** (not "A look at X" / "Exploring Y"). 7. **Word count in 600–900** (hard bounds — trim or expand). 8. **No placeholder phrases** like "[TBD]", "[link]", "[title]". If any item still fails after one rewrite pass, publish with status `REPO_ARTICLE_DEGRADED` and note which items failed in the log — don't hide it. ### Phase 5 — Save, log, notify (repo)