policyengine-writing

PolicyEngine Writing Skill

Use this skill when writing blog posts, documentation, PR descriptions, research reports, or any public-facing PolicyEngine content.

When to Use This Skill

• Writing blog posts about policy analysis
• Creating PR descriptions
• Drafting documentation
• Writing research reports
• Composing social media posts
• Creating newsletters
• Writing video descriptions and emails to outside readers
• Writing README files

Core Principles

PolicyEngine's writing emphasizes clarity, precision, and objectivity.

1. Active voice - Use an actor and a real verb throughout
2. Direct and quantitative - Use specific numbers, avoid vague adjectives/adverbs
3. Sentence case - Use sentence case for headings, not title case
4. Neutral tone - Describe what policies do, not whether they're good or bad
5. Precise language - Choose exact verbs over vague modifiers

Sentences

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. 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.
5. Mechanism claims come from the source. Before writing what a program or model does, open the statute, parameter file, or code that does it, and write what you read.
6. No "X, not Y" and no "instead of Y" unless Y is real information. State the fact. A real limit stays as its own plain sentence.
7. Name it or cut it. A sentence that alludes to something the reader cannot see ("several programs interact here") carries nothing. Name the programs or delete the sentence.
8. One thought per sentence, varied rhythm. Split any sentence a reader would read twice. Join clauses that share one thought. Vary sentence length within the paragraph; do not turn connected prose into a string of short declarations.
9. Finished work introduces itself fresh. A published post, paper, or doc describes what the analysis shows now. It does not narrate drafts, review rounds, or fixed bugs. Keep substantive assumptions, limitations, sensitivity ranges, and uncertainty beside the claims they qualify. Preserve forecast-registration dates and evidence wherever readers need them to assess a forecast; keep full registration and review trails in supporting records. Corrections, changelogs, PR descriptions, and release notes take history as their subject: state what changed and the new numbers, and never hide a correction to a published claim.
10. Public copy describes the policy, the result, and what the reader can do. This covers posts, newsletters, video descriptions, social posts, PDFs, and emails to outside readers. Cut clauses that only record how or why we produced the piece:
    • production and format choices: "a silent, captioned walkthrough", "no voiceover", "recorded from production", "phone view";
    • process and checking: "two of us checked", "independent arithmetic checks", "we reproduced it in a separate run", "files that match the checksums", "we added it as a structural reform" (rule 3 covers review credentials);
    • work in progress: "follows with a data update", "we hold our estimate back while…", "we plan to update these results later this week", "we are rebuilding the dashboard". State the current limitation in the present tense: "Our estimates exclude the savings income tax rise." When readers need a date to act on, give it: "We will publish revised estimates after the OBR's November forecast.";
    • our reasons for choosing one option over another, unless the reason changes how a number reads.