Plan Editions

An edition is one issue of the engineering newspaper: a stored plans row with kind: "edition", whose stories are written from the PR visual recaps the app already holds. It lives at /editions/:id, and every story links back to the recap it came from so a reader can drop into the real diff.

Editions ship behind the plan.editions lab. Every edition action answers 404 with "Editions is turned off in Labs" until the user turns it on under Settings → Labs; say that rather than retrying.

Editions answer a question search-pr-recaps cannot: not "find me the recap for X" but "tell me what happened, grouped into the handful of things that actually matter". Several PRs that were one piece of work become one story.

Writing an edition

Seven steps, in this order.

1. Select candidates. Call list-edition-candidates with the window. It returns compact candidates (title, brief, repo, PR, recap URL). It deliberately does not return recap bodies — a 40-recap day is far too large to read whole. Read the brief of every candidate, pick the 5–8 that carry the day, and only then call get-visual-plan on those to read their blocks in full.

2. Pass a merged-PR ledger only if you already have one. Plan exposes no provider-api action, so there is no GitHub tool here to fetch one with: do not go looking for a token. mergedPrLedger is optional, and its only job is the coverage note — which merged PRs shipped with no recap. Omit it and the edition publishes from the recaps alone, saying nothing it cannot prove. Supply it only when the session already has GitHub access (a local gh, say) and the extra round trip is worth a more complete colophon.

3. Shape the issue: at most three lead stories. This is the decision that makes an edition readable. Every well-regarded product in this space runs one to three narrative items and collapses the rest — Notion's And a few more…, Railway's Fixes and improvements, Raycast's New / Improvements / Fixes, Linear's tail sections, Google News' five-story briefing cap. Unequal treatment is the hierarchy; seven co-equal stories read as a wall.

So: pick three stories that carry the day. Everything else becomes a quick-link one-liner — lead: false, a single area tag, and a headline that is one plain sentence. Aim for roughly one lead per three-to-five quick links.

4. Write the headline as an abstract. Techmeme rewrites every headline to be "rich on specifics: headlines with names, numbers, and active verbs. Headlines that function as abstracts." Put the shape of the story in the sentence — "Live visual-edit becomes fully editable; eleven PRs make the chrome survive hydration" — so a reader who reads nothing else still knows what happened. One dek sentence after it, stating the consequence, not the implementation.

5. Group the pull requests into cohorts, never one row per PR. A story that spans eleven PRs must not print eleven citations; no product in this space shows per-PR metadata at all, and the ones that solved this group instead. CodeRabbit collapses 28 changed files into two rows — a bold human-named cohort, then one plain sentence. Do the same with PRs: pass 2-4 cohorts, each with a name, a one-sentence sentence, its prNumbers, and its repos.

Set mechanical: true on a cohort that is release commits, lockfiles, codegen, or translation churn. Those render dimmed and sorted last instead of competing with real work — the same suppression linguist-generated gives a diff.

Do not try to put author names or per-PR diff stats in the prose. The reader sees one aggregate per story and a capped avatar stack; per-PR numbers invite a comparison that cannot be made correctly anyway, which is why LinearB shows one aggregate per unit rather than one per PR.

6. Cite the visuals. A recap carries roughly nine blocks — diffs, diagrams, file-trees, wireframes, annotated code — and prose alone throws all of it away. For each lead story pick 1-4 block ids from the recaps you read and pass them as blockIds on that recap ref. The first id is the story's lead art and renders above the fold, so choose the one that makes the change legible at a glance: the diagram for a flow change, the before/after diff for a behavior change, the wireframe for a UI change, the file-tree for a wide refactor.

Cite a visual only when the change earns one — Greptile generates no diagram for a trivial change, and a sequence diagram on a copy tweak costs the reader more than it gives. Quick links carry no art at all; media presence is the tier marker.

Blocks are referenced by id, never copied, so an edition can never show a diagram the recap has since corrected. get-edition reports unresolvedBlockRefs when an id no longer resolves.

7. Publish. Call create-edition exactly once, with every story in the same call. Do not create an edition and then append stories: a background run that is cut off and retried would replay the appends and leave a half-written paper. The action is idempotent on the window's day key, so a retry replaces the edition rather than publishing a second one, and it keeps the issue number it was first published with.

The two rules that matter

