article

name	article
description	Write a publication-ready article in one of three angles - a trending long-form piece, a watched-repo thesis, or a project-through-a-lens essay. Optional Replicate hero image with --visual.
metadata	{"title":"Article","category":"basics","var":"","tags":["content","dev"],"requires":["REPLICATE_API_TOKEN?"]}

${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:

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: ![hero](../images/explainer-${today}.<ext>) — 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

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):

# 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)

# [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)