[juaristi22]

Fixes #372

Define a consistent standard for parameter labels and descriptions in the engineering guide: labels use concise noun phrases in sentence case, capitalising the first word and preserving capitals in programme proper names and acronyms; descriptions explain the parameter’s purpose and scope. Two hypothetical YAML examples show the distinction, and the model-structure guide links to the standard. This changes guidance and its changelog only; existing parameter wording and model behavior are unchanged.

Validation: make format passed (1,968 files unchanged); three YAML example blocks parsed; the relative documentation anchor and git diff --check passed. All 3,337 non-owned source files and 1,664 Python ASTs stayed unchanged. Independent committed-snapshot code and writing reviews are COMPLETE/APPROVE with no findings.

Model tests and make documentation were not run because this is a guidance-only change, as allowed by docs/engineering/skills/documentation-review.md. The examples describe a hypothetical programme and make no numerical or legal claims. This does not normalise the metadata corpus or complete the separate punctuation issue.

Reproducer: n/a: documentation-only wording guidance; model source, parameters and dependencies are unchanged.

axiom: n/a: engineering documentation only; no policy rule or model behavior changes.

Capitalisation clarification

Both guides now show Capital limit and Universal Credit standard allowance, while retaining the distinction between labels and descriptions. Existing parameter labels, descriptions and model behavior are unchanged.

Local validation for 3e7f66a8: one make format passed with 1,968 files unchanged and Ruff checks passed. The three-file documentation update preserves all 3,337 other tracked files and all 1,664 Python ASTs. Model tests and the documentation build were not run for this wording-only clarification. New-head CI requires separate verification.

[vahid-ahmadi]

@juaristi22 thanks, first-round review at f778f5dfd. The description guidance is clear and matches the checker. One should, on how labels are capitalised.

What I checked

• The new section against policyengine_uk/tests/test_parameter_descriptions.py. "End either form with a period" matches test_parameter_descriptions_end_with_period, and "Labels do not need a trailing period" matches the corpus (none of the 800 metadata.label values ends with one). The examples use metadata.label and top-level description, which is where the model reads them.
• Issue #372 asks for a standard for description wording (labels repeated, "X is ..." padding). The PR answers that, and the "Avoid padding a repeated label with "is"" line covers the screenshots in the issue. Closing it with this PR seems fair, since normalising the corpus is out of scope and the guide says so.
• The new link ../parameter-descriptions.md#labels-and-descriptions points at the new heading.
• CI at head: Lint, Test / Result, Test documentation builds, Fix evidence and Changes all pass; the rest skip as expected for a docs-only change. Reproducer: and axiom: n/a lines are present and fit a docs-only PR.

Findings

1. should: "lowercase noun phrase" doesn't say what happens to programme names and acronyms, and the repo mostly does the opposite. I counted metadata.label across policyengine_uk/parameters: 710 of 800 start with a capital, 87 with a lower-case letter. Most of the capitals are programme names ("Universal Credit ...", "Housing Benefit ...", "Carer's Allowance rate", "PIP ...", "UC ...") but many are plain sentence case ("Maximum ...", "Personal ...", "Qualifying ...", "Savings ..."). The lower-case ones are mostly the newer duty parameters ("alcohol duty spirits rate per litre of pure alcohol", "vehicle excise duty modern registration start"). Read literally, the new text asks for "universal credit standard allowance", which I don't think is meant, and it would also make the guide's own ESA example inconsistent with its label. Could you say explicitly that proper nouns and acronyms keep their capitals, and pick one rule for the first word (lower case, or sentence case like most of the corpus)? One label example with a programme name in it, for example label: Universal Credit standard allowance or label: income-related Employment and Support Allowance capital limit, would settle it. The same wording is in docs/engineering/skills/model-structure.md:29 (that line predates this PR) and the new paragraph at line 32, so both should change together.

Nit: changelog.d/372.fixed.md could be changed rather than fixed, since this adds guidance rather than fixing behaviour. Fine either way.

What looks right: keeping labels stable when improving a description, not forcing one grammatical template across programmes, and keeping the semantic review separate from the automatic check.

🤖 Generated with Claude Code

[juaristi22]

Addressed the capitalisation guidance in review #2603 (review) at 3e7f66a8.

Both guides now specify sentence case: capitalise the first word, preserve programme proper names and acronyms, and lowercase other ordinary words. They share the Capital limit and Universal Credit standard allowance examples. Existing parameter labels, descriptions, model code and the checker are unchanged.

Local make format passed with 1,968 files unchanged and Ruff checks passed. Model tests and the documentation build were not run for this wording-only update; new-head CI is verified separately.

[vahid-ahmadi]

@juaristi22 second round at 3e7f66a8d. Approving.

Status of round 1

1. Label capitalisation (should): resolved. Both docs/engineering/parameter-descriptions.md and docs/engineering/skills/model-structure.md now say sentence case, capitalise the first word, keep capitals in programme names and acronyms, and lower-case other words, with the shared Capital limit and Universal Credit standard allowance examples. The two YAML examples now match. That is the rule Vahid asked for. I found no other guidance in the repo that still asks for lower-case labels.

• Nit on changelog.d/372.fixed.md (fixed vs changed): unchanged, fine either way.

CI at head: Lint, Test / Result, Test documentation builds, Fix evidence and Changes pass; the rest skip as expected for a docs-only change.

🤖 Generated with Claude Code