Port boundary diagram, PolicyBench, design principles, and capabilities from the app-v2 draft - #2
Merged
Conversation
The app-v2 draft of this article (PolicyEngine/policyengine-app-v2#1073) carries material this version does not, all of it about why the calculation boundary holds rather than what the stages are. Bring the substantive parts across. - The boundary diagram, ported as-is: predictive language model on one side, deterministic PolicyEngine on the other, with the typed tool boundary between them and tool call / typed result crossing it. - PolicyBench as first-party evidence for the article's premise. The piece previously asserted that models cannot compute reliably and cited only external commentary. - Five design principles, plus the handle rule that makes the privacy boundary structural: a simulation returns an opaque identifier and metadata, never household rows, survey weights, or a serialisable object. - "What you can ask": five kinds of question with a worked prompt and the tool chain each one fires. - The stack, and GET /version reporting the engine versions behind any answer. Almost all of the CSS this needs was already in the legacy stylesheet and unused: .principles-grid, .principle-card, .iteration-num, .insight-box, and .agent-flow-container all come from the original article. Only the boundary diagram's label rules and the question-card layout are new. Note that the typed-surface principle states there is no model-authored Python execution tool, which is at odds with the "reviewed Python" fallback mentioned under What's next. Both cannot be right. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The paragraph above it already makes the point; the callout restated it. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Removed at review: the five design principles section, the stack table, and the Rules entry under What you can ask, which leaves four kinds of question. Replaced both "Select a … to …" hints with a labelled toolbar naming the cards and their count. The hint described an interaction the cards never exposed to the keyboard, so the pickers are now a real tablist: roving tabindex, arrow, Home and End keys, and a tablist/tabpanel pairing. Both pickers share one component instead of repeating the markup. The boundary diagram's connectors get rounded caps and a concave arrowhead, which reads as an arrow rather than a blunt triangle at this scale. The worked example's headline figure now matches the table's units. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The arrow into Weighted outputs turned a hard corner and entered the right edge with a 6px stub. It now sweeps out of Simulate's base into the top edge. "Verified, tool-backed answer" restated what the panel header and the diagram beneath it already say. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Left at .tool-cards' three columns they wrapped 3 + 1. The breakpoint rules below still collapse them to two columns and then one. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The subtitle read as an announcement rather than a description, and several claims leaned on adjectives the piece does not need: work the model "excels at", parts models are "genuinely good at", tools "narrow by design", inputs the user "actually" supplied. The PolicyBench line now reports what was measured, that computed amounts scored lowest, rather than calling them the hardest cases. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
…ents Rendered the diagram and looked at it: the curve between the two box centres put the arrowhead in at an angle, floating short of the box. Simulate and Weighted outputs overlap horizontally between x=700 and x=765, so they are now joined by a plain vertical drop through the middle of that overlap. The boundary section split the system two ways and the next section split it three ways, with nothing connecting them. Name the gateway as the thing sitting on the boundary, deciding whether a proposed plan may cross, which makes the two- and three-part descriptions the same picture. What you can ask now opens by referring back to the worked example, so it reads as widening the scope rather than starting over. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The plugin ecosystem is not tied to one vendor. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Applied across the h1, subtitle, opening paragraph, page title, social metadata, and the Markdown reference copy. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Reverts the subtitle rewrite from the neutral-language pass; the h1 keeps the AI wording. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Ports the material worth keeping from the app-v2 draft of this article (PolicyEngine/policyengine-app-v2#1073) into this version.
Comparing the two, they are independent articles rather than two drafts of one: this version has the better spine, the maintainable source, and a real computed result; the app-v2 draft carries a stronger case for why the calculation boundary holds. This PR brings across the parts of that case we want to keep, and reworks the two card pickers while it is in here.
What this adds
The boundary diagram — ported as-is from the app-v2 draft. Predictive language model on one side, deterministic PolicyEngine on the other, the typed tool boundary between them, and
tool call/typed resultcrossing it. The article previously argued this across three sections of prose without ever drawing it. Connectors have been given rounded caps and a sharper arrowhead for this context.PolicyBench — first-party evidence for the article's premise. The piece asserted that models cannot compute reliably and cited only external commentary (Wikipedia, POST, the NAO); it now leads with our own measurement and the 80.3% exact-match result, and notes that computed amounts were the hardest cases.
"What you can ask" — four kinds of question, each with a worked prompt and the tool chain it fires. The article had one worked example and nothing showing breadth.
What this also changes
Both card pickers are now real tabs. The
Select a family to inspect its toolsandSelect a kind of question to see an examplehints described an interaction that was never exposed to the keyboard. They are replaced by a labelled toolbar naming the cards and their count, and the pickers themselves are a proper tablist: roving tabindex, arrow/Home/End keys, and a tablist/tabpanel pairing. Both share one component rather than repeating the markup.The worked example's headline figure is in billions, matching the units in its own table.
Notes
Almost all of the CSS this needed was already in the legacy stylesheet and unused —
.iteration-num,.agent-flow-containerand friends come from the original article, since both versions descend from it. Only the boundary diagram's label rules, the tab header, and the question-card layout are new.Considered and deliberately left out: the five design principles, the stack table, and the
Rulesquestion kind.One thing still worth settling, which this PR does not touch: the app-v2 draft is framed as a beta throughout and this version has no beta framing at all. Both are currently dated 11 August 2026, and whichever publishes should be consistent about product status.
bun run checkpasses.