Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

9.3 KB
Raw Blame

Digest design

Design note for the daily merged-PR digest. Read the product README first for what the digest does and how to turn it on.

Routing

A merge fans out to every audience it belongs to (backend/logic/audiences.py). That is every team owning a file it changed, read back from the ownership the review already resolved. It also includes a per-repo audience when a repo declares its own channel under digest: in .stamphog/policy.yml. A team hears about code it owns, not about everywhere its members touched. So a merge nobody owns, in a repo that declares nothing, reaches nobody. That is an ownership gap, and hogli owners:unowned is where it gets fixed. A slug that is no longer a live GitHub team is not checked at run time. If a same-named Slack channel or a registry entry still exists, the digest keeps posting there; only when neither exists does the audience reach nobody. hogli owners:lint --live is the check that catches a stale slug. Renaming an audience in the ownership files does not move the rows already captured under the old key. A branch opened before the rename keeps producing that key until it rebases, so those rows route nowhere and expire after the seven-day claim window. A PullRequestAudience row per audience is what the daily run claims, so one channel failing to post never strands the merge for another. Generated frontend API types under products/<name>/frontend/generated/ do not count toward a team's stake in a merge, and a team that owns nothing else is not an audience at all. Generated files anywhere else still count, because only that one directory shape is rewritten by a change made elsewhere. hogli build:openapi rewrites a product's generated API types whenever any shared serializer changes anywhere in the repo, so owning one says nothing about whether that team was touched.

Routing is config, and it lives in the repositories rather than in this database (backend/logic/channel_resolution.py). Nothing is stored: a run resolves, posts, and records where it went, so changing a declaration moves the next morning's digest. The order is proximity. A repo: audience takes the channel that repo declared. A team slug takes the root owners.yaml registry of the repo the merge came from. A repo that carries a registry answers for its own merges completely, including by omission: a registry lists the teams whose derived name is wrong, so a missing slug means the derived name is right. A repo carrying no registry inherits one, which is what lets charts route team-data-stack to #group-data-stack because the monorepo says so. Otherwise the slug name-matches a Slack channel, and the app joins one it was never invited to, so a team's digest starts without anyone wiring it up. A registry-derived or name-matched channel that is shared outside the workspace is skipped, because nobody chose it for the audience on purpose. A channel the repository declared under digest: is posted to even when shared. notifications: false on a registry entry is how a team opts out. The registry is asked where automation posts (notifications), which falls back to the team's own slack channel. A team that wants bots somewhere quieter says so once and every producer follows.

Two repos, one team

Two repos declaring one team is a scope, not a conflict. Each answers for the merges that came from it. So one audience can resolve to two channels in a run, and the digest partitions between them. No merge is posted twice and no declaration is discarded.

Summaries and the graze rule

Summaries are written where the diff is. The reviewer emits a change_summary alongside its verdict, which is stamped onto the merged PR. The daily run condenses those rather than guessing from PR titles. For an owning team it also sees which of the changed files are theirs, so a repo-wide sweep that grazed two of them can be dropped as noise. That summary is one sentence about the whole change. On a merge more than one team owns files in, one clause per owning team follows it, each opening with that team's handle. The digest hands its model the sentence and the clause addressed to its own audience, and nothing else, so another team's clause is not there to be picked rather than forbidden. A team that owns part of a merge and got no clause of its own is dropped before the model reads anything, because the reviewer had the diff and found nothing to say about that team's files. A team that owns one file of a change of eight or more never reaches the summarizer: that merge is dropped from the team's digest in code (GRAZE_CHANGED_FILES in backend/logic/digest.py). The rule is deterministic because the prompt carries the title, the reviewed sentence and the paths, never the diff, so nothing in it says what the one file does. The team that owns the rest of the merge still hears about it. The author's own PR body never reaches the prompt, and a PR stamphog never summarized contributes only its title. The reviewed sentence already says what changed, and a long body crowds out the rest of the prompt. What remains is fenced so it cannot close its own tag and continue as instructions.

Two model calls

The daily run asks the model twice. The first call picks the merges worth posting and writes one line each for the thread. The second writes the channel headline and is shown only what the first call kept, so a headline cannot name a change the thread has no line for. A failed second call costs the headline and nothing else, because the first call's lines are already the digest. The headline is written every time, because the changes it sees have already cleared the bar.

Both calls run on Sonnet with adaptive thinking, the selection call at medium effort and the headline at low. Neither call sees the diff or the PR body. So the work is to carry every condition the reviewed text states, such as a flag or a change that does nothing until later work ships, and to add no consequence the text does not state. A smaller model got both wrong often enough that readers acted on lines that were not true, and both prompts state the two rules. The headline sees each kept change's reviewed text and thread line, and its title only when the team owns the whole merge. A title describes the whole pull request, so for a merge the team owns only part of, it is another team's news.

The bar

How many changes a digest carries is decided by the bar and by nothing else. There is no target count and no editorial cap, so a quiet day shows none and a heavy one shows what it earns. The bar is four named rules, contract, assumption, decision and customer, and the summarizer has to name the one that admits each merge it keeps. A merge kept without a valid rule is dropped in code rather than trusted, because an unnamed bar gets rationalized away. On a real day of twenty-six connector fixes, the same model kept twenty-one of them without the rules and none to two with them. The same trick carries the team's own perspective. A team that owns part of a merge was told what the merge was about, which is the other team's news. So the model has to say whether each line it keeps is about the team's own files or about the pull request overall, and a line about the whole pull request is dropped for a team that owns only part of it. A team owning every changed file, and a repo that declared its own channel, are asked for no such claim. Repair overrides all four. Making a broken integration work is maintenance, and only changing what a working one does is news. The one limit is Slack's own block ceiling, which the deterministic fallback rails far below because that path judges nothing.

Consumption

A run consumes every merge it claims, whatever the summarizer decided about it. Unconsumed leftovers would put the same merges in front of the same prompt every morning, where the same text produces the same answer, so a busy team's batch would grow for a week and then age out unseen. Merges above the per-run claim ceiling are the one exception: they are never claimed, so the next run picks them up.

Posting

A digest posts as two messages (backend/logic/slack_digest.py). The channel gets one lead, best available first: the model's headline, otherwise the first change's own line when the headline call failed or answered with something unpostable, and the scope line ("3 of 11 Stamphog-approved merges") when neither is available. Promoting a change line keeps the channel saying something that shipped instead of a bare count, and it is the line the thread already carries, so a reader who wants the diff is one message away. Only a judged run may promote one: the deterministic fallback's lines are unreviewed PR titles. The promoted line has to clear the same no-link rule the headline does, because the channel lead is the one piece of digest text posted without a link attached to it. The per-change lines go in a thread under that lead, so a team spends one line of its channel and opens the rest by choice. Neither message promises the reader every merge of the day: the thread leads with whose judgment picked its contents, and the footer marks the digest as beta and asks for a reaction or a reply, which is where feedback on the digest itself lands. A failed thread reply never fails the run. The lead is already posted and the run's PRs are consumed on that basis, so treating it as a failure would post the same lead again the next day.