An empty candidate set is not a quiet day. Recaps are org-visible, and accessFilter matches only the caller's active org, so a caller in the wrong org sees zero recaps — identical to a day on which nothing merged. list-edition-candidates throws when it can read no recaps at all, and returns status: "empty-window" only when recaps exist but none fall in the window. Never write an edition that says it was quiet because a query came back empty.

"No recap" and "stale recap" are different gaps. CI stamps merged-at only on the merge-close run, so a skipped or failed one leaves a real, readable recap frozen as open. Coverage therefore reports three states, and the edition must keep them apart: recapCount (in-window, merge-proven), stalePrs (a recap exists but was never re-published at merge), and missingPrs (no recap at all). Reporting a stale recap as missing tells a reader to go read a diff by hand when a recap is sitting right there — measured on real data, 1 of 9 uncovered PRs in a single day was stale rather than missing.

A missing number is not zero. filesChanged, additions, and deletions on a story's recap refs are number | null, where null means the stat could not be resolved. Pass null, never 0. Recap coverage also runs under 100% — tiny diffs, fork PRs, and failed recap runs all skip silently — so the coverage note states which merged PRs shipped without a recap instead of implying the recaps were the whole day.

Series: more than one recurring edition

An edition belongs to a series — daily by default, or any lowercase slug such as internal-daily, design-weekly, platform-weekly. Identity is (owner, org, series, window), so a per-repo or per-team edition covering the same day as the org-wide one is a separate issue rather than a replacement. Issue numbers run per series, so internal-daily has its own No. 1.

Scope the selection to match the series: pass repos to list-edition-candidates, scoped to the same repos. A series whose window selection is not scoped will just reprint the org-wide edition under a second name.

One automation per series, each naming its own scope:

manage-automations action=define name=plan-daily-edition
  schedule="0 7 * * *"  body="… series `daily`, all repos …"

manage-automations action=define name=plan-internal-weekly
  schedule="0 8 * * 1"  body="… series `internal-weekly`, repos
                              BuilderIO/builder-internal, over the last 7 days …"

Rows written before series existed read as daily, so an existing daily edition keeps working and keeps its number.

Scheduling it

The morning edition is a scheduled organization automation, not a job file:

manage-automations action=define
  name=plan-daily-edition
  trigger_type=schedule
  schedule="0 7 * * *"
  timezone=<the team's IANA zone>
  scope=organization
  mode=agentic
  domain=plan
  body="Publish today's edition of the engineering newspaper for the last 24
        hours, following the plan-editions skill."

Align the window to the timezone's midnights, not to UTC's. The day key is derived from the window, so a UTC-day window read in Europe/Amsterdam spans two local days and the edition names itself 2026-09-20_2026-09-21 instead of 2026-09-20. For a 07:00 Amsterdam run covering the previous local day, pass 2026-09-19T22:00:00Z to 2026-09-20T22:00:00Z.

Set timezone explicitly — an absent timezone follows the deploy host, not UTC. The automation runs with the org from its own stored identity, so it must be created in the organization that owns the CI-published recaps, or selection will throw. Test with action=run-now, which does real work without disturbing the next scheduled run.

The scheduler does not backfill: a missed morning is gone. Catch-up is the same actions over a wider window — list-edition-candidates and create-edition both take an arbitrary windowStart/windowEnd, and the day key becomes a range (2026-09-08_2026-09-21).

The edition is also read aloud

The reader has a Listen control, and the script is built from the fields you write — the headline, the dek, whatShipped, and each cohort's sentence. Nothing else is spoken: not the diffs, the file lists, the pull-request numbers or the stats, because reading those aloud is noise.

So write those four fields as sentences a person could say. A dek of grid drag: transactionId reads fine on the page and reads as nothing at all out loud; Multi-selection now travels as one pending Apply unit works in both. A story whose prose is only identifiers is a story the listener skips.

Actions

Action	Purpose
list-edition-candidates	Select in-window merged-PR recaps; compute coverage
get-visual-plan	Read a chosen recap's blocks, to pick blockIds from
create-edition	Publish one edition and its stories in a single call
get-edition	Read an edition, its stories in order, and its coverage note
list-editions	The back-issue archive

Related Skills

• plan-review-recaps — the recaps an edition is written from.
• plan-events — plan.created fires for a new edition with kind.
• plan-hosted-writes — verify every hosted write by re-reading it.