From a390469a8d21075eeae4fb9e0de11aa71105a093 Mon Sep 17 00:00:00 2001 From: Max Ghenis Date: Wed, 28 Oct 2026 15:38:39 -0400 Subject: [PATCH 1/2] Writing skill: comparisons take a comparing verb Rule 1 and the active voice examples now cover be-verb comparisons: "our estimate exceeds the Treasury's by 11% in 2026-27 and 16% in 2027-28", not "our estimate is 11% higher than the Treasury's in 2026-27 and 16% higher in 2027-28". The pattern appeared in the live Budget 2026 energy bills post. Co-Authored-By: Claude Opus 5.5 --- skills/policyengine-writing/SKILL.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/skills/policyengine-writing/SKILL.md b/skills/policyengine-writing/SKILL.md index 2929f94..3006b69 100644 --- a/skills/policyengine-writing/SKILL.md +++ b/skills/policyengine-writing/SKILL.md @@ -41,7 +41,7 @@ PolicyEngine's writing emphasizes clarity, precision, and objectivity. These rules apply to every register: blog posts, docs, READMEs, PR descriptions, social copy, and reports back to the team. -1. **Name the actor and action.** Put the person, program, or institution in the subject and a real verb in the predicate. Replace be-verb identities ("the chart is explorable") with actions ("filter the chart by state") wherever an actor can own the verb. +1. **Name the actor and action.** Put the person, program, or institution in the subject and a real verb in the predicate. Replace be-verb identities ("the chart is explorable") with actions ("filter the chart by state") wherever an actor can own the verb. Comparisons take a comparing verb with "by": "our estimate exceeds the Treasury's by 11% in 2026-27 and 16% in 2027-28", not "our estimate is 11% higher than the Treasury's in 2026-27 and 16% higher in 2027-28". 2. **Describe the action, not the scenario label.** Test-case names and table headings are not prose. Write what someone does, what the program or model does next, and who experiences the result. 3. **No glosses and no argument pointers.** Cut sentences whose subject is the text's own word ("X means…", "in other words") or the text's own reasoning ("this is why", "the point is"). Give a definition an agent and a condition where they help explain the subject. Keep formal definitions and equations. Remove narrated honesty, review credentials, and clauses about the writer's care; retain the facts those clauses manage. 4. **Introduce a name or role the first time it appears, then keep to it.** Expand unfamiliar acronyms on first use. Introduce terms with the context the audience needs. Use consistent names for the roles the subject needs. @@ -64,6 +64,7 @@ PolicyEngine projects higher costs than other organizations We estimate the ten-year costs The bill lowers the state's top income tax rate Montana raises the EITC from 10% to 20% +Our estimate exceeds the Treasury's by 11% in 2026-27 and 16% in 2027-28 ``` **❌ Wrong (Passive):** @@ -74,6 +75,7 @@ Higher costs are projected by PolicyEngine The ten-year costs are estimated The state's top income tax rate is lowered by the bill The EITC is raised from 10% to 20% by Montana +Our estimate is 11% higher than the Treasury's in 2026-27 and 16% higher in 2027-28 ``` ## Quantitative and Precise From 43ed71fb6f86057e49eec3e04590f673cbe60a8e Mon Sep 17 00:00:00 2001 From: Max Ghenis Date: Wed, 28 Oct 2026 15:42:00 -0400 Subject: [PATCH 2/2] Writing skill: scope the rule to be-verb comparisons; label the wrong list passive or be-verb Co-Authored-By: Claude Opus 5.5 --- skills/policyengine-writing/SKILL.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/skills/policyengine-writing/SKILL.md b/skills/policyengine-writing/SKILL.md index 3006b69..bada259 100644 --- a/skills/policyengine-writing/SKILL.md +++ b/skills/policyengine-writing/SKILL.md @@ -41,7 +41,7 @@ PolicyEngine's writing emphasizes clarity, precision, and objectivity. These rules apply to every register: blog posts, docs, READMEs, PR descriptions, social copy, and reports back to the team. -1. **Name the actor and action.** Put the person, program, or institution in the subject and a real verb in the predicate. Replace be-verb identities ("the chart is explorable") with actions ("filter the chart by state") wherever an actor can own the verb. Comparisons take a comparing verb with "by": "our estimate exceeds the Treasury's by 11% in 2026-27 and 16% in 2027-28", not "our estimate is 11% higher than the Treasury's in 2026-27 and 16% higher in 2027-28". +1. **Name the actor and action.** Put the person, program, or institution in the subject and a real verb in the predicate. Replace be-verb identities ("the chart is explorable") with actions ("filter the chart by state") wherever an actor can own the verb. A be-verb comparison becomes a comparing verb with "by": "our estimate exceeds the Treasury's by 11% in 2026-27 and 16% in 2027-28", not "our estimate is 11% higher than the Treasury's in 2026-27 and 16% higher in 2027-28". 2. **Describe the action, not the scenario label.** Test-case names and table headings are not prose. Write what someone does, what the program or model does next, and who experiences the result. 3. **No glosses and no argument pointers.** Cut sentences whose subject is the text's own word ("X means…", "in other words") or the text's own reasoning ("this is why", "the point is"). Give a definition an agent and a condition where they help explain the subject. Keep formal definitions and equations. Remove narrated honesty, review credentials, and clauses about the writer's care; retain the facts those clauses manage. 4. **Introduce a name or role the first time it appears, then keep to it.** Expand unfamiliar acronyms on first use. Introduce terms with the context the audience needs. Use consistent names for the roles the subject needs. @@ -67,7 +67,7 @@ Montana raises the EITC from 10% to 20% Our estimate exceeds the Treasury's by 11% in 2026-27 and 16% in 2027-28 ``` -**❌ Wrong (Passive):** +**❌ Wrong (Passive or be-verb):** ``` The Earned Income Tax Credit is proposed to be expanded by Harris Poverty is reduced by 3.2% by the reform