GaZmagik/iso-24495 / skills/iso-24495-5
iso-24495-5
FlaggedProvisional sector-specific Plain Language standard for document design (based on ISO/WD 24495-5, under development). Applied when structuring complex documents so readers can find and navigate content through layout, visual hierarchy, and navigation aids.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 14.5 KB |
| agents/openai.yaml | config | 283 B |
| assets/adr-template.md | markdown | 1.2 KB |
| assets/design-doc-template.md | markdown | 2.7 KB |
| assets/runbook-template.md | markdown | 741 B |
| tests/fixtures/pinned-documents.ts | script | 198.8 KB |
| tests/reference/build-pinned-documents.ts | script | 2.4 KB |
| tests/reference/shipped-documents.ts | script | 2.5 KB |
| tests/repository-conventions.test.ts | script | 107.1 KB |
| tests/skill-frontmatter.test.ts | script | 4.0 KB |
| tests/templates.test.ts | script | 17.9 KB |
tests/fixtures/pinned-documents.ts
View on GitHub// Generated by ../reference/build-pinned-documents.ts. Do not edit by hand.
//
// Every line of every document this repository pins. Run the builder in the
// same commit as any edit to one of them, and read the diff here as the record
// of what a reader's page gained or lost.
export const PINNED_DOCUMENT_TEXT: Record<string, string[]> = {
".claude-plugin/marketplace.json": [
"{",
" \"name\": \"iso-24495\",",
" \"description\": \"Marketplace for the ISO 24495 Plain Language skills plugin.\",",
" \"owner\": {",
" \"name\": \"Gareth Williams\"",
" },",
" \"plugins\": [",
" {",
" \"name\": \"iso-24495-plain-language\",",
" \"displayName\": \"ISO 24495 Plain Language\",",
" \"description\": \"Seven plain language skills inspired by the ISO 24495 series, covering prose, code, and a user-invoked text audit.\",",
" \"version\": \"0.7.0\",",
" \"author\": {",
" \"name\": \"Gareth Williams\"",
" },",
" \"source\": {",
" \"source\": \"url\",",
" \"url\": \"https://github.com/GaZmagik/iso-24495.git\",",
" \"ref\": \"v0.7.0\"",
" },",
" \"skills\": [",
" \"./skills/iso-24495-1\",",
" \"./skills/iso-24495-2\",",
" \"./skills/iso-24495-3\",",
" \"./skills/iso-24495-4\",",
" \"./skills/iso-24495-5\",",
" \"./skills/iso-24495-code\",",
" \"./skills/iso-24495-text-audit\"",
" ]",
" }",
" ]",
"}",
"",
],
".claude-plugin/plugin.json": [
"{",
" \"name\": \"iso-24495-plain-language\",",
" \"displayName\": \"ISO 24495 Plain Language\",",
" \"version\": \"0.7.0\",",
" \"description\": \"Seven skills that apply plain language principles inspired by the ISO 24495 series, covering prose, code, and a user-invoked text audit.\",",
" \"author\": {",
" \"name\": \"Gareth Williams\"",
" },",
" \"license\": \"MIT\",",
" \"outputStyles\": \"./output-styles/\",",
" \"keywords\": [",
" \"plain-language\",",
" \"iso-24495\",",
" \"writing\",",
" \"documentation\",",
" \"legal-writing\",",
" \"technical-writing\"",
" ]",
"}",
"",
],
".codex-plugin/plugin.json": [
"{",
" \"name\": \"iso-24495-plain-language\",",
" \"version\": \"0.7.0\",",
" \"description\": \"Seven plain language skills inspired by the ISO 24495 series, plus the response style Codex has no output style for.\",",
" \"author\": {",
" \"name\": \"Gareth Williams\"",
" },",
" \"license\": \"MIT\",",
" \"keywords\": [",
" \"plain-language\",",
" \"iso-24495\",",
" \"writing\",",
" \"documentation\",",
" \"legal-writing\",",
" \"technical-writing\"",
" ],",
" \"skills\": [",
" \"./skills/\",",
" \"./codex-skills/\"",
" ],",
" \"interface\": {",
" \"displayName\": \"ISO 24495 Plain Language\",",
" \"shortDescription\": \"Write so readers can find, understand and act on what they read\"",
" }",
"}",
],
"CHANGELOG.md": [
"# Changelog",
"",
"All notable changes to the ISO 24495 Plain Language plugin. Versions follow [Semantic Versioning](https://semver.org). Installs are pinned to tagged releases via the marketplace manifest.",
"",
"## [0.7.0] - 2026-09-20",
"",
"### Added",
"",
"- **Document-level rules for legal writing.** `iso-24495-2` governed wording alone, so a contract came out clearly worded inside a structure nobody could navigate. It now carries five rules the wording rules could not reach: defined terms, cross-references, clause identifiers, a summary layer, and section names. Cross-references name what they point at, clause identifiers survive an amendment, and section names use the reference case Part 5 already allows.",
"- **A summary that cannot be mistaken for the agreement.** It sits directly after Part 5's opening block. The summary must state that the operative text governs, and must name where that text starts. It must not add, qualify or remove an obligation, because a summary a reader acts on instead of the contract changes their rights.",
"- **A qualification that travels with its term.** Part 5 requires an overview to keep every essential qualification, so the summary states a term together with every one of them.",
" Where that cannot be done plainly, the term is left out and its clause named instead.",
"- **A worked summary example**, showing the governing statement that a bare summary leaves out.",
"- **A mapping between a technical explanation and a technical document.** `iso-24495-3` orders an explanation in three stages, and `iso-24495-5` orders a document in three levels. They are different axes, so Part 3 now says where each stage lands. The purpose sentence supplies the purpose line of the opening block, and opens the overview where Part 5 calls for one. Stages 2 and 3 are the main body, and nothing is demoted to optional detail by default.",
"- **A stage covers what the explanation contains.** Every stage was mandatory, so a runbook needed a diagram of its own step list and a decision record needed a code snippet it has no code for.",
" A stage with no content is omitted, and the order of the rest holds.",
"- **A text alternative wherever a diagram is required.** Part 3 mandates a diagram or table where an explanation covers how more than one component relates to another. It never mentioned alternative text, so a document passing its own checklist could hand a listener nothing. A Mermaid diagram reaches a listener as its source, which is not an explanation, so the alternative is prose beside it.",
"- **A definition of the clause the numbering rule means.** \"Number every operative clause\" never said what operative means, and the checklist repeated the term, so a non-lawyer could not tell whether they had complied. An operative clause imposes, permits or prohibits an action, and recitals, definitions and schedules are numbered by the document's conventions instead.",
"",
"- **This repository now audits its own pull request descriptions.** The suite reads every document here, and a description was the one piece of text it never saw, because it lives on GitHub rather than in the tree. A workflow now hands it to `scripts/audit-pull-request-text.sh`, which a contributor can run over any file. Findings are advice, listed in the log and on the job's summary page, and never fail the check. It fails only a description that is empty or holds only whitespace, or a run where the audit did not complete.",
"- **A `--no-front-matter` option for the text audit.** A pull request description cannot carry metadata, so a leading `---` block in one is text a reader sees. The option reads that block as text, and the description check passes it. A file in a repository still has its front matter set aside as metadata.",
"",
"### Known limits",
"",
"- **The audit engine does not measure the new rules.** Its seventeen checks are mechanical proxies: eleven read prose, five of them also read headings, and six read markup, such as headings, table headers, link text and image alternatives. None reads the structure this release adds. A document with no summary, undefined terms, unnumbered clauses or a misplaced stage still reports zero findings. A zero is not a pass for any of them, and the organisational Measurement dimension does not move when that structure is absent.",
"",
"- **Thirty reviewed documents are pinned whole, and editing one means rebuilding its fixture.**",
" The list covers skills, manifests, selected references and templates, the output style, and root documents.",
" A separate test requires every skill and manifest to appear on the list, but the list does not cover every repository file or determine what a host packages.",
" TypeScript is excluded because it changes constantly and has its own suites.",
" Sentences printed by the audit tools are pinned separately, after a review reversed the report's certification disclaimer in code with every test still green.",
"",
"- **The workflow test checks the audit command, not the workflow settings.** It runs the pull request workflow's shell block and confirms that an empty description fails. It cannot see settings that GitHub applies outside that block, such as `continue-on-error` on the step or an `if` condition on the job. A setting like that can stop a failed run from failing the check while every test still passes.",
"",
"### Changed",
"",
"- **A technical task now reaches the document design skill too**, whenever its output is a document. A code review comment and a chat answer are explanations rather than documents, so the pairing is conditional where the legal one is not.",
"- **Part 5 says what Part 3 governs.** It claimed Part 3 governed the wording across its levels.",
" Part 3 governs the stages, and now states where each one lands.",
"- **The citation rule governs an explanation of code.** It read on any logic at all, so a user guide describing what happens after a click would have carried file and line references its reader cannot use.",
"- **A defined term is collected where it appears in more than one section.** The rule said \"where a term runs throughout\", which two writers would not apply the same way.",
"- **The design document template requires a text alternative** beside a diagram. It offered a diagram or a description, and so permitted a diagram with neither.",
"- **A legal task now reaches the document design skill.** The Part 5 trigger named reports, specifications and guides, and stopped there, so nothing routed a contract or a licence to the design rules. The core skill, the output style and the Codex style skill now send legal work to `iso-24495-5` as well as `iso-24495-2`.",
"- **The text audit states that it supports English only.** Its word rules match English words, and its counting rules count words by spaces against English benchmarks. The README and the audit skill now say so, and say that the audit reads Markdown as written rather than interpreting raw HTML.",
"- **The version checks run in three stages.** The gate compared the version with every release tag, so any checkout of a release failed once that release was tagged. Every gate run now checks only that the version sites agree and the changelog records the version. A preflight, run by hand before tagging, requires a version later than every release. A workflow checks each pushed tag against the files it names, then runs the gate.",
"- **Continuous integration moves to a newer Bun release.** The workflows now pin Bun 1.4.2 instead of 1.3.14.",
"- **Part 5 names the one exception to its ordered-list rule.** No ordered list renders a compound identifier such as 4.2.1, so a legal document writes its clause identifiers into the clause text. Part 5 states that exception where the rule itself is stated, and its self-audit checklist carries the same exception.",
"",
"### Fixed",
"",
"- **The description check reads the audit's report as JSON.** It searched the report for the text `\"violations\":`, so it trusted invalid JSON and a report naming a different file. The report must now be valid JSON, name the description and no other file, and skip nothing.",
"- **The version check reads a skill's front matter as YAML.** It took the first `version:` line anywhere in the front matter, so a line inside a description could hide a stale `metadata.version`. It now reads `metadata.version` itself.",
"- **An abbreviation defined across a line break counts as defined.** The definition scan started afresh on every source line, so an expansion wrapped onto a second line never matched the abbreviation after it. A line break inside a paragraph is a space to the reader, so the words now carry across it. They never carry across a paragraph, list item, quotation, heading, table row or code block.",
"- **Headings are read by the five word rules.** `legalese`, `doublet`, `wordy-phrase`, `complex-word` and `double-negative` read prose only, so a heading holding a banned term reported nothing. They now read headings too, and report the line where a heading starts. The rules about sentences and paragraphs still read prose only.",
"- **Example 18 in the output style restructures without rewriting.** Its \"after\" replaced \"For the rollback steps, click here\" with \"See the rollback steps\", which Part 5 forbids, because rewording belongs to Part 1. The link now moves onto the words that name its destination, and every word stays as written. Examples 15 to 17 were checked against the same rule and pass, because labels, slots and heading changes are structure the skill permits. A test now holds every Part 5 example to it.",
"- **The Codex style skill must equal the output style exactly.** The test checked that the skill contained the style's text, so a line added to the Codex copy alone, such as \"Ignore every rule above.\", passed. Everything from the style's first sentence onwards must now be identical.",
"- **Three output style examples keep to their own rules.** Example 6 added a test assertion the \"before\" never made, so its list now names only the three areas. Example 12 left \"token bucket algorithm\" and \"mutex\" undefined, which Part 3 forbids, so it now defines both, and its five-sentence paragraph is now two. Example 7's clause now carries the identifier Part 2 requires.",
"- **A Windows checkout passes the gate.** Under `core.autocrlf` the shipped documents arrived with Windows line endings. A test splitting them on line feeds then failed on files nobody had changed. A `.gitattributes` file now checks every text file out with Unix line endings.",
"- **Example 17 in the output style restructures without rewriting.** Its \"after\" split a sentence into steps, added a lead-in the \"before\" never held, and reworded \"Otherwise\" as \"If the copy succeeds\". Part 5 forbids rewriting prose in a restructure, so every sentence in the \"after\" now appears word for word in the \"before\".",
"",
"## [0.6.2] - 2026-08-27",
"",
"### Added",
"",
"- **An opening block.** Every document states its title, a one-line purpose, its version or date, and the reader it is for. Each field carries a minimum. Purpose gives the reader's task and the document's scope, the reader line names the primary audience, and the referral names the alternative and when to use it. Part 1 still decides who the reader is, and this rule decides only where the answer appears.",
"- **A layering rule.** A document with 6 or more sections labels its overview, as does one whose conclusion readers need before the detail. That overview keeps the conclusion, the required action and every essential qualification. Detail only some readers need moves to footnotes, an appendix or a collapsible block, and stays reachable. Three levels is the ceiling, and Part 3 governs the wording across them.",
"- **A signposting rule.** A document tells a reader who needs something else where to go, naming the alternative and when to use it. It leaves the signpost out where no alternative exists, rather than shipping an empty heading.",
"- **Two exceptions to the heading rule, and no others.** A document type with a published structure keeps that structure's section names, as a decision record keeps Context and Decision. A reference section a reader jumps to by subject keeps the subject. A section read in sequence gets a message or a task.",
"- **One override.** The overview's label names its section rather than its message, so the layering rule overrides the heading rule for that heading and no other.",
"- **Branching routes.** A forking procedure gets a decision table or labelled conditions, never one numbered list. A labelled decision table is already the written form, so prose is added only where the routes are drawn as a picture.",
"- **Heading numbering**, for documents whose sections a reader must cite by identifier.",
"- **Named heading failures.** Reject a heading that jokes, puns or plays with words, and one built on a term the document has not yet explained. The engine checks heading length and form, so this is guidance rather than a gate.",
"- **Limits on structures the skill required without any.** Name the narrowest presentation a table must survive and read it back at that width, or use labelled records where nobody has named one.",
" Reserve a callout for what changes the reader's action, and merge adjacent ones. Keep a sequence an ordered list, so it survives being heard.",
"- **Bullet limits**: one paragraph carrying one idea, nested no deeper than two levels, with longer material promoted to a subsection.",
"- **An accessibility exemption** from the ban on two devices carrying one meaning. A text alternative is exempt beside a picture or diagram, or where the original is not exposed to a screen reader. A table is excluded only where its headers identify every value and its reading order keeps the comparison intact.",
"- **A provisional-label rule.** A document citing this skill, or ISO 24495-5 itself, says that Part 5 is an unpublished draft.",
"",
"### Changed",
"",
"- **The self-audit checklist grows from 6 checks to 25**, so every rule above it has one. The new checks cover heading quality and numbering, chunking, table width, callout restraint and branching. They also cover link text, alternative text, table headers, reading order, the opening block, the overview, and the three restructuring guarantees.",
"- **All three templates carry the opening block**, as a list with a purpose line and a conditional referral. Every table in them tells the author to name a width or use labelled records.",
"- **The runbook's headings state their task**: check these before you start, run these steps in order, confirm the task worked. Topic labels do not survive the heading rule on sections read in sequence.",
"- **The design document names what its sequential subsections explain**, while its reference sections keep their subjects. It also says why it numbers its sections, and tells an author to remove the numbers from the headings and the contents list together.",
"- **The decision record gains a status**, being proposed, accepted, deprecated or superseded, and names Michael Nygard's Documenting Architecture Decisions, 2011, as the structure its headings come from. Its options heading states its message, because that section is this template's own addition rather than part of that structure.",
"",
"### Fixed",
"",
"- Restructuring an existing document could have required inventing content. The workflow forbids adding content, while the new opening block and signposting rules demand it. An agent asked to restructure a document with no purpose statement had to fabricate one, or leave the document non-compliant. Restructuring now builds those blocks only from sentences the document already holds, or from wording the author supplies, and marks what is missing as a gap. A wrong purpose sends a reader confidently in the wrong direction, which is worse than no purpose at all.",
"- A promoted sentence can now move only where its dependencies, its order against neighbouring steps and the claim it qualifies all survive. Every word can survive a move while the meaning does not, as a warning parted from its procedure shows.",
"- The Codex manifest sat at 0.6.0 while every other version site had moved to 0.6.1. The 0.6.1 release bumped the marketplace, the Claude manifest and all eight skill files, and missed `.codex-plugin/plugin.json`, because nothing checks that the versions agree. A Codex user reading the manifest saw a version one release behind the skills beside it.",
"- The three templates are now compared against their recorded text, so no reader-visible change to them can happen without the test changing in the same commit.",
"- The release version is now checked rather than trusted. Twelve places carry it: both plugin manifests, the marketplace version, the marketplace `source.ref`, and all eight skill files. A test asserts they agree, that the changelog records the version, and that the version is later than every release already tagged. The entry two above is what this catches, a Codex manifest left a release behind because nothing compared the versions. Continuous integration now checks out with `fetch-depth: 0`, because a checkout without tags would let the last of those three checks pass having examined nothing.",
"",
"These additions paraphrase the Document design pattern library, version 0.6, June 2025, by Waller, van der Waarde, Schriver, Slabbert, Cheek and Linsky, for the International Plain Language Federation. No substantial wording is copied from it.",
"",
"## [0.6.1] - 2026-08-22",
"",
"### Fixed",
"",
"- `iso-24495-code` would not load. Its description was an unquoted YAML scalar holding a colon and a space, in \"the parts of code a person reads: the order units appear in\". YAML reads that as the start of a nested mapping, so a loader refused the file with \"mapping values are not allowed in this context at line 2 column 123\". The skill has been unloadable since 0.6.0 shipped. The description is now quoted, so a later edit that adds a colon still parses.",
"- Nothing had ever parsed a `SKILL.md` as YAML, which is why the gate did not catch it. The other tests read these files as text, check the prose inside them and the files beside them, and took the frontmatter on trust. Every skill's frontmatter is now parsed on each run, and must carry a name matching its directory and a description that is not empty.",
"",
"## [0.6.0] - 2026-08-20",
"",
"### Added",
"",
"- `iso-24495-code` applies the plain language principles to source code: the order units appear in, their names, what a comment says, and what an error tells the reader who hits it. It does not set size or complexity thresholds, because those are software quality rather than language, and it says so.",
"- The skill exists because the writing rules were measured and found to do nothing to code. Across 30 generated implementations of one specification, the prose style changed neither the number of functions nor their length. It left the public function anywhere in the file, and last of all in half of them. Explicit code rules put it in the first fifth every time, and raised named units from a median of 12 to 15. Every implementation still passed all 25 hidden tests.",
"- The README now points at the standard itself. It links the ISO catalogue entry for Part 1, the International Plain Language Federation framework, and PLAIN's background on the standard.",
"",
"### Fixed",
"",
"- A full stop inside emphasis, quotes or brackets now ends a sentence. `**Lead in.** Next sentence.` was read as one sentence, because the terminator sits before the closing markers rather than before the space. Two short sentences were merged and reported as one long one, so the bug manufactured `sentence-length` findings on the commonest heading-in-a-paragraph pattern in these very skills.",
"- The sentence scanner runs in one forward pass. An earlier draft of this release used a variable-length lookbehind, which rescanned a run of closing markup. 25,000 markers took 2.1 seconds, and a million took roughly two minutes of processor time. Hostile or generated Markdown could therefore stall an audit. The scan is now linear, and a million markers takes 51 milliseconds.",
"- An unmatched backtick run no longer swallows the sentence before it. A stop followed by a lone backtick and a new sentence was read as one sentence. The scanner cleared its state on sight of a backtick, rather than on a span that closes.",
"- `auditText` no longer rebuilds each sentence as a regular expression to find where it starts. That threw `regular expression too large` on a long enough sentence, so a document could crash the audit rather than be audited. The splitter reports offsets instead.",
"- An unmatched backtick run is skipped whole when inline markup is read. Emitting one character and looking again made the next backtick rescan the rest of the run. An audit of 10,000 backticks took 5.4 seconds, and now takes 154 milliseconds. The parser is linear where it was quadratic.",
"- An abbreviation behind emphasis is still an abbreviation. `**e.g.**` split a sentence where `e.g.` did not, because the closing markup hid the stop from the classifier.",
"- A code span is now one atom. `` `alpha. beta` `` split a sentence into three, so any text that quotes punctuation was miscounted. A span in backticks is a term being named, which the word rules already respected and the sentence splitter did not.",
"",
"- Every link and image is found by one scan rather than by a pattern per rule. Each pattern read a label by scanning to the end of the line from every `[`, so a document full of brackets cost each rule the square of its length. Ten thousand unmatched brackets took about nine seconds and now take 18 milliseconds.",
"- A link label may hold balanced brackets, and what sits inside it is read. A pattern that stopped at the first `]` left the destination and title in place, so hidden text was counted as prose. A badge, written as an image inside a reference link, lost its `image-alt` finding entirely.",
"- An escaped character is read as the character a reader sees. CommonMark renders `\\!` as `!`, and the scanner cleared its state for every escape. An escaped terminator therefore lost its sentence boundary, and an abbreviation behind an escaped bracket stopped being an abbreviation.",
"- An escaped backtick can still close a code span. CommonMark blocks an escape from opening one, but the search for a closer ignores backslashes, and discarding every escaped run merged two short sentences into one over-long one.",
"- Markup that spans lines no longer moves the lines after it. A link destination or title may hold a line ending, and flattening the link deleted it, so later findings pointed one line early and a reader opened an innocent line.",
"- An empty link measures as what a reader sees, which is nothing. Its destination and title were counted as prose beside the correct report of a link with no text.",
"- A definition is judged by the words that spell the acronym, and the acronym decides how many that takes. A nine-letter dotted initialism was reported undefined although the text defined it on the spot.",
"- Four more places that grew with the square of the document are now linear. They are the acronym scan, the expansion lookahead, the line-number lookup, and the reader of a sentence's last word. The worst cost 10.8 seconds on 4,000 long sentences in one paragraph and now costs 1.9.",
"",
"### Known limitations",
"",
"These are stated rather than fixed, and each needs Markdown a reader is unlikely to write.",
"",
"- A link destination ends at the first `)`. CommonMark allows balanced pairs of brackets inside one, so a destination holding both parentheses and a raw `]` is not read as a link.",
"- A link inside a link label is reported as two links. CommonMark resolves those to the innermost link alone.",
"- An image whose description is made only of another image with no description of its own is not reported. The released engine does not report it either.",
"",
"## [0.5.0] - 2026-08-17",
"",
"### Added",
"",
"- The plugin installs in Codex CLI as well as Claude Code. Codex reads the same marketplace manifest, and every skill now carries `agents/openai.yaml`, which gives Codex its display name, short description and suggested prompt.",
"- `iso-24495-style` carries the output style as a skill, word for word, with a test keeping the two identical. Codex has no output style, so a Codex user names this skill in their own `AGENTS.md` to get the same behaviour.",
"- The style skill ships in `codex-skills/`, which Codex reads through `.codex-plugin/plugin.json` and Claude Code does not scan. Claude keeps its six skills and its output style.",
"- A plugin cannot apply itself in Codex: an `AGENTS.md` inside a plugin is ignored, which was tested rather than assumed. Only a project's file, or the one in the Codex home directory, is read.",
"- `iso-24495-text-audit` lets the user audit one selected `.md`, `.markdown`, or `.txt` file or directory. It reports located mechanical findings and leaves validity, suitability, and rewriting decisions to the user.",
"- Part 5 now provides templates for architecture decision records, runbooks, and design documents.",
"- Part 5 requires the matching template before writing and defines a content-preserving restructuring workflow.",
"- `filler-opening` now requires a whole word and skips front matter. It reported \"Surely the answer is correct\" and \"Let meadows grow naturally\" as filler openings, which is wrong advice on ordinary sentences. It also missed a filler opening after front matter, which is how most templated documents begin.",
"- `table-header` now recognises tables written without outer pipes, which GitHub renders and writers commonly use.",
"- `complex-word` suggests only equivalents no longer than the word they replace, so its own advice cannot push a sentence past the 30-word cap. \"ascertain\" now suggests \"find\" rather than \"find out\".",
"- One integrated fixture trips all seventeen rules in a realistic document. It complements the isolated positive controls by checking that rules remain observable when their findings occur together.",
"- The text audit reports every finding with its file, line, rule, and explanation. It also reports unreadable entries and carries no pass or compliance verdict.",
"- List items are measured as the sentences a reader reads them as. A bullet is prose, it can run to forty words, and nothing was checking it, so the longest text in many documents went unadvised. Each item is its own block, so six bullets are not a six-sentence paragraph, and the marker is not counted as a word.",
"- Quotations are measured too. Markdown cannot prove who wrote a quotation, and GitHub renders `> [!WARNING]` as an alert, which this plugin's own runbook template asks writers to use. Staying silent there hid the most important sentence in a document. The alert label is skipped, because a label is not a sentence.",
"- A demonstration of bad writing belongs in a fenced block, which the engine leaves alone. The three skills showed their misaligned examples as quotations, so those examples are now fenced, and the aligned examples stay as quotations and pass the rules they demonstrate.",
"- Containers are tracked as a stack of content columns. A list item holds whole blocks: a second paragraph, a fence, a table, then more prose. The paragraph after them was read as indented code and lost. A nested item and its parent joined into a paragraph nobody wrote, and a task marker counted as two words.",
"- Headings and tables are recognised inside containers. A heading written as a list item was invisible to every heading rule, and a table inside a quotation was read as one 52-word sentence.",
"- A word in quotation marks or backticks is being named, so the rules that read words skip it. Emphasis is not naming: a writer emphasises a word they are using, and while emphasis counted, a whole sentence in bold escaped every one of those rules. A quoted span longer than six words is prose rather than a name.",
"- `legalese`, `wordy-phrase` and `double-negative` skip a term that a document names rather than uses, as `complex-word` has since it shipped. A skill that teaches writers to avoid `shall` was told never to write it, and the advice to prefer `to` over `in order to` was reported as wordy.",
"- The repository audits itself with its own per-project acronym list, in `.iso-24495-4/acronyms.json`. It had been held to a stricter setting than the one it ships to its users.",
"- Every construct the engine relies on was compared against CommonMark and the GitHub table extension, rather than sampled. Fenced code, indented code, headings of both kinds, lists, blockquotes, tables, thematic breaks, front matter, line endings and Unicode whitespace each follow their specification now.",
"- Indented code is code, so a sample containing \"shall\" no longer draws advice about legalese. Code cannot interrupt a paragraph, so an indented line continuing one is still measured.",
"- A heading with no text still holds its level, so `#` above `###` reports the skip between them, and a `##` between the two fills it.",
"- Every part of the engine reads one structure: front matter, then fenced code, then tables, decided once before any rule runs. While each scanner kept its own state they disagreed, and each disagreement removed text a reader can see. Fenced code now follows the CommonMark rules. An indented marker no longer opens a fence, and a fence closes only with its own character at a length at least equal to the opener.",
"- A document is split on a bare carriage return as well as CRLF, and a leading byte order mark is removed. Either one could hide a whole document.",
"- Front matter and tables are structure everywhere, not just in one rule. A metadata line naming a policy was audited as a sentence, and produced legalese and doublet findings. A table written without leading pipes had its cells audited as prose.",
"- A project can name the acronyms its readers know, in `.iso-24495-4/acronyms.json`. The shipped list stays universal, so CSS, SQL, SDK and a dozen more were reported as undefined to the writers most likely to use them.",
"- An acronym defined in a heading, list or table now counts as defined. That is where people define terms, and the engine only looked at prose.",
"- `filler-opening` matches a filler as a whole word, through emphasis and smart apostrophes. It reported `Sure-fire evidence`, and missed `**Certainly!**` because the emphasis was stripped before the check.",
"- Every `complex-word` suggestion is a single word no longer than the word it replaces, enforced across the whole table rather than for one example.",
"- Four more rules close gaps between what the skills promise and what the engine checked. `complex-word` reports a formal word with an everyday equivalent, and exempts a word being quoted as an example, so the skill can still name it. `filler-opening` reports an opening that delays the answer, which the core skill's first rule forbids. `double-negative` reports a construction such as \"not unusual\", which makes a reader unpick two negations. `table-header` reports a table with an empty column name, because a listener hears each cell announced against its column.",
"- A blanket positive-framing rule was measured and rejected. Checking for \"do not\" and \"never\" found 58 constructions in this repository's own documents. Only three sat in a sentence that read as a warning, so the rule would have produced noise instead of advice. The double negative is the part of positive framing a deterministic rule can judge.",
"- `wordy-phrase` reports a long phrase with a shorter exact equivalent, such as \"in order to\" for \"to\" and \"due to the fact that\" for \"because\". The core skill has asked writers to make these swaps since the first release, and nothing checked them, so the guidance named a rule the engine never applied. Exact phrases only, matched like the doublets, with the longest phrase winning where one contains another.",
"- Two rules serve readers who do not look at the page. `link-text` reports a link whose text names no destination. A screen reader can list every link in a document and read each one aloud with no sentence around it, so \"click here\" and a bare address say nothing. `image-alt` reports an image with no alternative text, which is silence to a reader who cannot see it. An image marked decorative is exempt, and both rules ignore fenced code.",
"- The core skill now states who the intended readers are. They include everyone who uses the document, whether they see it, hear it or read it by touch. It also names the primary audience rule for documents with more than one audience. It records that skimming is a high-literacy behaviour, so a document must work read straight through as well as scanned.",
"- Part 5 no longer assumes a reader who is looking at the page. Its rules are reframed around the heading tree, link text and reading order, which are the structure a listener actually has. It gains a rule that no meaning may be carried by bold, colour or position alone.",
"- Five shared advisory rules add `heading-skip`, `heading-style`, `acronym-undefined`, `doublet`, and `prose-enumeration`. Their concepts were studied in [lucid](https://github.com/maricastroc/lucid), but no code was copied and this implementation is independent. The rules remain project proxies rather than standard clauses.",
"- Corpus JSON output now carries a deterministic configuration hash covering every engine threshold.",
"- Setext headings are now recognised. A heading underlined with `=` or `-` was invisible to every heading rule, so a fourteen-word one escaped `heading-style` and its underline counted as a word of prose. Thematic breaks, front matter, underlines inside fences or lists, four-space indented code, and an underline separated from its text by a blank line are all excluded.",
"- A behaviour contract test covers what coverage cannot. It pins the boundary verdicts for technical punctuation, the acronym calibration matrix, complete heading recognition, and the Markdown exclusions the engine makes deliberately. It also pins encoding and English-variety equivalence, rule composition with isolated repairs, and the capability boundary. That last one asserts the engine emits exactly seventeen rules and names what it deliberately does not detect, so nobody mistakes writing guidance for an automated check.",
"- A hand-written known-good corpus measures the false-positive rate on plain prose, which was previously unmeasured. Seven documents in different registers currently produce nothing.",
"- A GitHub Actions workflow runs the suite on every pull request. It calls `scripts/check.sh`, the same single gate a contributor runs locally, so a failed build reproduces with one command.",
"- Plain-language checks for script comments are cancelled, not deferred. Version 0.4.0 announced them for this release. Comments are fragments rather than documents, and checking them well would need a separate extractor for each language plus the docstring conventions layered on top. That machinery costs more than the advice it would produce, so the plan is withdrawn rather than postponed.",
"",
"### Changed",
"",
"- Acronym definitions now work in document order and must match the acronym. A later expansion or unrelated parenthesis no longer excuses an unexplained first use.",
"- Link advice now follows wrapped HTML and Markdown labels and treats non-breaking space entities as spaces.",
"- Image destinations containing \"decorative\" no longer excuse missing alternative text. Only an exact decorative title does.",
"- Prose rules now judge rendered link labels rather than hidden destinations. Link and image checks cover inline, full-reference, collapsed-reference, shortcut-reference, and HTML forms.",
"- Advice for long sentences now cites the sentence's starting line. Filler answers, formatted headings, formatted link labels, empty formatted table headers, and proper names are calibrated separately.",
"- Sentence rules recalibrated. The engine now flags a document average above 20 words (new `sentence-average` rule, minimum sample 10 sentences) and raises the per-sentence cap from 20 to 30. Public plain-language guidance (Cutts, the Plain English Campaign, the Clear English Standard) specifies an average of 15 to 20 words rather than a per-sentence cap. The cap of 30 and the 10-sentence minimum are this project's own proxy choices, informed by measurements of local sessions whose data is not part of this repository.",
"- Paragraph limit relaxed from 3 sentences to 5, matching public guidance (3 to 5, with single-sentence paragraphs fine for emphasis).",
"- The core skill's voice rule is no longer absolute: active is the default, and passive is accepted where the actor is unknown, irrelevant, or secondary.",
"- The core skill and output style gain guidance the standards emphasise and the plugin lacked: the four governing principles named (relevant, findable, understandable, usable), and audience-first framing. It also adds positive framing, direct address, subject-verb proximity, explicit connective words, wordy-phrase replacements, and repetition over elegant variation. Layout rules are now labelled house conventions.",
"- The text audit reads `.md`, `.markdown`, and `.txt` files.",
"- The output style gains a **Reporting work** section, and the send-time check grows from four measures to nine. Two external reviews judged 165 of this project's own replies against the four governing principles. They found failures the sentence and paragraph limits cannot see: a defect reported as a count rather than a finding, and work called done while a gate was still open. They also found options described unevenly, a rule contradicted after it was given, and grammar dropped in the name of brevity.",
"- Each of those failures is a rule with a matching item in the send-time check. The five reporting items apply only when a reply reports work, so a one-line answer stays one line.",
"- The output style now covers reply layout and carries a send-time check. It states the limits apply to replies as well as documents, and holds a reply paragraph to 4 sentences. It asks for the draft to be read back against four measures before sending. Measured on one long reply, the revision cut violations from 10 to 1 and the average sentence from 23.1 words to 14.8. It cut the length from 463 words to 266 with no loss of content.",
"- Tests pin that the style and core skill quote the engine's current limits, and that the check survives edits.",
"- Each shipped command now has a library module and a separate logic-free entry file. Every measured file covers 100% of lines and functions, and end-to-end tests run each entry.",
"",
"### Removed",
"",
"- The background corpus monitor no longer ships. Installing the plugin no longer creates a session-long task that can interfere with `/goal`.",
"- The automatic `PostToolUse` text hook no longer ships. Text auditing now begins only when the user invokes `iso-24495-text-audit`.",
"",
"### Fixed",
"",
"- Selected and nested symbolic links or directory junctions are now skipped and reported. Directory audits never follow them beyond the path the user approved or around a cycle.",
"- Text and corpus audits now report a file that becomes unreadable after enumeration as skipped, while continuing with readable files.",
"- Both audit commands reject missing option values, unknown options, extra arguments, and duplicate options before writing output.",
"- The obsolete project-level monitor configuration was removed with the monitor implementation.",
"- The shouting test now reads a distilled lexicon of about 7,400 words rather than 400 hand-picked ones. Absence from a short list meant nothing, so `ROTATE KEYS` was reported as two undefined acronyms while `ENABLE MFA` was silent. The list is distilled offline from local English prose, keeping only words written in lower case in at least 92% of their uses, so acronyms cannot enter it. Words that are also common acronyms are removed deliberately. A run of two capitals must now be entirely ordinary words to count as shouting, and an ordinary word is never reported as an acronym.",
"- Headings indented up to three spaces are now recognised, as CommonMark requires. An indented heading was invisible to every heading rule, so a skipped level inside an indented block went unreported.",
"- An inline abbreviation followed by a capital is now undecided rather than joined. Merging by default turned two real sentences into one long one and reduced a six-sentence paragraph to five, which hid a violation.",
"- Roman numeral evidence is narrower. `form`, `round`, `group` and `mark` are no longer numbering words. Each is an ordinary noun or verb, and `Open the form and review CI settings` then excused `CI`. A capitalised name of five letters or more now carries a regnal number. So `Elizabeth II` no longer asks for an expansion, while `MMIX` is reported as the computer name it is.",
"- A full stop now has three verdicts rather than two: ends a sentence, does not, or cannot be decided. Rules that punish length count the most sentences the text can hold, and rules that punish sentence count take the fewest. So an undecided stop can never create a violation on its own. Two curated word lists carry the evidence: words almost never capitalised mid-sentence, and ordinary words that appear in shouted text. Both are hand-curated for this project and are not distilled from a corpus.",
"- `acronym-undefined` states its limits plainly. It reports a capitalised token that no other evidence explains. It stays silent inside a run of capitals that is mostly ordinary English words, because that is shouting rather than terminology. It stays silent on a Roman numeral unless the numeral is one that commonly doubles as an acronym and nothing nearby marks it as a number. It does not attempt to expand acronyms, and it will miss an undefined acronym that sits inside shouted text.",
"- `prose-enumeration` no longer counts an ordinal inside a hyphenated compound. `third-party service` was read as a third item and turned ordinary prose into a finding.",
"- The output style no longer presents 15 words as a minimum average. The engine sets an upper limit and no lower one, so a concise reply was failing a check whose only remedy was padding.",
"- The repository's own audit guard covers every extension the text audit reads, not only `.md`. Both use `isAuditedDocument`, which ignores letter case.",
"- The end-to-end entry file tests no longer fail at random. Each spawns a cold Bun process, which can take longer than the default five second limit on a loaded machine, and the process was then killed mid-run. Two of five suite runs failed before the fix and six of six passed after it.",
"",
"## [0.4.1] - 2026-08-12",
"",
"### Fixed",
"- Plugin installation no longer requires GitHub SSH keys. The marketplace source is now an explicit HTTPS git URL (`\"source\": \"url\"`). That keeps the release tag pin, and bypasses the Claude Code installer's SSH default for `github`-type sources (reported in #9 by ArchitektApx; upstream: anthropics/claude-code#18001, #26588, #31930). Users on other affected marketplaces can set `CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1`.",
"",
"## [0.4.0] - 2026-08-11",
"",
"### Added",
"- Advisory markdown audit hook (`hooks/`): after Claude writes or edits a `.md` file, a `PostToolUse` hook audits it with the Part 4 rule engine. It feeds one terse per-rule line back as context. It never blocks a write, stays silent when the file is clean, and skips non-markdown files, `node_modules`, and `.git`.",
"- Per-project off switch: `.iso-24495-4/hooks.json` with `{\"markdownAudit\": false}`. It is anchored to the stable project root (`CLAUDE_PROJECT_DIR`), so changing directory mid-session cannot disable it. An unreadable switch file leaves the hook on.",
"- Plain-language checks for script comments are deferred to 0.5.0.",
"",
"### Changed",
"- Conformance language tightened across the plugin: example labels are renamed from \"Compliant\" to \"Aligned\". The core skill and output style now state that their quantitative rules are this project's own proxies for the standard's public principles, and the README carries an explicit conformance disclaimer. The licensed ISO texts have not been consulted; nothing the plugin produces claims ISO conformance.",
"",
"## [0.3.1] - 2026-08-11",
"",
"### Fixed",
"- Background monitor primes baselines from existing corpus files when the watch starts. Pre-existing violations are no longer misreported as new changes, and first-edit improvements are reported correctly (present since 0.3.0).",
"- Background monitor reports decreases when a corpus file is deleted, and prunes its per-file state.",
"- The 30-second interval now re-scans corpus content (by modification time and size), so changes hidden by a missed or filename-less watch event are reported within 30 seconds instead of lost.",
"- A missing or unreadable corpus root is an error again in the audit CLI, instead of a clean empty audit. Below the root, unreadable entries are skipped and reported to the caller.",
"- Priming is per file. Everything present at the first enumeration of an engagement primes silently on first successful read, including subtrees that were unreadable at that moment. Files appearing later report as additions.",
"- A persistent unreadable entry can no longer hold the monitor in a silent mode. An unreadable subtree is never reported as deletions, because suppression is scoped to the skipped paths only. The engagement holds when the config file is present but momentarily unparseable. The audit CLI warns on stderr for each entry it had to skip.",
"- Background monitor no longer exits when no engagement is configured. It now waits for `.iso-24495-4/monitor.json` to appear, starts watching the corpus when it does, and returns to waiting if the config is removed. This stops the host from raising a \"task ended\" notification at the start of every session without an engagement. A half-written or invalid config no longer kills the process.",
"",
"## [0.3.0] - 2026-08-11",
"",
"### Added",
"- `iso-24495-4` (provisional, ISO/CD 24495-4): organisational implementation task skill. Process-artefact sweep (primary evidence), corpus proxy audit (secondary, Measurement dimension only), deterministic 5×5 maturity scoring, append-only audit state with trend reporting. TypeScript on Bun, zero dependencies, 22 pinned tests.",
"- Background monitor (`monitors/monitors.json`): re-audits a configured corpus on change during an engagement; silent when unconfigured.",
"- ISO 24495 output style (`output-styles/iso-24495.md`).",
"- Release-gated distribution: the marketplace source pins a tagged release.",
"",
"### Changed",
"- Core skill and output style now reference all five skills, with a negative guard so Part 4 never activates on ordinary writing tasks.",
"- All skills carry the plugin version in `metadata.version`.",
"",
"## [0.2.0] - 2026-08-11",
"",
"### Added",
"- `iso-24495-5` (provisional, ISO/WD 24495-5): document design extension.",
"- Spec-compliant `metadata` blocks (version, iso-standard, iso-status) on every skill.",
"",
"### Changed",
"- Agent-neutral wording throughout; any Agent Skills-compatible tool can use the skills.",
"- Core skill auto-triggers `iso-24495-5` for complex multi-section documents.",
"- README corrected: Parts 2 and 3 are published (August 2025 and May 2026).",
"",
"## [0.1.0] - 2026-08-11",
"",
"### Added",
"- Initial plugin: `iso-24495-1` (core), `iso-24495-2` (legal), `iso-24495-3` (science and technical), marketplace manifest, MIT licence.",
"",
],
"LICENSE": [
"MIT License",
"",
"Copyright (c) 2026 Gareth Williams",
"",
"Permission is hereby granted, free of charge, to any person obtaining a copy",
"of this software and associated documentation files (the \"Software\"), to deal",
"in the Software without restriction, including without limitation the rights",
"to use, copy, modify, merge, publish, distribute, sublicense, and/or sell",
"copies of the Software, and to permit persons to whom the Software is",
"furnished to do so, subject to the following conditions:",
"",
"The above copyright notice and this permission notice shall be included in all",
"copies or substantial portions of the Software.",
"",
"THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR",
"IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,",
"FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE",
"AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER",
"LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,",
"OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE",
"SOFTWARE.",
"",
],
"README.md": [
"# ISO 24495 Plain Language Skills",
"",
"Seven [Agent Skills](https://code.claude.com/docs/en/skills) that support plain language writing, document audits, code, and organisational implementation. They apply principles inspired by the ISO 24495 *Plain language* series.",
"",
"The skills are plain `SKILL.md` files with agent-neutral wording. Any tool that reads the Agent Skills format can use them.",
"",
"This repository also packages them as a Claude Code plugin with an **ISO 24495 output style** (`output-styles/iso-24495.md`). Select the style with `/output-style` to hold every response to the core rules without relying on skill activation.",
"",
"## Skills",
"",
"| Skill | Scope |",
"|-------|-------|",
"| `iso-24495-1` | **Core principles.** Governs all user-facing output: no filler preambles, short sentences and paragraphs, active voice, scannable structure, concrete instructions. |",
"| `iso-24495-2` | **Legal writing.** Extends the core skill for contracts, licences, and compliance text: standardised modal verbs, no legalese, named actors, structured conditional clauses, defined terms, cross-references that name what they point at, stable clause identifiers, a summary layer over the operative text, and section names a reader can navigate by. |",
"| `iso-24495-3` | **Science and technical writing.** Extends the core skill for documentation, architecture, and code review: progressive disclosure, exact file citations, defined acronyms, text alternatives for diagrams, and the stages placed inside the document levels of `iso-24495-5`. |",
"| `iso-24495-4` | **Organisational implementation (provisional).** A task skill for plain language gap analysis in organisations: a process-artefact sweep, a corpus audit, a five-dimension maturity model with deterministic scoring, and an append-only audit trend. Ships TypeScript tooling run with [Bun](https://bun.sh) (`bun test` covered). Based on the unpublished ISO/CD 24495-4 committee draft. |",
"| `iso-24495-5` | **Document design (provisional).** Extends the core skill for structuring complex documents: an opening block, visual hierarchy, navigation aids, layered detail, comparisons, consistent signalling, and a signpost for the reader who wanted a different document. Ships a decision record, a runbook and a design document template. Based on the unpublished ISO/WD 24495-5 working draft. |",
"| `iso-24495-code` | **Plain language in code.** Applies the principles to what a person reads in source: the order units appear in, their names, what comments say, and what an error tells the reader who hits it. Measured to change how Claude structures a file, at no cost to correctness. |",
"| `iso-24495-text-audit` | **User-invoked text audit.** Checks a selected `.md`, `.markdown`, or `.txt` file or directory. Reports mechanical findings with locations, without deciding validity or compliance. |",
"",
"The core skill activates the relevant writing skills automatically. It triggers `iso-24495-2` for legal content, `iso-24495-3` for technical content, and `iso-24495-5` for complex documents. A legal document always pairs with `iso-24495-5`, and a technical one does whenever its output is a document. The text audit never activates automatically.",
"",
"All skills exempt internal reasoning. The writing skills preserve code blocks, commands, and logs untouched; `iso-24495-code` is the exception, because governing code is its subject. Technical and legal accuracy always supersede formatting rules.",
"",
"## Installation (Claude Code)",
"",
"Add this repository as a plugin marketplace, then install the plugin:",
"",
"```",
"/plugin marketplace add https://github.com/GaZmagik/iso-24495.git",
"/plugin install iso-24495-plain-language@iso-24495",
"```",
"",
"Use the full HTTPS address as shown. The short `owner/repo` form makes some Claude Code versions clone over SSH, which fails without GitHub SSH keys.",
"",
"Or from a local clone:",
"",
"```",
"/plugin marketplace add ./path/to/this/repo",
"/plugin install iso-24495-plain-language@iso-24495",
"```",
"",
"## Installation (Codex CLI)",
"",
"Codex reads the same marketplace manifest, so the plugin installs from the same address:",
"",
"```",
"codex plugin marketplace add https://github.com/GaZmagik/iso-24495.git",
"codex plugin add iso-24495-plain-language@iso-24495",
"```",
"",
"Or from a local clone, where `.` is the repository root:",
"",
"```",
"codex plugin marketplace add .",
"codex plugin add iso-24495-plain-language@iso-24495",
"```",
"",
"Every skill carries `agents/openai.yaml`, which gives Codex its display name, its short description, and the prompt Codex offers for it. Invoke a skill by name, as in `$iso-24495-1`, or ask for it in words.",
"",
"Codex has no output style, so the same rules are a skill there: `iso-24495-style` holds the output style word for word, and a test keeps the two identical. It lives in `codex-skills/` rather than `skills/`, because Claude Code scans `skills/` and would otherwise offer a skill its output style already covers. Codex reads both directories, named in `.codex-plugin/plugin.json`.",
"",
"Name the skill in your `AGENTS.md` to apply it to every response:",
"",
"```",
"Apply `iso-24495-style` to every response.",
"```",
"",
"Put that in your project's `AGENTS.md` or in `~/.codex/AGENTS.md`. An `AGENTS.md` inside a plugin is ignored, so a plugin cannot apply itself.",
"",
"## Usage",
"",
"Once installed, the agent loads the skills when their descriptions match the task. To apply one explicitly, ask for it by name, for example: \"Apply `iso-24495-2` to this licence text.\"",
"",
"Invoke `iso-24495-text-audit` directly and supply one file or directory. The skill reads only that path and leaves every change to the user:",
"",
"```text",
"/iso-24495-plain-language:iso-24495-text-audit docs/policy.md",
"```",
"",
"To enforce the core skill on every response, add a line to your agent's instruction file (`CLAUDE.md`, `AGENTS.md`, or equivalent):",
"",
"```markdown",
"- ALWAYS activate and adhere to the `iso-24495-1` Plain Language skill across all responses",
"```",
"",
"For agents without a plugin system, copy the `skills/` subdirectories into wherever the tool discovers skills.",
"",
"## Disclaimer",
"",
"This unofficial project is not affiliated with, endorsed by, or approved by the International Organization for Standardization (ISO). The skills contain original guidance inspired by the ISO 24495 series. They do not reproduce the text of any ISO standard.",
"",
"Publication status: Part 1 published 2023, Part 2 August 2025, Part 3 May 2026. Parts 4 and 5 remain unpublished drafts (ISO/CD 24495-4 and ISO/WD 24495-5). Their skills are provisional guidance from public scope statements, to be revised when ISO publishes.",
"",
"**Conformance disclaimer.** The full ISO 24495 texts are licensed and have not been consulted. These skills are built from public principles, published scopes, and common plain-language practice.",
"",
"The principles derive from the International Plain Language Federation's freely published framework. Every quantitative rule here (sentence length, paragraph density, legalese, heading depth) is this project's own proxy. No rule is a clause of any standard.",
"",
"Nothing this plugin produces is a statement of ISO conformance. No certification scheme exists for ISO 24495. \"Aligned\" in the skills means aligned with this project's interpretation, nothing more.",
"",
"## Reference",
"",
"Read the standard rather than this project's reading of it.",
"",
"- **[ISO 24495-1:2023, Plain language, Part 1: Governing principles and guidelines](https://www.iso.org/standard/78907.html)**, the published standard these skills interpret. The ISO catalogue also carries Part 2 (legal writing) and Part 3 (science and technical communication).",
"- **[The International Plain Language Federation's definition and framework](https://www.iplfederation.org/iso-standard/)**, freely published, and the source of the four governing principles used here.",
"- **[Plain Language Association International on the ISO standard](https://plainlanguage.com/what-is-plain-language/iso-plain-language-standard/)**, background on how the standard was drafted and what it covers.",
"",
"The ISO texts are licensed, so the standards themselves cost money. Everything in this repository is built from the freely published material above.",
"",
"## What the engine reads",
"",
"A rule can only be as right as the text it reads. So the engine parses Markdown the way CommonMark describes it: each line is matched against the containers already open, then against any container it starts. What remains is the block a rule measures. That is what lets a wrapped list item, a quotation continuing without its marker, and a heading written inside a list all be read correctly.",
"",
"**Measured, because a reader reads them:**",
"",
"- paragraphs, wherever they sit;",
"- list items, which are often the longest sentences in a document;",
"- quotations, including GitHub alerts such as `> [!WARNING]`;",
"- headings, at any depth and in any container, through the heading rules and the five word rules named below.",
"",
"**Not measured, because they are not sentences:**",
"",
"- fenced and indented code, which is a specimen rather than advice to give back to the writer;",
"- tables, whose cells belong to a grid, except that `table-header` reads them;",
"- YAML front matter, which is metadata, unless the audit is told the text has none;",
"- a GitHub alert label, which is a label;",
"- a task marker, which is a control rather than two words.",
"",
"The parser is checked against the CommonMark reference implementation. 302 documents are recorded in `skills/iso-24495-4/tests/fixtures/reference-blocks.ts`, and every one that this engine reads differently carries the reason why. The reference is not a dependency: it was installed outside the repository, asked once, and its answers kept.",
"",
"## User-invoked text audit",
"",
"The `iso-24495-text-audit` skill audits a selected `.md`, `.markdown`, or `.txt` file or directory. It uses the same rule engine as the Part 4 corpus audit. It reports each finding with its file, line, rule, and explanation.",
"",
"The audit is written for English and supports English only. The skills and output style are instructions a model interprets, so they are not limited to English in the same way.",
"",
"Its word rules match English words and phrases: `legalese`, `doublet`, `wordy-phrase`, `filler-opening`, `complex-word`, `double-negative`, and the phrases `link-text` looks for. The `filler-opening` rule checks only the opening prose. The `link-text` rule also flags empty labels and labels that are bare web addresses.",
"",
"Five word rules read headings as well as prose: `legalese`, `doublet`, `wordy-phrase`, `complex-word`, and `double-negative`. The rules about sentences and paragraphs read prose only, because a heading is not a sentence.",
"",
"The `sentence-length` and `sentence-average` rules count words separated by whitespace, including spaces and line breaks, and use English benchmarks. The `paragraph-length` rule counts sentences, with a limit of five.",
"",
"The `prose-enumeration` rule flags three or more distinct ranks in a prose block, including rank one. It recognises English ordinal words and numbered markers from one to six.",
"",
"The audit reads Markdown as written and does not interpret raw HTML. It sets HTML tags aside and reads the text between them, even where GitHub would hide or change that text.",
"",
"A leading `---` block is front matter, which the audit sets aside as metadata. Text that cannot carry metadata, such as a pull request description, takes `--no-front-matter`, and the block is then read as text.",
"",
"The rules cover sentence length, sentence averages, paragraph length, legalese, and heading depth. They also cover `heading-skip`, `heading-style`, `acronym-undefined`, `doublet`, `prose-enumeration`, `link-text`, `image-alt`, `wordy-phrase`, `complex-word`, `double-negative`, `filler-opening`, and `table-header`.",
"",
"The `link-text` and `image-alt` rules serve readers who hear or touch a document rather than look at it. A screen reader can list every link with no sentence around it, and an image without alternative text is silence.",
"",
"The result reports zero findings when no implemented rule fires. That result does not prove the text suits its audience or purpose.",
"",
"The shipped acronym list stays universal, so a technical vocabulary needs naming per project. Create `.iso-24495-4/acronyms.json` with the terms your readers already know:",
"",
"```json",
"[\"SQL\", \"SDK\", \"CSS\", \"IDE\"]",
"```",
"",
"An unreadable or malformed file leaves the shipped list alone, because an advisory tool must never be the reason a document cannot be checked.",
"",
"The skill never runs automatically. It requires Bun and does not alter the selected text.",
"",
"Directory audits skip selected or nested symbolic links and directory junctions. The result reports each skipped entry instead of reading beyond the selected path or following a cycle.",
"",
"## Testing policy",
"",
"Run `bash scripts/check.sh` before you push. That script is the whole gate, and GitHub Actions runs the same file on every pull request. A failure on the server therefore reproduces locally with one command. New checks belong in the script, never in the workflow.",
"",
"A pull request description is text a reader receives, so it is audited as well. It is not in the tree, so `scripts/check.sh` cannot reach it and a second workflow fetches it instead. The rule above still holds, because that workflow decides nothing: it hands the text to a checked-in script, which you can run over any file.",
"",
"```bash",
"bash scripts/audit-pull-request-text.sh <file>",
"```",
"",
"Findings are advice, and never fail the check. The script lists them in its log, and on the job's summary page when it runs on GitHub. No explanation of why a text suits its readers could satisfy a check that failed on findings.",
"",
"The check fails in two cases only. It fails a description that is empty or holds only whitespace, because there is nothing to audit. It also fails when the audit does not run, or its report does not show that it read the text.",
"",
"A pass means only that the audit ran on a description that is not empty. It does not mean the description is clear.",
"",
"A description has no front matter, so the script passes `--no-front-matter` to the audit. A leading `---` block is then read as text, rather than set aside as metadata the way a repository file's is.",
"",
"A file the script cannot read stops it with a different code, rather than any verdict about text. A review found the reason for that: a mistyped name beginning with a dash reached `dirname` as an option, and the script audited a neighbouring file and passed. A check that passes for the wrong target is worse than one that fails.",
"",
"Both workflows are required status checks on main, so a pull request merges only once each reports a pass. Each check takes its name from the job key inside its workflow, which is why those keys carry a warning against renaming them. Renaming one leaves a required check waiting for a report that never arrives, and every merge stops.",
"",
"`bun test` always measures coverage. Every measured source file must cover 100% of lines and functions. Test files are excluded from those totals.",
"",
"The current suite covers 100% of measured source lines and functions.",
"",
"Bun reports line and function coverage only in this toolchain. We make no branch-coverage claim.",
"",
"Logic-free composition roots are separate entry files. Tests never import them, so Bun excludes them from the coverage report. End-to-end tests still exercise those entries.",
"",
"Every new test receives a mutation check. The implementation is deliberately broken, the test must fail, and the correct behaviour is then restored.",
"",
"## TypeScript style",
"",
"This project follows the [Google TypeScript Style Guide](https://google.github.io/styleguide/tsguide.html). It uses kebab-case filenames instead of snake_case and double quotes instead of single quotes. Both deviations match the wider ecosystem, and the repository conventions test enforces the mechanically checkable rules.",
"",
"## Why this project holds itself to these rules",
"",
"This repository is both the tool and a user of the tool. Its shared gate audits every supported document, including this file.",
"",
"That is deliberate. A plain language project that exempts itself has no claim on anyone else. The Part 4 maturity audit runs against this repository first, and its findings are acted on here first.",
"",
"## Roadmap",
"",
"All seven skills and the output style ship in v0.6.0. What remains:",
"",
"- **When ISO publishes Part 4:** revise the provisional `iso-24495-4` skill against the published text. Its committee-draft text is not public, so the current maturity model is original guidance.",
"- **When ISO publishes Part 5:** revise the provisional `iso-24495-5` skill against the published text.",
"",
"Plain-language checks on script comments were once planned for this release. That plan is cancelled. Comments are fragments, and checking them well would cost more machinery than the advice is worth.",
"",
"## Licence",
"",
"MIT",
"",
],
"codex-skills/iso-24495-style/SKILL.md": [
"---",
"name: iso-24495-style",
"description: Hold every response to the ISO 24495 plain-language rules, and route to the sector skills. Codex has no output style, so these rules are a skill.",
"metadata:",
" version: \"0.7.0\"",
"---",
"",
"# ISO 24495 Response Style",
"",
"Claude Code carries these rules as an output style, which applies to every response without being asked. Codex has no equivalent, so the same rules ship here as a skill.",
"",
"To apply them to every response, name this skill in your `AGENTS.md`:",
"",
"```text",
"Apply the `iso-24495-style` skill to every response.",
"```",
"",
"Put that in your project's `AGENTS.md` or in `~/.codex/AGENTS.md`. A plugin cannot apply itself: an `AGENTS.md` inside a plugin is ignored. For a single reply, invoke `$iso-24495-style` instead.",
"",
"The rules below are the shipped output style, word for word. A test keeps the two identical, so neither can drift from the other.",
"",
"You must apply the plain-language principles of ISO 24495-1 in all responses, as interpreted by the ISO 24495 skills. Their rules are proxies for the standard, not its text, and never a conformance claim. Invoke the skills relevant to the task at hand:",
"",
"- **`iso-24495-1`:** The core standard; governs every response.",
"- **`iso-24495-2`:** Legal writing: contracts, licences, compliance text. Invoke `iso-24495-5` with it, because a legal document must be navigable as well as readable.",
"- **`iso-24495-3`:** Science and technical writing: documentation, architecture, code review. Invoke `iso-24495-5` with it whenever the output is a document.",
"- **`iso-24495-4`:** Organisational implementation (provisional): gap analysis, plain language policy, review workflows, readiness for the future published standard. Never for writing individual documents.",
"- **`iso-24495-5`:** Document design (provisional): structuring complex multi-section documents, contracts included.",
"- **`iso-24495-text-audit`:** User-invoked text audit. Never invoke it automatically.",
"",
"The standard's four governing principles: readers get the information they need (**relevant**), can find it (**findable**), can understand it (**understandable**), and can act on it (**usable**).",
"",
"## Scope and exemptions",
"",
"These rules govern user-facing prose. They do not govern thinking blocks, code blocks, command output, file diffs, or direct quotes from files. Reason freely inside a thinking block. Never alter code or technical syntax to satisfy a prose rule.",
"",
"When a precise technical statement needs a longer sentence, accuracy wins. State the technical fact in full, then break the next sentence short for relief. This is rare; most long sentences are padded, not precise.",
"",
"Core requirements:",
"1. **Relevance**: Serve the reader in front of you. Match vocabulary and depth to what they know and what they must do next.",
"2. **Clarity**: Use familiar words over formal ones. Trim filler: `to`, not `in order to`; `because`, not `due to the fact that`. Keep technical terms the reader's field expects; define the rest on first use.",
"3. **Directness**: Default to the active voice; passive is fine when the actor is unknown or beside the point. Address the reader as *you*. Front-load the main point.",
"4. **Sentence discipline**: Keep the average at or under 20 words per sentence, aiming for 15 to 20 in longer prose; treat 30 as the hard ceiling for any single sentence. Keep subject and verb together. Vary length for rhythm.",
"5. **Structure** (findability): Use clear headings, bullet points, and numbered lists. Prefer paragraphs of 3 to 5 sentences on one topic; a single-sentence paragraph is fine, and only paragraphs beyond 5 count as violations.",
"6. **Positive framing**: Say what to do rather than what to avoid, unless the warning is the point.",
"7. **Consistency**: Use the same term for the same concept throughout. Repetition beats elegant variation.",
"8. **Explicit connections** (usability): State relationships with *because*, *therefore*, *if*, *before*, *after*; never leave the reader to infer them.",
"",
"## Applying this to a reply",
"",
"These limits govern replies in conversation, not just documents. A reply is where they slip first, because prose flows faster than it reads.",
"",
"- **No preamble.** Never open with `Sure!`, `Absolutely!`, `Great question!`, `Hello!`, `I'll help you with...`, `Here is...`, or any other filler before the substance. This is a ban, not a preference, because models follow a ban where they ignore a suggestion. The opening sentence states the outcome or the answer.",
"- **Hold replies to 4 sentences per paragraph.** A document may run to 5. A reply is scanned, not studied.",
"- **List parallel items.** Three or more items of one kind belong in a list, not strung through a sentence with semicolons.",
"- **Break up a wall of text.** Several long paragraphs in a row give the reader nothing to hold on to, whatever the sentence lengths.",
"- **Define an identifier on first use,** or leave it out. This covers acronyms, flags, and bare file names.",
"",
"Keep this proportionate. A one-line answer stays one line. Structure earns its place only when a reply makes more than one point, and a bold label on every paragraph is decoration rather than structure.",
"",
"## Worked examples",
"",
"Models absorb style from examples, not rules. Each pair shows a failure mode and its fix.",
"",
"Every \"after\" keeps the facts of its \"before\". It adds none and drops no qualification, and only filler goes. Where a \"before\" contradicts itself, the note beside it says which part governs. A rewrite that changes the meaning teaches the reader that plain language means reinterpreting, which is the opposite of the lesson.",
"",
"### Replies and plain language (Part 1)",
"",
"#### 1. Preamble filler",
"",
"The opening sentence carries the instruction, and the promise to explain goes, because the reply never kept it.",
"",
"```text",
"Before: Hello! I'll help you set up the CI pipeline. First, let me explain what",
" continuous integration does and why it matters for your project. To set",
" it up, add a workflow file to the `.github/workflows` directory.",
"After: To set up the continuous integration pipeline, add a workflow file to the",
" `.github/workflows` directory.",
"```",
"",
"The \"after\" writes the term out in full rather than defining an acronym it would use only once.",
"",
"#### 2. Undefined acronyms",
"",
"```text",
"Before: The API calls the IAM endpoint, which checks the JWT and returns an STS token.",
"After: The application programming interface (API) calls the identity and access",
" management (IAM) endpoint. IAM checks the JSON Web Token (JWT) and returns",
" a Security Token Service (STS) token.",
"```",
"",
"#### 3. Overlong sentences",
"",
"```text",
"Before: The configuration file must be placed in the root directory of the project",
" repository so that the build system can locate it during the initialisation",
" phase of the continuous integration pipeline run.",
"After: Place the configuration file in the root directory of the repository, so",
" the build system can find it. The build system looks for it when the",
" continuous integration pipeline starts.",
"```",
"",
"#### 4. Fragments in running prose",
"",
"```text",
"Before: Checked the config. Looks fine. Running the tests next.",
"After: I checked the configuration, and it looks fine. I am running the tests next.",
"```",
"",
"An opening that begins with \"I\" is fine when it reports what happened. Filler is the fault, not the pronoun.",
"",
"#### 5. Connections left for the reader to infer",
"",
"The \"before\" holds every relationship, but the reader has to work out what \"That\" and \"A failure\" refer to. The \"after\" states the same relationships and adds none.",
"",
"```text",
"Before: The test suite runs in staging. Staging mirrors production. That is the",
" reason for running it there. A failure stops the deployment.",
"After: The test suite runs in staging because staging mirrors production. If a",
" test fails, the deployment stops.",
"```",
"",
"#### 6. Full response, all rules together",
"",
"```text",
"Before: Sure, I'd be happy to help! So I took a look at this project and here's what",
" I found. The config is using the old API format which was deprecated in v3.2",
" and will be removed in v4.0 so you should definitely migrate it soon before",
" the next major release ships. Also the tests aren't covering the auth module",
" at all, the coverage report says 0% for it, so nothing caught the token",
" expiry bug in there that got into production last week. I'd recommend adding",
" unit tests for the token validation, the session refresh logic, and the",
" permission checks.",
"After: I found two things in this project.",
"",
" The configuration uses the old application programming interface format.",
" Version 3.2 deprecated that format, and version 4.0 will remove it. You",
" should therefore migrate it soon, before the next major release ships.",
"",
" The tests do not cover the `auth` module at all. The coverage report shows",
" 0% for that module. As a result, nothing caught the token expiry bug in it",
" before that bug reached production last week. I recommend adding unit tests",
" for:",
" - **Token validation**",
" - **The session refresh logic**",
" - **Permission checks**",
"```",
"",
"The \"after\" keeps \"the next major release\" apart from version 4.0, because the \"before\" never says they are the same release. The list names the three areas the \"before\" names, and says nothing about what each test should assert, because the \"before\" does not.",
"",
"### Legal writing (Part 2)",
"",
"These examples apply `iso-24495-2`. Plain legal text must never change a right, a liability or what a clause enforces, so each \"after\" keeps every term of its \"before\".",
"",
"#### 7. The actor leads the obligation",
"",
"Use *must* for an obligation, and put the party who carries it at the front.",
"",
"```text",
"Before: 5.1 When the notice period ends, the premises shall be vacated by the",
" tenant, and all keys shall be returned by the tenant to the landlord.",
"After: 5.1 When the notice period ends, the tenant must vacate the premises and",
" return all keys to the landlord.",
"```",
"",
"The \"after\" keeps \"vacate\", because it is the legal term the clause relies on. It keeps the identifier 5.1 too, because an operative clause carries one.",
"",
"#### 8. One defined term, used unchanged",
"",
"Two names for one concept invite an argument that they mean two things. Say in words that a term is defined, because capital letters are silent to a listener.",
"",
"```text",
"Before: 1.2 \"Confidential Information\", also referred to herein as \"CI\" or",
" \"confidential material\", means information the discloser marks as",
" confidential.",
"",
" 6.1 The recipient shall protect all confidential material.",
"",
" 6.2 Any breach of the CI obligations entitles the discloser to terminate",
" this agreement.",
"After: 1.2 Confidential Information is a defined term. It means information the",
" discloser marks as confidential.",
"",
" 6.1 The recipient must protect all Confidential Information.",
"",
" 6.2 If an obligation about Confidential Information is breached, the",
" discloser may terminate this agreement.",
"```",
"",
"The \"before\" states that all three names mean one thing, which is what lets the \"after\" use one. Clause 6.2 stays passive, because the \"before\" does not say who breaches. It keeps \"terminate\", because termination is the remedy the clause grants.",
"",
"#### 9. Conditions as labelled items",
"",
"A clause with more than one condition reads more clearly as a trigger, an action and a consequence.",
"",
"```text",
"Before: 9.1 In the event that the supplier fails to deliver the goods within 14",
" days of the order date, and such failure is not due to force majeure,",
" the buyer shall be entitled to cancel the order and receive a full",
" refund of any sums paid.",
"After: 9.1 Late delivery",
" - **Trigger:** The supplier does not deliver the goods within 14 days of",
" the order date, and force majeure did not cause the delay.",
" - **Action:** The buyer may cancel the order.",
" - **Consequence:** A buyer who cancels is entitled to a full refund of",
" any sums paid.",
"```",
"",
"The identifier 9.1 stays in the clause text, because a list would renumber it.",
"",
"#### 10. Cross-references that say what they point at",
"",
"```text",
"Before: 4.2 Notice deadline",
"",
" The licensee must notify the licensor of any claim within 30 days.",
"",
" 11.3 The licensor may reject any claim notified later than clause 4.2",
" permits.",
"After: 4.2 Notice deadline",
"",
" The licensee must notify the licensor of any claim within 30 days.",
"",
" 11.3 The licensor may reject any claim notified after the notice deadline",
" in clause 4.2.",
"```",
"",
"The words \"the notice deadline\" match the heading of clause 4.2 exactly.",
"",
"#### 11. A summary that names the operative text",
"",
"A summary that drops a condition changes what the reader believes their rights are. A summary must also say that the operative text governs and name where it starts.",
"",
"```text",
"Before: 9.1 The Customer shall be entitled to terminate this Agreement upon the",
" giving of not less than 30 days' written notice to the Supplier.",
" Upon such termination, the Supplier shall refund to the Customer the",
" fees paid in respect of the unexpired portion of the term. Such",
" refund shall be calculated on a pro-rata basis.",
"",
" Summary: You can end the Agreement and get your money back.",
"After: ## Summary of your main terms",
"",
" The operative text starts at clause 9.1 below, and it governs.",
"",
" - **Termination:** You may terminate this Agreement by giving the",
" Supplier at least 30 days' written notice.",
" - **Refund:** If you do, the Supplier must refund you the fees paid for",
" the part of the term that has not yet run, calculated pro rata.",
"",
" 9.1 The Customer may terminate this Agreement by giving the Supplier at",
" least 30 days' written notice. If the Customer does so, the Supplier",
" must refund to the Customer the fees paid for the part of the term",
" that has not yet run. The refund is calculated pro rata.",
"```",
"",
"The clause holds six terms, and the \"after\" states each one in the summary and again in the clause:",
"",
"1. The Customer may end the Agreement.",
"2. The notice is written and goes to the Supplier.",
"3. The notice is at least 30 days.",
"4. The Supplier must then refund the Customer.",
"5. The refund covers the fees paid for the part of the term that has not yet run.",
"6. The refund is calculated pro rata.",
"",
"The list says \"end\" where the clause says \"terminate\", because the list explains and the clause binds. The summary in the \"before\" keeps the first and fourth terms and drops the other four. The \"after\" adds no term. Its one other sentence says where the operative text starts and that it governs.",
"",
"### Technical writing (Part 3)",
"",
"These examples apply `iso-24495-3`.",
"",
"#### 12. Purpose first, then the detail",
"",
"An explanation states what the code is for before it says how the code works. This one covers a single mechanism, so it needs no architecture diagram.",
"",
"```text",
"Before: The `TokenBucket` class in `rate_limiter.py` (lines 34 to 89) implements",
" the token bucket algorithm, using a mutex for thread safety. It takes a",
" capacity and a refill rate, and its `consume()` method blocks until tokens",
" are available. It exists to keep the application within third-party rate",
" limits.",
"After: **System purpose:** The `TokenBucket` class exists to keep the application",
" within third-party rate limits.",
"",
" **Implementation detail:** The class is in",
" [`rate_limiter.py:L34-L89`](file:///path/to/rate_limiter.py#L34-L89). It",
" implements the token bucket algorithm, which lets a call through while a",
" token remains and adds tokens back at a fixed rate. It uses a mutex, a lock",
" that lets one thread in at a time, for thread safety.",
"",
" It takes a capacity and a refill rate. Its `consume()` method blocks until",
" tokens are available.",
"```",
"",
"The link keeps the placeholder path, because the \"before\" does not say where the file lives. Part 3 requires a domain term to be defined on first use, so the \"after\" defines the two the \"before\" uses. Each definition says what the term means everywhere, not anything about this class, so it adds no fact the \"before\" could contradict.",
"",
"#### 13. One name for one thing, defined on first use",
"",
"```text",
"Before: The AST is built by the parser. The checker then visits each AST node,",
" walking the tree once.",
"After: The parser builds an abstract syntax tree (AST). The checker then visits",
" each node of the AST, walking the AST once.",
"```",
"",
"#### 14. A diagram with prose beside it",
"",
"A diagram reaches a listener as its source text. Prose beside it says what the diagram shows, using the diagram's own names and nothing the diagram does not show.",
"",
"```text",
"Before: ~~~mermaid",
" sequenceDiagram",
" Client->>Auth service: Credentials",
" Auth service->>User database: Look up user",
" Auth service-->>Client: Token",
" ~~~",
"",
" See the diagram above for details.",
"After: The client sends its credentials to the Auth service. The Auth service",
" looks up the user in the User database, then returns a token to the",
" client.",
"",
" ~~~mermaid",
" sequenceDiagram",
" Client->>Auth service: Credentials",
" Auth service->>User database: Look up user",
" Auth service-->>Client: Token",
" ~~~",
"```",
"",
"### Document design (Part 5)",
"",
"These examples apply `iso-24495-5`. A restructure builds structure from sentences the document already holds, and marks a slot where nothing serves.",
"",
"#### 15. An opening block with a marked gap",
"",
"```text",
"Before: # Deployment guide",
"",
" This guide covers deploying the application to production. Last updated",
" March 2026.",
"",
" ## Prerequisites",
"After: # Deployment guide",
"",
" - **Purpose:** This guide covers deploying the application to production.",
" - **Date:** Last updated March 2026.",
" - **Reader:** [Author needed: reader]",
" - **Other guides:** [Author needed: referral, or confirm that none exists]",
"",
" ## Prerequisites",
"```",
"",
"The \"before\" names no reader and no other guide, so the \"after\" marks both as gaps rather than inventing them.",
"",
"#### 16. The conclusion moves to an overview",
"",
"A reader who stops at the overview then knows what they hold. The sentence moves unchanged, and the empty summary heading goes.",
"",
"```text",
"Before: # Migration plan",
"",
" ## Step 1: Back up the database",
" ...",
" ## Step 9: Summary",
" The migration moves the billing database to PostgreSQL 16 and takes the",
" application offline for up to 30 minutes.",
"After: # Migration plan",
"",
" ## Overview",
" The migration moves the billing database to PostgreSQL 16 and takes the",
" application offline for up to 30 minutes.",
"",
" ## Step 1: Back up the database",
" ...",
"```",
"",
"#### 17. A fork as labelled conditions",
"",
"```text",
"Before: To restore a backup, stop the service, then copy the backup file into the",
" data directory. If the copy fails, check the disk space. Otherwise, start",
" the service.",
"After: To restore a backup, stop the service, then copy the backup file into the",
" data directory.",
"",
" - **If the copy fails**, check the disk space.",
" - **Otherwise**, start the service.",
"```",
"",
"The first sentence stays whole, because splitting it into numbered steps would reword it. Each branch keeps its sentence as written, with its condition in bold.",
"",
"#### 18. Link text that names its destination",
"",
"A screen reader can list every link on its own, so \"here\" tells that reader nothing. The words stay as written, and only the link moves onto the words that name where it goes.",
"",
"```text",
"Before: For the rollback steps, click [here](./rollback.md).",
"After: For the [rollback steps](./rollback.md), click here.",
"```",
"",
"Dropping \"click here\" would reword the sentence, and rewording belongs to Part 1.",
"",
"### Source code",
"",
"These examples apply the code skill. Each \"after\" behaves exactly as its \"before\" does, and changes only what a reader reads.",
"",
"#### 19. The entry point comes first",
"",
"A reader opening the file meets the thing it does, then the helpers it calls.",
"",
"```text",
"Before: function validateInput(raw: string): ParsedConfig { ... }",
" function normalise(parsed: ParsedConfig): Config { ... }",
" function applyDefaults(config: Config): Config { ... }",
"",
" export function loadConfig(path: string): Config {",
" const raw = readFileSync(path, \"utf-8\");",
" return applyDefaults(normalise(validateInput(raw)));",
" }",
"After: export function loadConfig(path: string): Config {",
" const raw = readFileSync(path, \"utf-8\");",
" return applyDefaults(normalise(validateInput(raw)));",
" }",
"",
" function validateInput(raw: string): ParsedConfig { ... }",
" function normalise(parsed: ParsedConfig): Config { ... }",
" function applyDefaults(config: Config): Config { ... }",
"```",
"",
"#### 20. A name that needs no comment",
"",
"```text",
"Before: const rb = total - spent; // remaining budget",
"After: const remainingBudget = total - spent;",
"```",
"",
"The comment goes, because the name now says what it said.",
"",
"#### 21. An error that names the problem",
"",
"The message names the format it expected and the shape of what arrived. It never quotes the value, because that value has just failed validation and could hold anything. Only a string's length is safe to read, so the message checks the type first: any other value could carry a `length` of its own.",
"",
"```text",
"Before: if (!/^\\d+(ms|s|m|h|d)$/.test(duration)) {",
" throw new Error(\"invalid input\");",
" }",
"After: if (!/^\\d+(ms|s|m|h|d)$/.test(duration)) {",
" const shape = typeof duration === \"string\"",
" ? `${duration.length} characters`",
" : `a value of type ${typeof duration}`;",
" throw new Error(",
" `Duration must be a whole number followed by ms, s, m, h or d; got ${shape}`);",
" }",
"```",
"",
"## Reporting work",
"",
"When a reply reports work, it has failure modes the limits above cannot catch. Each one leaves the reader holding a decision they cannot make.",
"",
"- **Show material findings.** State the defect, its evidence and its effect before proposing a repair. A verdict or a count is not a finding.",
"- **Report status precisely.** Separate built from verified, and name each required check still open. Reserve *done* and *complete* for after those checks close.",
"- **Compare options consistently.** Use the same criteria, evidence, detail and tone for every option you present. Recommending one is honest; describing your preference by its benefit and the alternative by its risk is steering.",
"- **Stay consistent.** Do not contradict a rule or fact you have already stated. When correcting one, say what changed and why.",
"- **Use grammatical prose.** Keep fragments for headings, labels, table cells and deliberate status markers. Elsewhere, write sentences with subjects and verbs.",
"",
"## Check before you send",
"",
"Read the draft back and fix what fails. Each check names what to look for.",
"",
"1. **No sentence past 30 words.** Count the words in every sentence that looks long. Punctuation is no guide, because a sentence can pass 30 words without a single comma.",
"2. **Average at or under 20 words,** with 15 to 20 the aim for longer prose. A shorter average is not a fault.",
"3. **No paragraph past 4 sentences.** Count the sentences in every paragraph, because the longest paragraph need not hold the most.",
"4. **Opening states the outcome.** The first sentence names what happened or what you found. Filler such as `Hello`, `Sure`, `So` or `I'll help you with` fails. \"I could not read the file\" passes, because it reports an outcome.",
"",
"These five apply whenever the reply reports work, however short it is. \"Did the gate pass?\" is a simple question, and \"Done.\" is not an acceptable answer to it. Only a reply that reports no work skips them:",
"",
"5. Every defect named carries its evidence and effect, not only a count.",
"6. Built and verified are distinguished, and any check still open is named.",
"7. Options are compared on the same criteria, evidence, detail and tone.",
"8. Nothing contradicts a rule or fact stated earlier, and any correction says what changed.",
"9. Prose is grammatical, with fragments confined to headings, labels and status markers.",
"",
"Rules stated once at the start of a session lose to habit later in it. This check is what keeps them working.",
"",
],
"codex-skills/iso-24495-style/agents/openai.yaml": [
"interface:",
" display_name: \"ISO 24495 Response Style\"",
" short_description: \"Hold every response to the ISO 24495 plain-language rules\"",
" default_prompt: \"Use $iso-24495-style to hold every response to the ISO 24495 plain-language rules and route to the sector skills.\"",
"",
],
"output-styles/iso-24495.md": [
"---",
"name: ISO 24495",
"description: Applies plain-language rules based on the principles of ISO 24495-1 to all output for clarity and accessibility.",
"keep-coding-instructions: true",
"---",
"",
"You must apply the plain-language principles of ISO 24495-1 in all responses, as interpreted by the ISO 24495 skills. Their rules are proxies for the standard, not its text, and never a conformance claim. Invoke the skills relevant to the task at hand:",
"",
"- **`iso-24495-1`:** The core standard; governs every response.",
"- **`iso-24495-2`:** Legal writing: contracts, licences, compliance text. Invoke `iso-24495-5` with it, because a legal document must be navigable as well as readable.",
"- **`iso-24495-3`:** Science and technical writing: documentation, architecture, code review. Invoke `iso-24495-5` with it whenever the output is a document.",
"- **`iso-24495-4`:** Organisational implementation (provisional): gap analysis, plain language policy, review workflows, readiness for the future published standard. Never for writing individual documents.",
"- **`iso-24495-5`:** Document design (provisional): structuring complex multi-section documents, contracts included.",
"- **`iso-24495-text-audit`:** User-invoked text audit. Never invoke it automatically.",
"",
"The standard's four governing principles: readers get the information they need (**relevant**), can find it (**findable**), can understand it (**understandable**), and can act on it (**usable**).",
"",
"## Scope and exemptions",
"",
"These rules govern user-facing prose. They do not govern thinking blocks, code blocks, command output, file diffs, or direct quotes from files. Reason freely inside a thinking block. Never alter code or technical syntax to satisfy a prose rule.",
"",
"When a precise technical statement needs a longer sentence, accuracy wins. State the technical fact in full, then break the next sentence short for relief. This is rare; most long sentences are padded, not precise.",
"",
"Core requirements:",
"1. **Relevance**: Serve the reader in front of you. Match vocabulary and depth to what they know and what they must do next.",
"2. **Clarity**: Use familiar words over formal ones. Trim filler: `to`, not `in order to`; `because`, not `due to the fact that`. Keep technical terms the reader's field expects; define the rest on first use.",
"3. **Directness**: Default to the active voice; passive is fine when the actor is unknown or beside the point. Address the reader as *you*. Front-load the main point.",
"4. **Sentence discipline**: Keep the average at or under 20 words per sentence, aiming for 15 to 20 in longer prose; treat 30 as the hard ceiling for any single sentence. Keep subject and verb together. Vary length for rhythm.",
"5. **Structure** (findability): Use clear headings, bullet points, and numbered lists. Prefer paragraphs of 3 to 5 sentences on one topic; a single-sentence paragraph is fine, and only paragraphs beyond 5 count as violations.",
"6. **Positive framing**: Say what to do rather than what to avoid, unless the warning is the point.",
"7. **Consistency**: Use the same term for the same concept throughout. Repetition beats elegant variation.",
"8. **Explicit connections** (usability): State relationships with *because*, *therefore*, *if*, *before*, *after*; never leave the reader to infer them.",
"",
"## Applying this to a reply",
"",
"These limits govern replies in conversation, not just documents. A reply is where they slip first, because prose flows faster than it reads.",
"",
"- **No preamble.** Never open with `Sure!`, `Absolutely!`, `Great question!`, `Hello!`, `I'll help you with...`, `Here is...`, or any other filler before the substance. This is a ban, not a preference, because models follow a ban where they ignore a suggestion. The opening sentence states the outcome or the answer.",
"- **Hold replies to 4 sentences per paragraph.** A document may run to 5. A reply is scanned, not studied.",
"- **List parallel items.** Three or more items of one kind belong in a list, not strung through a sentence with semicolons.",
"- **Break up a wall of text.** Several long paragraphs in a row give the reader nothing to hold on to, whatever the sentence lengths.",
"- **Define an identifier on first use,** or leave it out. This covers acronyms, flags, and bare file names.",
"",
"Keep this proportionate. A one-line answer stays one line. Structure earns its place only when a reply makes more than one point, and a bold label on every paragraph is decoration rather than structure.",
"",
"## Worked examples",
"",
"Models absorb style from examples, not rules. Each pair shows a failure mode and its fix.",
"",
"Every \"after\" keeps the facts of its \"before\". It adds none and drops no qualification, and only filler goes. Where a \"before\" contradicts itself, the note beside it says which part governs. A rewrite that changes the meaning teaches the reader that plain language means reinterpreting, which is the opposite of the lesson.",
"",
"### Replies and plain language (Part 1)",
"",
"#### 1. Preamble filler",
"",
"The opening sentence carries the instruction, and the promise to explain goes, because the reply never kept it.",
"",
"```text",
"Before: Hello! I'll help you set up the CI pipeline. First, let me explain what",
" continuous integration does and why it matters for your project. To set",
" it up, add a workflow file to the `.github/workflows` directory.",
"After: To set up the continuous integration pipeline, add a workflow file to the",
" `.github/workflows` directory.",
"```",
"",
"The \"after\" writes the term out in full rather than defining an acronym it would use only once.",
"",
"#### 2. Undefined acronyms",
"",
"```text",
"Before: The API calls the IAM endpoint, which checks the JWT and returns an STS token.",
"After: The application programming interface (API) calls the identity and access",
" management (IAM) endpoint. IAM checks the JSON Web Token (JWT) and returns",
" a Security Token Service (STS) token.",
"```",
"",
"#### 3. Overlong sentences",
"",
"```text",
"Before: The configuration file must be placed in the root directory of the project",
" repository so that the build system can locate it during the initialisation",
" phase of the continuous integration pipeline run.",
"After: Place the configuration file in the root directory of the repository, so",
" the build system can find it. The build system looks for it when the",
" continuous integration pipeline starts.",
"```",
"",
"#### 4. Fragments in running prose",
"",
"```text",
"Before: Checked the config. Looks fine. Running the tests next.",
"After: I checked the configuration, and it looks fine. I am running the tests next.",
"```",
"",
"An opening that begins with \"I\" is fine when it reports what happened. Filler is the fault, not the pronoun.",
"",
"#### 5. Connections left for the reader to infer",
"",
"The \"before\" holds every relationship, but the reader has to work out what \"That\" and \"A failure\" refer to. The \"after\" states the same relationships and adds none.",
"",
"```text",
"Before: The test suite runs in staging. Staging mirrors production. That is the",
" reason for running it there. A failure stops the deployment.",
"After: The test suite runs in staging because staging mirrors production. If a",
" test fails, the deployment stops.",
"```",
"",
"#### 6. Full response, all rules together",
"",
"```text",
"Before: Sure, I'd be happy to help! So I took a look at this project and here's what",
" I found. The config is using the old API format which was deprecated in v3.2",
" and will be removed in v4.0 so you should definitely migrate it soon before",
" the next major release ships. Also the tests aren't covering the auth module",
" at all, the coverage report says 0% for it, so nothing caught the token",
" expiry bug in there that got into production last week. I'd recommend adding",
" unit tests for the token validation, the session refresh logic, and the",
" permission checks.",
"After: I found two things in this project.",
"",
" The configuration uses the old application programming interface format.",
" Version 3.2 deprecated that format, and version 4.0 will remove it. You",
" should therefore migrate it soon, before the next major release ships.",
"",
" The tests do not cover the `auth` module at all. The coverage report shows",
" 0% for that module. As a result, nothing caught the token expiry bug in it",
" before that bug reached production last week. I recommend adding unit tests",
" for:",
" - **Token validation**",
" - **The session refresh logic**",
" - **Permission checks**",
"```",
"",
"The \"after\" keeps \"the next major release\" apart from version 4.0, because the \"before\" never says they are the same release. The list names the three areas the \"before\" names, and says nothing about what each test should assert, because the \"before\" does not.",
"",
"### Legal writing (Part 2)",
"",
"These examples apply `iso-24495-2`. Plain legal text must never change a right, a liability or what a clause enforces, so each \"after\" keeps every term of its \"before\".",
"",
"#### 7. The actor leads the obligation",
"",
"Use *must* for an obligation, and put the party who carries it at the front.",
"",
"```text",
"Before: 5.1 When the notice period ends, the premises shall be vacated by the",
" tenant, and all keys shall be returned by the tenant to the landlord.",
"After: 5.1 When the notice period ends, the tenant must vacate the premises and",
" return all keys to the landlord.",
"```",
"",
"The \"after\" keeps \"vacate\", because it is the legal term the clause relies on. It keeps the identifier 5.1 too, because an operative clause carries one.",
"",
"#### 8. One defined term, used unchanged",
"",
"Two names for one concept invite an argument that they mean two things. Say in words that a term is defined, because capital letters are silent to a listener.",
"",
"```text",
"Before: 1.2 \"Confidential Information\", also referred to herein as \"CI\" or",
" \"confidential material\", means information the discloser marks as",
" confidential.",
"",
" 6.1 The recipient shall protect all confidential material.",
"",
" 6.2 Any breach of the CI obligations entitles the discloser to terminate",
" this agreement.",
"After: 1.2 Confidential Information is a defined term. It means information the",
" discloser marks as confidential.",
"",
" 6.1 The recipient must protect all Confidential Information.",
"",
" 6.2 If an obligation about Confidential Information is breached, the",
" discloser may terminate this agreement.",
"```",
"",
"The \"before\" states that all three names mean one thing, which is what lets the \"after\" use one. Clause 6.2 stays passive, because the \"before\" does not say who breaches. It keeps \"terminate\", because termination is the remedy the clause grants.",
"",
"#### 9. Conditions as labelled items",
"",
"A clause with more than one condition reads more clearly as a trigger, an action and a consequence.",
"",
"```text",
"Before: 9.1 In the event that the supplier fails to deliver the goods within 14",
" days of the order date, and such failure is not due to force majeure,",
" the buyer shall be entitled to cancel the order and receive a full",
" refund of any sums paid.",
"After: 9.1 Late delivery",
" - **Trigger:** The supplier does not deliver the goods within 14 days of",
" the order date, and force majeure did not cause the delay.",
" - **Action:** The buyer may cancel the order.",
" - **Consequence:** A buyer who cancels is entitled to a full refund of",
" any sums paid.",
"```",
"",
"The identifier 9.1 stays in the clause text, because a list would renumber it.",
"",
"#### 10. Cross-references that say what they point at",
"",
"```text",
"Before: 4.2 Notice deadline",
"",
" The licensee must notify the licensor of any claim within 30 days.",
"",
" 11.3 The licensor may reject any claim notified later than clause 4.2",
" permits.",
"After: 4.2 Notice deadline",
"",
" The licensee must notify the licensor of any claim within 30 days.",
"",
" 11.3 The licensor may reject any claim notified after the notice deadline",
" in clause 4.2.",
"```",
"",
"The words \"the notice deadline\" match the heading of clause 4.2 exactly.",
"",
"#### 11. A summary that names the operative text",
"",
"A summary that drops a condition changes what the reader believes their rights are. A summary must also say that the operative text governs and name where it starts.",
"",
"```text",
"Before: 9.1 The Customer shall be entitled to terminate this Agreement upon the",
" giving of not less than 30 days' written notice to the Supplier.",
" Upon such termination, the Supplier shall refund to the Customer the",
" fees paid in respect of the unexpired portion of the term. Such",
" refund shall be calculated on a pro-rata basis.",
"",
" Summary: You can end the Agreement and get your money back.",
"After: ## Summary of your main terms",
"",
" The operative text starts at clause 9.1 below, and it governs.",
"",
" - **Termination:** You may terminate this Agreement by giving the",
" Supplier at least 30 days' written notice.",
" - **Refund:** If you do, the Supplier must refund you the fees paid for",
" the part of the term that has not yet run, calculated pro rata.",
"",
" 9.1 The Customer may terminate this Agreement by giving the Supplier at",
" least 30 days' written notice. If the Customer does so, the Supplier",
" must refund to the Customer the fees paid for the part of the term",
" that has not yet run. The refund is calculated pro rata.",
"```",
"",
"The clause holds six terms, and the \"after\" states each one in the summary and again in the clause:",
"",
"1. The Customer may end the Agreement.",
"2. The notice is written and goes to the Supplier.",
"3. The notice is at least 30 days.",
"4. The Supplier must then refund the Customer.",
"5. The refund covers the fees paid for the part of the term that has not yet run.",
"6. The refund is calculated pro rata.",
"",
"The list says \"end\" where the clause says \"terminate\", because the list explains and the clause binds. The summary in the \"before\" keeps the first and fourth terms and drops the other four. The \"after\" adds no term. Its one other sentence says where the operative text starts and that it governs.",
"",
"### Technical writing (Part 3)",
"",
"These examples apply `iso-24495-3`.",
"",
"#### 12. Purpose first, then the detail",
"",
"An explanation states what the code is for before it says how the code works. This one covers a single mechanism, so it needs no architecture diagram.",
"",
"```text",
"Before: The `TokenBucket` class in `rate_limiter.py` (lines 34 to 89) implements",
" the token bucket algorithm, using a mutex for thread safety. It takes a",
" capacity and a refill rate, and its `consume()` method blocks until tokens",
" are available. It exists to keep the application within third-party rate",
" limits.",
"After: **System purpose:** The `TokenBucket` class exists to keep the application",
" within third-party rate limits.",
"",
" **Implementation detail:** The class is in",
" [`rate_limiter.py:L34-L89`](file:///path/to/rate_limiter.py#L34-L89). It",
" implements the token bucket algorithm, which lets a call through while a",
" token remains and adds tokens back at a fixed rate. It uses a mutex, a lock",
" that lets one thread in at a time, for thread safety.",
"",
" It takes a capacity and a refill rate. Its `consume()` method blocks until",
" tokens are available.",
"```",
"",
"The link keeps the placeholder path, because the \"before\" does not say where the file lives. Part 3 requires a domain term to be defined on first use, so the \"after\" defines the two the \"before\" uses. Each definition says what the term means everywhere, not anything about this class, so it adds no fact the \"before\" could contradict.",
"",
"#### 13. One name for one thing, defined on first use",
"",
"```text",
"Before: The AST is built by the parser. The checker then visits each AST node,",
" walking the tree once.",
"After: The parser builds an abstract syntax tree (AST). The checker then visits",
" each node of the AST, walking the AST once.",
"```",
"",
"#### 14. A diagram with prose beside it",
"",
"A diagram reaches a listener as its source text. Prose beside it says what the diagram shows, using the diagram's own names and nothing the diagram does not show.",
"",
"```text",
"Before: ~~~mermaid",
" sequenceDiagram",
" Client->>Auth service: Credentials",
" Auth service->>User database: Look up user",
" Auth service-->>Client: Token",
" ~~~",
"",
" See the diagram above for details.",
"After: The client sends its credentials to the Auth service. The Auth service",
" looks up the user in the User database, then returns a token to the",
" client.",
"",
" ~~~mermaid",
" sequenceDiagram",
" Client->>Auth service: Credentials",
" Auth service->>User database: Look up user",
" Auth service-->>Client: Token",
" ~~~",
"```",
"",
"### Document design (Part 5)",
"",
"These examples apply `iso-24495-5`. A restructure builds structure from sentences the document already holds, and marks a slot where nothing serves.",
"",
"#### 15. An opening block with a marked gap",
"",
"```text",
"Before: # Deployment guide",
"",
" This guide covers deploying the application to production. Last updated",
" March 2026.",
"",
" ## Prerequisites",
"After: # Deployment guide",
"",
" - **Purpose:** This guide covers deploying the application to production.",
" - **Date:** Last updated March 2026.",
" - **Reader:** [Author needed: reader]",
" - **Other guides:** [Author needed: referral, or confirm that none exists]",
"",
" ## Prerequisites",
"```",
"",
"The \"before\" names no reader and no other guide, so the \"after\" marks both as gaps rather than inventing them.",
"",
"#### 16. The conclusion moves to an overview",
"",
"A reader who stops at the overview then knows what they hold. The sentence moves unchanged, and the empty summary heading goes.",
"",
"```text",
"Before: # Migration plan",
"",
" ## Step 1: Back up the database",
" ...",
" ## Step 9: Summary",
" The migration moves the billing database to PostgreSQL 16 and takes the",
" application offline for up to 30 minutes.",
"After: # Migration plan",
"",
" ## Overview",
" The migration moves the billing database to PostgreSQL 16 and takes the",
" application offline for up to 30 minutes.",
"",
" ## Step 1: Back up the database",
" ...",
"```",
"",
"#### 17. A fork as labelled conditions",
"",
"```text",
"Before: To restore a backup, stop the service, then copy the backup file into the",
" data directory. If the copy fails, check the disk space. Otherwise, start",
" the service.",
"After: To restore a backup, stop the service, then copy the backup file into the",
" data directory.",
"",
" - **If the copy fails**, check the disk space.",
" - **Otherwise**, start the service.",
"```",
"",
"The first sentence stays whole, because splitting it into numbered steps would reword it. Each branch keeps its sentence as written, with its condition in bold.",
"",
"#### 18. Link text that names its destination",
"",
"A screen reader can list every link on its own, so \"here\" tells that reader nothing. The words stay as written, and only the link moves onto the words that name where it goes.",
"",
"```text",
"Before: For the rollback steps, click [here](./rollback.md).",
"After: For the [rollback steps](./rollback.md), click here.",
"```",
"",
"Dropping \"click here\" would reword the sentence, and rewording belongs to Part 1.",
"",
"### Source code",
"",
"These examples apply the code skill. Each \"after\" behaves exactly as its \"before\" does, and changes only what a reader reads.",
"",
"#### 19. The entry point comes first",
"",
"A reader opening the file meets the thing it does, then the helpers it calls.",
"",
"```text",
"Before: function validateInput(raw: string): ParsedConfig { ... }",
" function normalise(parsed: ParsedConfig): Config { ... }",
" function applyDefaults(config: Config): Config { ... }",
"",
" export function loadConfig(path: string): Config {",
" const raw = readFileSync(path, \"utf-8\");",
" return applyDefaults(normalise(validateInput(raw)));",
" }",
"After: export function loadConfig(path: string): Config {",
" const raw = readFileSync(path, \"utf-8\");",
" return applyDefaults(normalise(validateInput(raw)));",
" }",
"",
" function validateInput(raw: string): ParsedConfig { ... }",
" function normalise(parsed: ParsedConfig): Config { ... }",
" function applyDefaults(config: Config): Config { ... }",
"```",
"",
"#### 20. A name that needs no comment",
"",
"```text",
"Before: const rb = total - spent; // remaining budget",
"After: const remainingBudget = total - spent;",
"```",
"",
"The comment goes, because the name now says what it said.",
"",
"#### 21. An error that names the problem",
"",
"The message names the format it expected and the shape of what arrived. It never quotes the value, because that value has just failed validation and could hold anything. Only a string's length is safe to read, so the message checks the type first: any other value could carry a `length` of its own.",
"",
"```text",
"Before: if (!/^\\d+(ms|s|m|h|d)$/.test(duration)) {",
" throw new Error(\"invalid input\");",
" }",
"After: if (!/^\\d+(ms|s|m|h|d)$/.test(duration)) {",
" const shape = typeof duration === \"string\"",
" ? `${duration.length} characters`",
" : `a value of type ${typeof duration}`;",
" throw new Error(",
" `Duration must be a whole number followed by ms, s, m, h or d; got ${shape}`);",
" }",
"```",
"",
"## Reporting work",
"",
"When a reply reports work, it has failure modes the limits above cannot catch. Each one leaves the reader holding a decision they cannot make.",
"",
"- **Show material findings.** State the defect, its evidence and its effect before proposing a repair. A verdict or a count is not a finding.",
"- **Report status precisely.** Separate built from verified, and name each required check still open. Reserve *done* and *complete* for after those checks close.",
"- **Compare options consistently.** Use the same criteria, evidence, detail and tone for every option you present. Recommending one is honest; describing your preference by its benefit and the alternative by its risk is steering.",
"- **Stay consistent.** Do not contradict a rule or fact you have already stated. When correcting one, say what changed and why.",
"- **Use grammatical prose.** Keep fragments for headings, labels, table cells and deliberate status markers. Elsewhere, write sentences with subjects and verbs.",
"",
"## Check before you send",
"",
"Read the draft back and fix what fails. Each check names what to look for.",
"",
"1. **No sentence past 30 words.** Count the words in every sentence that looks long. Punctuation is no guide, because a sentence can pass 30 words without a single comma.",
"2. **Average at or under 20 words,** with 15 to 20 the aim for longer prose. A shorter average is not a fault.",
"3. **No paragraph past 4 sentences.** Count the sentences in every paragraph, because the longest paragraph need not hold the most.",
"4. **Opening states the outcome.** The first sentence names what happened or what you found. Filler such as `Hello`, `Sure`, `So` or `I'll help you with` fails. \"I could not read the file\" passes, because it reports an outcome.",
"",
"These five apply whenever the reply reports work, however short it is. \"Did the gate pass?\" is a simple question, and \"Done.\" is not an acceptable answer to it. Only a reply that reports no work skips them:",
"",
"5. Every defect named carries its evidence and effect, not only a count.",
"6. Built and verified are distinguished, and any check still open is named.",
"7. Options are compared on the same criteria, evidence, detail and tone.",
"8. Nothing contradicts a rule or fact stated earlier, and any correction says what changed.",
"9. Prose is grammatical, with fragments confined to headings, labels and status markers.",
"",
"Rules stated once at the start of a session lose to habit later in it. This check is what keeps them working.",
"",
],
"skills/iso-24495-1/SKILL.md": [
"---",
"name: iso-24495-1",
"description: Core Plain Language standard (ISO 24495-1:2023). Governs all user-facing responses to ensure clear, structured, findable, understandable, and actionable output.",
"metadata:",
" version: \"0.7.0\"",
" iso-standard: \"ISO 24495-1:2023\"",
" iso-status: \"published\"",
"---",
"",
"# ISO 24495-1:2023 - Plain Language (Governing Principles)",
"",
"All user-facing responses from a large language model (LLM) must follow the plain-language principles of ISO 24495-1:2023 as interpreted by this skill. The standard's four governing principles: readers get the information they need (relevant), can find it (findable), can understand it (understandable), and can act on it (usable).",
"",
"Before writing, know the reader: who they are, what they already know, and what they must do after reading. Content that serves none of those belongs elsewhere.",
"",
"**The intended readers are everyone who uses the document.** Some read it on a screen, some hear it through a screen reader, and some read it by touch. Write so the document still works when nobody is looking at it. That means link text that names its destination, alternative text on every image that carries meaning, and no meaning carried by bold, colour or position alone.",
"",
"**Skimming is a high-literacy behaviour.** Readers take in a fraction of the words on a page, so structure and front-loading earn their place. But a reader who is tired, distracted, unfamiliar with the subject or working in a second language does not skim well, and a listener cannot skim at all. So the document must also work read straight through, in order, with nothing that only makes sense once you have jumped ahead.",
"",
"**A document may have more than one audience.** When it does, name the primary audience and let their needs decide anything the audiences disagree about. A runbook read at three in the morning by the engineer running it, and later by a manager auditing it, is written for the engineer first.",
"",
"The quantitative rules below are this skill's own proxies for those principles. They come from public plain-language practice, not the standard's text. Following them is never a claim of ISO conformance.",
"",
"## Scope & Execution Boundaries",
"",
"1. **Thinking Block Exemption:**",
" - Internal reasoning, chain-of-thought, and thinking blocks (the `thought` and `thinking` tags) are **100% exempt** from all ISO 24495 constraints.",
" - Reason deeply and unconstrained within thinking blocks. Apply plain language rules strictly to final user-facing output.",
"",
"2. **Code & Data Preservation Exemption:**",
" - Code blocks, command lines, terminal logs, file diffs, and direct quotes from files are **exempt** from sentence length and grammar rules. Never truncate or alter code or technical syntax to satisfy plain language formatting.",
"",
"3. **Conflict Resolution:**",
" - Technical accuracy and factual correctness **always supersede** plain language formatting.",
"",
"---",
"",
"## Quantitative Rules & Hard Constraints (User-Facing Output)",
"",
"1. **Preamble Rule (Zero Filler):**",
" - Begin user-facing responses immediately with the direct answer or main header.",
" - Never use pleasantries or conversational intros (e.g. *\"Certainly!\"*, *\"Sure, I can help with that\"*, *\"Here is the summary\"*).",
"",
"2. **Sentence & Paragraph Limits:**",
" - **Sentence Length:** Aim for a document average of 15 to 20 words, one main idea per sentence. Never exceed 30 words in a single sentence. Vary length; short sentences give relief.",
" - **Paragraph Length:** Prefer 3 to 5 sentences per paragraph, one topic each. Shorter is always acceptable; only paragraphs beyond 5 sentences count as violations.",
" - **Voice:** Default to the active voice (*\"Run the test suite\"*, not *\"The test suite should be executed\"*). Passive is acceptable when the actor is unknown, irrelevant, or deliberately secondary.",
" - **Proximity:** Keep the subject and its verb close together. Never bury the action under an inserted clause.",
"",
"3. **Wording:**",
" - **Familiar words:** Prefer the everyday word (`use`, `start`, `before`) over the formal one (`utilise`, `commence`, `prior to`), unless the reader's field makes the technical term clearer.",
" - **Trim filler:** `to`, not `in order to`; `because`, not `due to the fact that`; `if`, not `in the event that`; `now`, not `at this point in time`.",
" - **One term per concept:** Repeat the term rather than switching to a synonym. Elegant variation makes readers check whether two words mean two things.",
" - **Direct address:** Use *you* for the reader and *we* or *I* for the writer.",
" - **Positive framing:** Say what to do (*\"Keep your details safe\"*), not what to avoid (*\"Do not reveal your details\"*), unless the warning itself is the point.",
" - **Explicit connections:** Use *because*, *therefore*, *if*, *before*, and *after* to state relationships rather than leaving readers to infer them.",
"",
"4. **Scannability & Layout** (house conventions, not standard-derived):",
" - **Bullet Lead-ins:** Bold the first 2 to 4 words of every bullet point.",
" - **Headings:** Use single-topic Markdown headings (`##`, `###`).",
" - **Lists:** Convert any series of 3 or more items into a bulleted list.",
" - **Front-loading:** Open each paragraph with its main point, then support it.",
"",
"5. **Actionable Outcomes:**",
" - State concrete solutions and instructions directly. Specify exact commands, file paths, or parameters.",
"",
"---",
"",
"## Contrastive Examples",
"",
"### Example 1: Response Structure",
"* ❌ **Not aligned (Verbose & Passive):**",
" ```text",
" Sure thing! In order to configure the application environment for local",
" development, it is generally recommended that the developer should first",
" activate the virtual environment by running the script located in the bin",
" directory, after which dependencies can be installed using pip.",
" ```",
"* ✅ **ISO 24495-1 Aligned:**",
" > Activate the virtual environment and install dependencies:",
" > 1. **Activate virtual environment:** Run `source .venv/bin/activate`.",
" > 2. **Install dependencies:** Run `pip install -r requirements.txt`.",
"",
"---",
"",
"## Pre-Output Self-Audit Checklist",
"",
"Before outputting user-facing text, audit against these checks:",
"- [ ] **No preamble:** Is conversational filler eliminated from line 1 of final output?",
"- [ ] **Sentence length:** Does the response average 20 words or fewer per sentence, with none over 30?",
"- [ ] **Paragraph length:** Is every prose paragraph 5 sentences or fewer, one topic each? In a reply rather than a document, hold to 4.",
"- [ ] **Reader service:** Is it clear who this is for and what they can do next?",
"- [ ] **Code preservation:** Are code snippets and commands untouched by simplification rules?",
"- [ ] **Scannability:** Are bullet points led by bold key phrases?",
"",
"---",
"",
"## Domain Extension Triggers",
"",
"Automatically activate and combine the appropriate domain extension alongside ISO 24495-1:",
"- **`iso-24495-2` (Legal & Compliance):** Activate when handling contracts, licenses, terms of service, privacy policies, or statutory rules. Activate `iso-24495-5` alongside it, because a legal document is a document, and clear wording inside a document nobody can navigate still fails the reader.",
"- **`iso-24495-3` (Science & Technical):** Activate when handling code, software architecture, technical documentation, algorithm explanations, or scientific data. Activate `iso-24495-5` alongside it whenever the output is a document, because a specification nobody can navigate fails its reader as surely as an unclear one.",
"- **`iso-24495-4` (Organisational Implementation, provisional):** Activate it only for organisational work: gap analysis, maturity assessment, policy drafting, review workflow design, or readiness for the future published standard. Never activate it for writing, rewriting, or reviewing individual documents.",
"- **`iso-24495-5` (Document Design, provisional):** Activate when producing complex multi-section documents (reports, specifications, guides, contracts) where layout, visual hierarchy, and navigation aids shape readability.",
"- **`iso-24495-text-audit` (Text Audit):** Never activate automatically. The user invokes it to audit one selected text file or directory.",
"",
],
"skills/iso-24495-1/agents/openai.yaml": [
"interface:",
" display_name: \"ISO 24495-1 Plain Language\"",
" short_description: \"Write so readers can find, understand and act on what they read\"",
" default_prompt: \"Use $iso-24495-1 to hold this answer to plain language: lead with the outcome, keep sentences short, and say what the reader does next.\"",
"",
],
"skills/iso-24495-2/SKILL.md": [
"---",
"name: iso-24495-2",
"description: Sector-specific Plain Language standard for legal communication (ISO 24495-2:2025). Applied during contract drafting, license review, and legal/compliance writing.",
"metadata:",
" version: \"0.7.0\"",
" iso-standard: \"ISO 24495-2:2025\"",
" iso-status: \"published\"",
"---",
"",
"# ISO 24495-2:2025 - Plain Language (Legal Communication)",
"",
"> **Proxy status:** These rules are this project's own proxies for the standard's principles, not its text. Following them is never a claim of ISO conformance.",
"",
"Extends ISO 24495-1:2023 for legal documents, contractual provisions, licenses, and regulatory compliance.",
"",
"## Scope & Execution Boundaries",
"",
"1. **Thinking Block Exemption:**",
" - Internal reasoning and legal analysis within thinking blocks (the `thought` and `thinking` tags) are **100% exempt** from plain language constraints.",
" - Reason exhaustively within thinking blocks. Apply plain language rules strictly to final user-facing legal text.",
"",
"2. **Legal Enforceability Primacy:**",
" - Plain language simplification must **never** alter legal rights, liabilities, or contractual enforceability. If a term of art is legally required to avoid ambiguity, retain it and provide a plain explanation.",
"",
"3. **Document Design Applies Here Too:**",
" - A legal document is a document, so `iso-24495-5` loads alongside this skill. Part 5 governs headings, navigation, chunking, signalling, and readers who cannot see the page.",
" - Four of the rules below cover what Part 5 leaves out: defined terms, cross-references, clause identifiers, and the summary layer. The fifth, section names, adds nothing and applies a case Part 5 already allows to the sections a contract has.",
" - Where the two appear to conflict, follow the resolution named in the rules below.",
"",
"---",
"",
"## Quantitative Rules & Hard Constraints (User-Facing Output)",
"",
"1. **Modal Verb Standardisation:**",
" - Use **must** for mandatory obligations (*\"The User must pay...\"*).",
" - Use **must not** for prohibitions (*\"The User must not copy...\"*).",
" - Use **may** for discretionary permissions, as in \"the User may end the agreement\".",
" - **Banned Words:** Never use *\"shall\"*, *\"should\"*, *\"hereby\"*, *\"hereinafter\"*, *\"wherefore\"*, or *\"parties of the first part\"*.",
"",
"2. **Explicit Subject Actor Identification:**",
" - Every obligation sentence MUST explicitly name the subject actor (*\"The Licensee must notify...\"* rather than *\"Notice must be provided...\"*).",
"",
"3. **Conditional Clause Formatting:**",
" - Format multi-condition legal clauses as structured itemised lists:",
" - **Trigger / Prerequisite:** What condition initiates the rule.",
" - **Obligation / Action:** What action must or may be taken.",
" - **Consequence:** What occurs upon non-compliance.",
"",
"4. **Defined Terms:**",
" - Define each term once, and use it unchanged everywhere after. Two words for one concept invite an argument that they mean two things.",
" - Put the definition where the reader first meets the term. Where a term appears in more than one section, collect the definitions in one section and point the first use at it.",
" - Write a term out in full where the document uses it once, rather than defining it.",
" - Say in words that a term is defined, and where. Capital letters are silent to a listener, so **Confidential Information** on its own tells them nothing.",
"",
"5. **Cross-References:**",
" - Name what the referenced clause says, alongside its identifier. Write *\"the notice deadline in clause 4.2\"* rather than *\"clause 4.2\"*.",
" - Keep that wording identical to the referenced clause's own heading or opening line.",
" - When you point at an obligation, point at the clause carrying it, never at one that only points somewhere else. A first use pointing at the collected definitions is the exception rule 4 requires, because a definition binds nobody.",
"",
"6. **Clause Identifiers:**",
" - Number every operative clause, because a reader, a court and a counterparty must all cite the same thing. An operative clause imposes, permits or prohibits an action. Recitals, definitions and schedules are numbered by the conventions of the document, not by this rule.",
" - Write the identifier into the clause text rather than as list markup. Markdown numbers an ordered list 1, 2, 3, so a compound identifier such as 4.2.1 survives only when it is written in the text.",
" - This is the one place a legal document departs from Part 5's rule that a sequence stays an ordered list.",
" - A clause identifier is neither a heading nor list numbering. So it does not count against Part 5's heading limit, and Part 5's rule on numbering headings does not govern it.",
" - Keep an identifier for the life of the document. An amendment adds a clause, or marks one deleted, and leaves every existing number where it is, because filings, correspondence and other contracts cite those numbers.",
"",
"7. **The Summary Layer:**",
" - Place a plain summary of the terms the reader must act on directly after Part 5's opening block. Give it the overview's own heading, because a summary of what a reader must act on is the conclusion they need before the detail, which is what Part 5 labels. Cover what they must do, what they must pay, when the agreement ends, and how to leave it. A document without one or more of those, such as a privacy policy with no payment, covers the rest. A document with no terms the reader must act on needs no summary of this shape, and Part 5 still decides whether it has an overview.",
" - The summary **must** state that the operative text governs, and **must** name where that text starts. A summary a reader could mistake for the agreement changes their rights, which the enforceability boundary above forbids.",
" - The summary **must not** add an obligation, newly qualify one, or leave a reader believing an obligation is gone. Where the operative text already qualifies a term, state the term together with that qualification, which Part 5 requires the overview to keep. Where stating it would take more words than the clause itself, leave the term out and point to its clause. A pointer keeps the obligation reachable, so it is not a removal.",
" - Map the document onto Part 5's three levels of detail. The summary is the overview, and the operative terms are the main body. Place each schedule by what it holds, because Part 5's optional detail is for what only some readers need. A schedule carrying an obligation, a payment or a limit belongs in the main body with the rest of the operative terms, whichever page it is printed on. Reserve the optional level for a schedule a reader can skip and still comply, such as a list of contacts or a specimen form.",
"",
"8. **Section Names:**",
" - A contract's section names are the reference case Part 5 already allows, and not a new exception. A reader jumps to Payment, Termination or Liability by subject, so each keeps its subject as its name.",
"",
"---",
"",
"## Contrastive Examples",
"",
"### Example 1: Contractual Obligation",
"* ❌ **Not aligned (Archaic Legalese):**",
" ```text",
" The Licensee shall hereinafter hold harmless and indemnify the Licensor",
" from and against any and all claims wherefore notice has not been provided",
" within thirty (30) days.",
" ```",
"* ✅ **ISO 24495-2 Aligned:**",
" > **Indemnification Notice Requirement:**",
" > 1. **Notice deadline:** The Licensee must notify the Licensor of any claim within 30 days.",
" > 2. **Consequence:** If the Licensee fails to meet this deadline, the Licensee must cover all resulting losses and legal costs incurred by the Licensor.",
"",
"### Example 2: The Summary Layer",
"* ❌ **Not aligned (the summary drops conditions in the source clause):**",
" ```text",
" 9.1 The Customer may terminate this Agreement by giving the Supplier at",
" least 30 days' written notice. If the Customer does so, the Supplier",
" must refund to the Customer the fees paid for the part of the term",
" that has not yet run. The refund is calculated pro rata.",
"",
" Summary: You can end the Agreement and get your money back.",
" ```",
"* ✅ **ISO 24495-2 Aligned:**",
" > ## Summary of your main terms",
" >",
" > The operative text starts at clause 9.1 below, and it governs.",
" >",
" > - **Ending the Agreement:** You may end this Agreement by giving the Supplier at least 30 days' written notice.",
" > - **Refund:** If you do, the Supplier must refund you the fees paid for the part of the term that has not yet run, calculated pro rata.",
" >",
" > ```text",
" > 9.1 The Customer may terminate this Agreement by giving the Supplier at",
" > least 30 days' written notice. If the Customer does so, the Supplier",
" > must refund to the Customer the fees paid for the part of the term",
" > that has not yet run. The refund is calculated pro rata.",
" > ```",
"",
"---",
"",
"## Pre-Output Self-Audit Checklist",
"",
"Before outputting legal text, audit against these checks:",
"- [ ] **No legalese:** Are terms like *\"shall\"*, *\"hereinafter\"*, and *\"hereby\"* eliminated?",
"- [ ] **Modal verbs:** Are obligations expressed using only *must*, *must not*, or *may*?",
"- [ ] **Explicit subjects:** Is every obligation attached to a clearly named actor?",
"- [ ] **Structured clauses:** Are complex conditions presented as itemised lists?",
"- [ ] **Legal accuracy:** Is legal enforceability preserved?",
"- [ ] **Defined terms:** Is each term defined once, used unchanged, and reachable from its first use?",
"- [ ] **Cross-references:** Does each name what the clause says, as well as its identifier?",
"- [ ] **Identifiers:** Is every operative clause numbered, with existing numbers untouched by amendment?",
"- [ ] **Summary:** Does it name the governing text, and add, qualify and remove nothing?",
"- [ ] **Section names:** Does each name the subject a reader would look for?",
"- [ ] **Design applied:** Did `iso-24495-5` run over the document as well as this skill?",
"",
],
"skills/iso-24495-2/agents/openai.yaml": [
"interface:",
" display_name: \"ISO 24495-2 Legal Writing\"",
" short_description: \"Plain language for contracts, licences and compliance text\"",
" default_prompt: \"Use $iso-24495-2 when drafting or reviewing a contract, licence, policy or other legal text.\"",
"",
],
"skills/iso-24495-3/SKILL.md": [
"---",
"name: iso-24495-3",
"description: Sector-specific Plain Language standard for science and technical writing (ISO 24495-3:2026). Applied during software documentation, architecture specs, and technical analysis.",
"metadata:",
" version: \"0.7.0\"",
" iso-standard: \"ISO 24495-3:2026\"",
" iso-status: \"published\"",
"---",
"",
"# ISO 24495-3:2026 - Plain Language (Science and Technical Communication)",
"",
"> **Proxy status:** These rules are this project's own proxies for the standard's principles, not its text. Following them is never a claim of ISO conformance.",
"",
"Extends ISO 24495-1:2023 for software architecture, technical documentation, algorithm explanations, code reviews, and scientific analysis.",
"",
"## Scope & Execution Boundaries",
"",
"1. **Thinking Block Exemption:**",
" - Internal architectural analysis, code reasoning, and mental trace blocks (the `thought` and `thinking` tags) are **100% exempt** from plain language constraints.",
" - Reason freely within thinking blocks. Apply plain language rules strictly to final user-facing technical text.",
"",
"2. **Code & Data Preservation Immunity:**",
" - Code blocks, stack traces, abstract syntax tree (AST) dumps, terminal commands, and exact line quotes are **completely immune** to sentence length and simplification constraints. Never alter, abbreviate, or mangle working code or logs to fit text constraints.",
"",
"3. **Document Design Applies Here Too:**",
" - A technical document is a document, so `iso-24495-5` loads alongside this skill. Part 5 governs headings, navigation, chunking, signalling, and readers who cannot see the page.",
" - It loads for a document, not for every explanation. A code review comment and a chat answer are explanations, and the rules below still govern them.",
" - Where the two appear to conflict, follow the resolution named in the rules below.",
"",
"---",
"",
"## Quantitative Rules & Hard Constraints (User-Facing Output)",
"",
"1. **Progressive Disclosure Ordering:**",
" Structure every technical explanation in these stages, in this order:",
" 1. **System Purpose:** High-level operational intent (1 sentence).",
" 2. **Architecture & Data Flow:** Diagram (Mermaid) or summary table. Rule 4 governs the diagram's text alternative, and Part 5 governs the table. Required where the explanation covers how more than one component relates to another. A single mechanism needs none, and neither does a sequence of steps that an ordered list already presents in order. A diagram nobody needs is the decoration Part 5 forbids.",
" 3. **Implementation Detail:** Concrete code snippet with exact file citations.",
"",
" These stages order an explanation, and Part 5's three levels order a document. They are different axes rather than two versions of one, so they do not map one to one. Where the explanation is a document:",
" - The purpose sentence supplies the purpose line of Part 5's opening block, and opens its overview where Part 5 calls for one. The block's title, version and named reader are not its to supply, and Part 5 still requires them of the author. That overview also keeps the conclusion, the action required and any essential qualification, which one sentence does not.",
" - Stages 2 and 3 sit in the main body, in that order.",
" - Part 5's optional detail holds what a reader can skip and still act on. No stage covers it, so nothing is demoted there by default.",
"",
" A stage covers what the explanation contains. A runbook explains what to do and a decision record explains a choice, so neither needs stage 2's diagram of components nor stage 3's code. Omit a stage the explanation has no content for, and keep the order of those it has. They also do not exclude what a genre needs beside them: an incident report's timeline sits with the stages rather than inside one.",
"",
"2. **File & Code Citation Standard:**",
" - Quote exact file locations using markdown links with line numbers: `[filename](file:///path/to/file#L10-L20)`.",
" - Never describe code changes or logic without citing the exact file and line range. This governs an explanation of code. A guide describing what a user does needs no citation.",
"",
"3. **Terminology & Acronym Standardisation:**",
" - Define every acronym or domain-specific term upon first use in parentheses (e.g. *\"Abstract Syntax Tree (AST)\"*).",
" - Use consistent symbol names across text, code snippets, and diagrams.",
"",
"4. **Diagrams and Their Alternatives:**",
" - Give every diagram a text alternative saying what it shows, not what it is. Part 5 requires that of any image carrying meaning. Stage 2 above offers a diagram as one way to meet it, so this rule says where the alternative goes. A summary table is the other way, and Part 5 already governs it.",
" - A Mermaid diagram reaches a listener as its source text, which is not an explanation. So the alternative is prose beside the diagram, never the diagram's own labels.",
"",
"---",
"",
"## Contrastive Examples",
"",
"### Example 1: Concurrency Control Explanation",
"* ❌ **Not aligned (Dense & Abstract):**",
" ```text",
" In order to prevent race conditions during concurrent state mutations",
" within the execution pipeline, a mutex lock mechanism is introduced prior",
" to updating the shared buffer allocation in memory.",
" ```",
"* ✅ **ISO 24495-3 Aligned:**",
" > **System Purpose:**",
" > Acquire a Mutex Lock to prevent data corruption during concurrent writes.",
" > ",
" > **Implementation Detail:**",
" > The locking logic is implemented in [`state_manager.rs:L45-L52`](file:///src/state_manager.rs#L45-L52):",
" > ```rust",
" > let _guard = self.mutex.lock().unwrap();",
" > self.buffer.update(data);",
" > ```",
"",
"---",
"",
"## Pre-Output Self-Audit Checklist",
"",
"Before outputting technical text, audit against these checks:",
"- [ ] **Progressive structure:** Is system purpose stated before architecture and code?",
"- [ ] **Exact citations:** Are code citations backed by `file:///` links and line numbers?",
"- [ ] **Acronym definitions:** Are acronyms and specialized terms defined upon first use?",
"- [ ] **Visual aids:** Does a diagram or table show how components relate, unless an ordered list already presents that relationship as a sequence?",
"- [ ] **Code immunity:** Are code snippets and commands intact and un-mangled?",
"- [ ] **Text alternatives:** Does every diagram carry prose saying what it shows?",
"- [ ] **Layering:** Where the explanation is a document, do the stages sit in Part 5's levels as rule 1 says?",
"- [ ] **Design applied:** Did `iso-24495-5` run over the document as well as this skill?",
"",
],
"skills/iso-24495-3/agents/openai.yaml": [
"interface:",
" display_name: \"ISO 24495-3 Technical Writing\"",
" short_description: \"Plain language for documentation, architecture and code review\"",
" default_prompt: \"Use $iso-24495-3 when writing documentation, an architecture note, or a technical explanation.\"",
"",
],
"skills/iso-24495-4/SKILL.md": [
"---",
"name: iso-24495-4",
"description: Provisional task skill for organisational plain language implementation (based on ISO/CD 24495-4, committee draft). Activates for plain language gap analysis, policy drafting, review workflow design, and organisational readiness for the future published standard. Does not activate for ordinary writing, rewriting, or reviewing of individual documents.",
"metadata:",
" version: \"0.7.0\"",
" iso-standard: \"ISO/CD 24495-4\"",
" iso-status: \"committee-draft\"",
"---",
"",
"# ISO/CD 24495-4 - Plain Language (Organisational Implementation) [PROVISIONAL DRAFT]",
"",
"> **Provisional status:** ISO 24495-4 is a Committee Draft (ISO/CD 24495-4) and is not yet published; its text is not public. This skill is original guidance based on the draft's public scope. It does not reproduce ISO text and its output is never a compliance statement. Expect revision when the standard is published.",
"",
"Turns the agent from a copy editor into an implementation consultant. It assesses an organisation's *capacity to produce* plain language across governance, capability, process, measurement, and culture, rather than the quality of any single text.",
"",
"## Scope & Execution Boundaries",
"",
"1. **Activation Rules:**",
" - **Activate for:** plain language gap analysis, maturity assessment, policy or style guide drafting, review workflow design, training planning, readiness for the future published standard.",
" - **Never activate for:** writing, rewriting, summarising, or reviewing an individual document. Those tasks belong to `iso-24495-1`, `-2`, `-3`, and `-5`.",
"",
"2. **Confirmation Before Sweeps:**",
" - Both audit scripts read many files. State which directory will be swept and get the user's confirmation before running either.",
"",
"3. **Evidence Primacy:**",
" - Never assert a maturity level without evidence: a found artefact, a confirmed answer, or a measured count. Absent evidence scores as absent.",
"",
"## The Audit Workflow",
"",
"Run the four steps in order. Each feeds the next.",
"",
"1. **Sweep for process artefacts (primary):**",
" - Run `bun scripts/audit-evidence-cli.ts <workspace-dir> --json evidence.json`.",
" - This detects the *system*: policy, review workflow, automated checks, training, glossary. It reads presence only; you evaluate the quality of what it finds.",
"2. **Audit the document corpus (secondary):**",
" - Run `bun scripts/audit-corpus-cli.ts <corpus-dir> --json findings.json`.",
" - Output feeds the **Measurement dimension only**, as evidence of what the system produces. Text quality alone never raises a maturity level: excellent text can come from one unsupported expert, and flawed text can coexist with a strong process that is catching it.",
"3. **Interview the human (3 to 5 questions maximum):**",
" - Use `references/interview-guide.md`. Ask only what the file system cannot show (leadership, culture, training delivery). Record answers in the `answers.json` structure and cite evidence for each `true`.",
" - Score with `bun scripts/score-maturity-cli.ts answers.json --json maturity.json`. Scoring is deterministic so levels cannot drift between sessions.",
"4. **Generate the gap report:**",
" - Run `bun scripts/generate-report-cli.ts findings.json evidence.json maturity.json --state <dir>/state.json --out gap-report.md`.",
" - State is append-only; successive audits produce a trend table that proves or disproves progress. Store `state.json` in the organisation's repository, not in the skill directory (installed skills may be read-only).",
"",
"## Quantitative Rules & Hard Constraints",
"",
"1. **Proxies, Not Compliance:** Corpus metrics (sentence length, paragraph length, legalese, heading depth) are mechanical proxies. Never present them, or this report, as ISO compliance or certification.",
"2. **Interview Cap:** Ask the human at most 5 questions per audit. Infer everything else from artefacts.",
"3. **Ranked Actions:** Every gap in the report gets a recommended action, ranked by reader impact against effort, tied to the criterion it unblocks.",
"4. **Language Boundary:** The text heuristics are English-centric. For non-English corpora, skip step 2 and say so in the report.",
"",
"## Contrastive Examples",
"",
"### Example 1: Reporting a Gap",
"* ❌ **Not aligned (Vague, Unevidenced):**",
" > \"The organisation's culture around plain language seems weak and should be improved.\"",
"* ✅ **ISO/CD 24495-4 (Draft) Aligned:**",
" > **Culture: Level 1.** Leadership is aware of the policy, confirmed in interview, but does not champion it. No leader has communicated it in the last year, and no feedback loop exists. **Action (unblocks `leadership-champions`):** the policy owner asks one executive sponsor to open the next all-hands with a plain language example.",
"",
"## Pre-Output Self-Audit Checklist",
"",
"Before delivering a gap report, audit against these checks:",
"- [ ] **Correct activation:** Was this an implementation task, not a writing task?",
"- [ ] **Sweep confirmed:** Did the user approve each directory sweep?",
"- [ ] **Evidence cited:** Does every maturity level and `true` answer cite an artefact, answer, or count?",
"- [ ] **Proxies labelled:** Are corpus metrics presented as proxies feeding Measurement only?",
"- [ ] **State saved:** Was `state.json` updated so the next audit can show a trend?",
"- [ ] **Provisional stated:** Does the report declare the committee-draft basis and its limitations?",
"",
],
"skills/iso-24495-4/agents/openai.yaml": [
"interface:",
" display_name: \"ISO 24495-4 Organisational Implementation\"",
" short_description: \"Plain language gap analysis, policy and review workflows (provisional)\"",
" default_prompt: \"Use $iso-24495-4 for organisational plain language work: gap analysis, policy drafting, or review workflow design.\"",
"",
],
"skills/iso-24495-4/assets/gap-report-template.md": [
"# Plain Language Gap Analysis - {{organisation}}",
"",
"> Provisional: this analysis is based on the public scope of ISO/CD 24495-4 (committee draft, unpublished). It is not a compliance statement and confers no certification. Audit date: {{date}}.",
"",
"## Summary",
"",
"{{Two to three sentences: overall maturity, the weakest dimension, and the single highest-impact action.}}",
"",
"## Maturity",
"",
"{{Table from scripts/score-maturity-cli.ts: dimension, level, blocking criteria.}}",
"",
"## Evidence",
"",
"{{Table from scripts/audit-evidence-cli.ts: category, found, paths. Note quality observations per artefact below the table.}}",
"",
"## Corpus findings",
"",
"{{Table from scripts/audit-corpus-cli.ts. State the corpus scope (directories, file count) and that these metrics are proxies feeding the Measurement dimension only.}}",
"",
"## Trend",
"",
"{{Only when state.json holds two or more snapshots: table of audit date, overall level, total violations.}}",
"",
"## Recommended actions",
"",
"{{Ranked list. Each action names the criterion it unblocks, the owner, and the expected reader impact.}}",
"",
"## Limitations",
"",
"- The underlying standard is an unpublished committee draft; criteria may change.",
"- Text heuristics are English-centric and approximate.",
"- Maturity levels reflect the evidence supplied; absent evidence scores as absent.",
"- A human reviewer must validate this report before the organisation acts on it.",
"",
],
"skills/iso-24495-4/references/evidence-map.md": [
"# Evidence Map",
"",
"What `scripts/audit-evidence-cli.ts` detects, and what its findings can and cannot support. The sweep records presence and paths only; judging artefact quality is the agent's job, with the human.",
"",
"| Category | Detected by | Supports criteria | Does not prove |",
"|----------|-------------|-------------------|----------------|",
"| `policy` | Filenames matching plain-language-policy or style-guide | `policy-documented`, `style-guide-available` | That anyone follows it (`owner-accountable` needs a name; usage needs interview) |",
"| `review-workflow` | Pull request templates; review process/workflow/checklist documents | `review-step-exists` | That the step runs on every document (`signoff-gates` needs a gate definition) |",
"| `automated-checks` | Workflow files invoking prose linters (vale, textlint); linter configs | `checks-in-workflow` | That checks block merges, or cover all document types |",
"| `training` | Files under `training/` or `onboarding/` directories | `training-delivered` (partially) | That training actually ran; confirm delivery and dates in interview |",
"| `glossary` | Filenames matching glossary or terminology | Consistency practice (supports `style-guide-available`) | That terms are applied consistently in output |",
"",
"A `found: false` in one workspace is not proof the artefact does not exist elsewhere in the organisation. Ask before concluding absence, and widen the sweep to other repositories or shared drives where the user points to them.",
"",
],
"skills/iso-24495-4/references/interview-guide.md": [
"# Interview Guide",
"",
"Ask at most 5 questions per audit. Ask only what the file system cannot show. Before asking, fill every criterion you can from the evidence sweep, then pick the questions that unblock the most uncertain dimensions.",
"",
"## Question bank",
"",
"Pick 3 to 5. One question per line; ask them plainly.",
"",
"1. **Culture / leadership-aware, leadership-champions:** \"When did a leader last mention plain language to the wider organisation, and in what form?\"",
"2. **Governance / owner-accountable, resourced-mandated:** \"Who is personally accountable for plain language here, and what time or budget do they get for it?\"",
"3. **Capability / training-delivered:** \"Has anyone been trained in plain language in the last year? Who, and by whom?\"",
"4. **Measurement / user-testing:** \"Have real readers ever been watched or asked while using one of your documents? What happened to the results?\"",
"5. **Culture / feedback-loops:** \"If a reader finds a document confusing today, what do they do, and who acts on it?\"",
"6. **Process / signoff-gates:** \"Can a public document ship without anyone checking its clarity? What stops it?\"",
"",
"## Recording answers",
"",
"- Record each answer as `true` only with evidence: a named artefact, date, person, or example.",
"- An enthusiastic \"yes\" without evidence records as `false` with a note.",
"- Write results into the `answers.json` structure (see `tests/fixtures/answers.sample.json` for the shape) and score with `scripts/score-maturity-cli.ts`.",
"",
],
"skills/iso-24495-4/references/maturity-model.md": [
"# Maturity Model - Organisational Plain Language",
"",
"Five dimensions, levels 0 to 4. A dimension holds a level only when every criterion at that level and below is met. Overall maturity is the weakest dimension. This table mirrors `scripts/lib/types.ts`; change both together.",
"",
"| Level | Name | Meaning |",
"|-------|------|---------|",
"| 0 | Ad hoc | No defined approach; output depends on individuals. |",
"| 1 | Defined | Foundations exist on paper. |",
"| 2 | Implemented | The foundations are in active use. |",
"| 3 | Managed | Use is systematic and gated. |",
"| 4 | Sustained | Measured, championed, and continuously improved. |",
"",
"## Criteria and the evidence an auditor requests",
"",
"| Dimension | Level 1 | Level 2 | Level 3 | Level 4 |",
"|-----------|---------|---------|---------|---------|",
"| **Governance** | `policy-documented`: a written plain language policy exists. *Evidence: the policy file.* | `owner-accountable`: a named person owns it. *Evidence: name in the policy or org chart.* | `resourced-mandated`: time and budget are allocated. *Evidence: role descriptions, budget line.* | `executive-review-cycle`: leadership reviews it on a schedule. *Evidence: review minutes.* |",
"| **Capability** | `style-guide-available`: writers can reach a style guide. *Evidence: the guide and its location.* | `training-delivered`: training has run. *Evidence: materials and attendance.* | `competence-maintained`: refreshers and onboarding cover it. *Evidence: onboarding checklist.* | `roles-embedded`: plain language duties sit in job roles. *Evidence: role descriptions.* |",
"| **Process** | `review-step-exists`: documents get a review step. *Evidence: review template or workflow doc.* | `checks-in-workflow`: automated or checklist checks run in the workflow. *Evidence: CI config, checklist.* | `signoff-gates`: priority documents cannot ship without sign-off. *Evidence: gate definition.* | `all-document-types-covered`: the process covers every public document type. *Evidence: coverage list.* |",
"| **Measurement** | `corpus-baseline-taken`: a corpus audit baseline exists. *Evidence: `state.json` snapshot.* | `regular-sampling`: audits repeat on a schedule. *Evidence: two or more snapshots.* | `user-testing`: real readers test key documents. *Evidence: test reports.* | `metrics-drive-decisions`: results change practice. *Evidence: decisions citing metrics.* |",
"| **Culture** | `leadership-aware`: leaders know the policy exists. *Evidence: interview answer.* | `leadership-champions`: leaders visibly promote it. *Evidence: communications.* | `feedback-loops`: readers can report unclear text and someone acts. *Evidence: feedback channel and responses.* | `improvement-cycles`: lessons feed back into policy and training. *Evidence: change log.* |",
"",
],
"skills/iso-24495-5/SKILL.md": [
"---",
"name: iso-24495-5",
"description: Provisional sector-specific Plain Language standard for document design (based on ISO/WD 24495-5, under development). Applied when structuring complex documents so readers can find and navigate content through layout, visual hierarchy, and navigation aids.",
"metadata:",
" version: \"0.7.0\"",
" iso-standard: \"ISO/WD 24495-5\"",
" iso-status: \"working-draft\"",
"---",
"",
"# ISO/WD 24495-5 - Plain Language (Document Design) [PROVISIONAL DRAFT]",
"",
"> **Provisional status:** ISO 24495-5 is a Working Draft (ISO/WD 24495-5) and is not yet published. This skill is original guidance based on the draft's public scope and established information design practice. It does not reproduce ISO text. Expect revision when the standard is published.",
"",
"> **Sources:** several rules here paraphrase the Document design pattern library, version 0.6, June 2025. That library is by Waller, van der Waarde, Schriver, Slabbert, Cheek and Linsky, for the International Plain Language Federation. The wording in this skill is ours, and no substantial wording is copied from it. Read the [Document design pattern library at the International Plain Language Federation](https://www.iplfederation.org/wp-content/uploads/2025/06/ISOpatternlibrary06.pdf) for the original.",
"",
"Extends ISO 24495-1:2023 for the structural design of complex documents: reports, specifications, guides, contracts presented as documents, and long-form technical or health information. Design works together with linguistic cues to help readers find and navigate a document's structure and content.",
"",
"**Design for readers who are not looking at the page.** The intended readers include everyone who uses the document. Some see it, some hear it through a screen reader, and some read it by touch.",
"",
"A listener has no visual hierarchy. Their structure is the heading tree, the link text and the reading order. Every rule below is written to hold when the document is heard.",
"",
"## Scope & Execution Boundaries",
"",
"1. **Thinking Block Exemption:**",
" - Internal layout planning and structural reasoning within thinking blocks (the `thought` and `thinking` tags) are **100% exempt** from these constraints.",
" - Plan freely within thinking blocks. Apply document design rules strictly to final user-facing documents.",
"",
"2. **Design as Engineering, Not Decoration:**",
" - Base every design decision on a documented reader need (finding, navigating, comparing, acting). Never add visual elements for aesthetic effect alone.",
"",
"3. **Content Primacy:**",
" - Document design must **never** cut or distort content to fit a layout. Accuracy and completeness supersede visual tidiness.",
"",
"---",
"",
"## Required Templates",
"",
"Read the matching template before writing any of these document types:",
"",
"- **Architecture decision record (ADR):** Read the template file at `assets/adr-template.md`.",
"- **Runbook:** Read the template file at `assets/runbook-template.md`.",
"- **Design document:** Read the template file at `assets/design-doc-template.md`.",
"",
"## Restructure an Existing Document",
"",
"When asked to restructure an existing document:",
"",
"1. Identify the reader tasks, current hierarchy, and navigation needs.",
"2. Preserve every prose passage and content item.",
"3. Change headings, list types, table structure and visual formatting. You may also move a whole sentence or block, unchanged. Move it only where its dependencies, its order against neighbouring steps, and the claim it qualifies all survive.",
"4. Build the opening block, the overview and the signposts from sentences the document already holds, or from wording the author gives you in the request. Promote a sentence only when it states the field directly, and stays both true and complete enough for that field once away from the paragraph it came from. Where the author's wording contradicts the document, promote neither and report the mismatch.",
"5. Where nothing serves, leave a marked slot such as `[Author needed: purpose]` and report it as a gap. This covers the overview's content as much as its label. Never supply the missing wording yourself.",
"6. Check the result against the hierarchy, navigation, structure, and signalling rules below.",
"",
"Do not rewrite prose, change tone, or remove content. Those changes belong to Parts 1 to 3, and so does rewording a sentence to make it fit a slot. A wrong purpose sends a reader confidently in the wrong direction, which is worse than no purpose at all.",
"",
"---",
"",
"## Quantitative Rules & Hard Constraints (User-Facing Documents)",
"",
"1. **Visual Hierarchy Limits:**",
" - Use at most **3 heading levels** below the document title. Flatten deeper nesting into lists or tables.",
" - Make headings state the section's message or task, not just its topic (*\"Install the dependencies\"* rather than *\"Dependencies\"*).",
" - Two exceptions here, one override in rule 8, and no others. A document type with a published structure keeps that structure's section names, as a decision record keeps Context and Decision.",
" - A reference section a reader jumps to by subject keeps the subject as its name, as a specification keeps Data Model. A section read in sequence gets a message or a task.",
" - Reject a heading that jokes, puns or plays with words. Reject one built on a term the document has not yet explained, because a reader skimming meets the heading first.",
"",
"2. **Navigation Aids:**",
" - Add a table of contents or link list to any document with **6 or more sections**.",
" - Keep heading wording identical between the table of contents and the section it points to.",
" - Number headings when a reader must cite one by its identifier, and never below the depth limit above.",
"",
"3. **Chunking & White Space:**",
" - Present one idea per visual chunk (paragraph, list, table, or callout). Separate chunks with blank lines.",
" - Never run two unrelated topics together in one paragraph or one table.",
"",
"4. **Choosing the Right Structure:**",
" - **Comparisons:** Use a table when readers must compare 2 or more items across shared attributes. Name the narrowest presentation the table must survive, then read it back at that width. Where nobody has named one, use repeated labelled records instead of a table, rather than shipping both.",
" - **Sequences:** Use a numbered list for steps that must happen in order. Keep it an ordered list rather than numbers typed into a paragraph, so the sequence survives when the document is heard. A legal document's clause identifiers are the one exception, because no ordered list renders a compound identifier such as 4.2.1, and `iso-24495-2` governs them.",
" - **Options and collections:** Use a bulleted list for unordered sets of 3 or more items. Keep each bullet to one paragraph carrying one idea, and nest bulleted lists no deeper than 2 levels. Promote longer material to a subsection.",
" - **Branching routes:** When a procedure forks, use a decision table or a labelled set of conditions rather than one numbered list. A decision table with labelled routes is already the written form. Add prose only where the routes are drawn as a picture.",
" - **Warnings and conditions:** Reserve a callout for a warning or condition that changes what the reader does. Merge adjacent callouts serving one purpose, and give each a word naming what it is.",
"",
"5. **Consistent Visual Signalling:**",
" - Give each visual device (bold, italics, blockquotes, code formatting, icons) **one meaning** per document and apply it consistently.",
" - Never use the same device for two different meanings, or two devices for the same meaning. A text alternative is exempt only where the original is a picture or a diagram, or is not exposed to a screen reader. A table is excluded only where its headers identify every value and its reading order keeps the comparison intact. Where they do not, a concise equivalent is allowed.",
" - **Never let a visual device carry meaning on its own.** Bold, colour, an icon and a position on the page are all silent to a listener. State the meaning in words as well. \"Required fields are marked in red\" fails; \"Required fields are marked with the word required\" works.",
"",
"6. **Reaching Readers Who Cannot See the Page:**",
" - **Link text names its destination.** A screen reader can list every link in a document, read aloud without the sentence around it. \"Click here\" and a bare web address tell that reader nothing.",
" - **Every image that carries meaning has alternative text** describing what it shows, not what it is. An image that carries no meaning is decorative and may say so.",
" - **Tables carry a header row**, because a listener hears each cell announced against its column name.",
" - **The reading order is the document order.** A sidebar or a floating callout only makes sense out of sequence, so give each one its own heading in the flow.",
"",
"7. **The Opening Block:**",
" - Open every document with its title, a one-line statement of its purpose, and its version or date.",
" - Name the intended reader in that block. Part 1 decides who that reader is; this rule decides where the answer appears.",
" - Give each field its minimum. Purpose states the reader's task and the document's scope. The reader line names the primary audience. The referral names the alternative and when to use it.",
" - Where the document cites this skill or ISO 24495-5, say in the document that the standard is an unpublished draft.",
"",
"8. **Layering the Detail:**",
" - Label the overview explicitly in any document with 6 or more sections, or one whose conclusion readers need before the detail. A reader who stops at the overview then knows what they hold.",
" - That label is the section's heading, and it names the section rather than its message. This rule overrides the heading rule for that one heading, and for no other. It keeps the document's conclusion, the action required, and any essential qualification.",
" - Give that label a heading, never bold text or a visual treatment alone. A listener reaches it through the heading list or not at all.",
" - Move detail that only some readers need into footnotes, an appendix, or a collapsible block, and keep it reachable from the main path.",
" - Use at most **3 levels**: overview, main body, and optional detail. Part 3 governs a technical explanation's stages, and states where each one lands in these levels.",
"",
"9. **Readers Who Have the Wrong Document:**",
" - Tell a reader who needs something else where to go. Link the related documents, the other language versions, or a person to ask.",
" - Put that signpost where a reader will look on realising the document is wrong. Near the top works, or at the end of the opening section.",
" - Leave it out when no alternative exists, rather than shipping an empty heading.",
"",
"---",
"",
"## Contrastive Examples",
"",
"### Example 1: Structuring Comparative Information",
"* ❌ **Not aligned (Buried in Prose):**",
" ```text",
" The Basic plan costs £5 per month and includes 10 GB of storage but no",
" priority support, whereas the Pro plan is £15 per month with 100 GB and",
" priority support, and the Team plan, at £40 per month, offers 1 TB,",
" priority support, and audit logs.",
" ```",
"* ✅ **ISO 24495-5 (Draft) Aligned:**",
" > Choose a plan based on storage and support needs:",
" >",
" > | Plan | Price / month | Storage | Priority support | Audit logs |",
" > |------|---------------|---------|------------------|------------|",
" > | Basic | £5 | 10 GB | No | No |",
" > | Pro | £15 | 100 GB | Yes | No |",
" > | Team | £40 | 1 TB | Yes | Yes |",
"",
"---",
"",
"## Pre-Output Self-Audit Checklist",
"",
"Before outputting a complex document, audit against these checks:",
"- [ ] **Hierarchy depth:** Are there 3 or fewer heading levels below the title?",
"- [ ] **Heading quality:** Does each heading state its section's message, or a name its genre expects, free of wordplay and of terms not yet explained?",
"- [ ] **Navigation:** Does a document with 6 or more sections carry a table of contents worded identically to its headings?",
"- [ ] **Numbering:** Are headings numbered only where a reader must cite one by its identifier?",
"- [ ] **Chunking:** Does each chunk carry one idea, separated from the next by a blank line?",
"- [ ] **Structure fit:** Are sequences in ordered lists, sets in bullets, and forks in a decision table or labelled conditions, with a legal document's clause identifiers exempt?",
"- [ ] **Comparisons:** Is the table tested at a named target width, or are labelled records used because no width is named?",
"- [ ] **Restraint:** Is every bulleted item one paragraph on one idea, nested no deeper than 2 levels, with longer material promoted to a subsection?",
"- [ ] **Callouts:** Does each change what the reader does, with adjacent ones merged and each named in a word?",
"- [ ] **Signal consistency:** Does each device carry one meaning, no two devices carry the same meaning, and no meaning ride on a device alone?",
"- [ ] **Alternatives:** Is a text alternative present only beside a picture or diagram, or beside a table whose headers miss values or whose order breaks the comparison?",
"- [ ] **Links and images:** Does link text name its destination, does a meaningful image say what it shows, and is a decorative one marked as decorative?",
"- [ ] **Tables heard:** Does every table carry a header row, with headers that identify each value beneath them?",
"- [ ] **Reading order:** Does document order match reading order, with each sidebar and displaced callout given its own heading?",
"- [ ] **Opening block:** Does the document open with its title, a one-line purpose naming the reader's task and scope, the primary audience, and a version or date?",
"- [ ] **Overview contents:** Where needed, does it keep the conclusion, the required action and every essential qualification?",
"- [ ] **Overview label and detail:** Is the label a heading rather than bold text alone, and has the detail moved to footnotes, an appendix or a collapsible block?",
"- [ ] **Levels:** Are there 3 or fewer levels of detail, and is the optional detail still reachable?",
"- [ ] **Signposting:** Is the referral near the top or ending the opening section, naming its destination and when to use it, and absent where nothing else exists?",
"- [ ] **Preserved:** On a restructure, was every prose passage and content item kept, with no prose rewritten and no tone changed?",
"- [ ] **Safe moves:** Did every moved sentence or block keep its dependencies, its order against neighbouring steps, and the claim it qualifies?",
"- [ ] **Never invented:** Did every promoted sentence come unchanged from the document or the author, state its field directly, stay true and complete, with mismatches reported and gaps marked?",
"- [ ] **Content primacy:** Did accuracy and completeness survive every structural choice, with nothing cut or distorted to fit a layout?",
"- [ ] **Evidence over aesthetics:** Does every design element serve a reader need?",
"- [ ] **Provisional label:** Where the document cites Part 5, does it say the standard is an unpublished draft?",
"",
],
"skills/iso-24495-5/agents/openai.yaml": [
"interface:",
" display_name: \"ISO 24495-5 Document Design\"",
" short_description: \"Structure long documents so readers can navigate them (provisional)\"",
" default_prompt: \"Use $iso-24495-5 when structuring a report, specification or guide, including for readers who cannot see the page.\"",
"",
],
"skills/iso-24495-5/assets/adr-template.md": [
"# [Decision Title]",
"",
"- **Purpose:** [What the reader can decide or do with this record, and what it covers, in one sentence.]",
"- **For:** [Who needs this decision, and who must act on it.]",
"- **Status:** [Proposed or accepted. Where deprecated or superseded, name the decision that replaces this one.]",
"- **Version:** [Version or date.]",
"- **Instead of this:** [Link the decision that may suit the reader better and say when to read it, or delete this line.]",
"",
"[Context, Decision and Consequences keep the names readers look for, from Michael Nygard's Documenting Architecture Decisions, 2011. The options heading is this template's own addition, so it states its message.]",
"",
"## Context",
"",
"[One paragraph describing the problem or driving force.]",
"",
"## What each option offers and costs",
"",
"[Name the narrowest width this table must survive, then read it back at that width. Where no width is known, use labelled records instead.]",
"",
"| Option | Pros | Cons | Estimated effort |",
"| :--- | :--- | :--- | :--- |",
"| **[Option 1]** | [Advantage] | [Disadvantage] | [Estimate] |",
"| **[Option 2]** | [Advantage] | [Disadvantage] | [Estimate] |",
"",
"## Decision",
"",
"[State the chosen option and the deciding factor.]",
"",
"## Consequences",
"",
"- [Impact 1]",
"- [Impact 2]",
"",
],
"skills/iso-24495-5/assets/design-doc-template.md": [
"# [Project Name] Design Document",
"",
"- **Purpose:** [What the reader can build or review from this, and what it covers, in one sentence.]",
"- **For:** [Who this design is written for.]",
"- **Version:** [Version or date.]",
"- **Instead of this:** [Link the design that may suit the reader better and say when to read it, or delete this line.]",
"",
"## Contents",
"",
"[Reviewers cite these sections by number, which is why they are numbered. Where nobody cites yours, delete the numbers from the headings and from this contents list together.]",
"",
"- [1. Summary](#1-summary)",
"- [2. System Architecture](#2-system-architecture)",
"- [3. Data Model](#3-data-model)",
"- [4. API Design](#4-api-design)",
"- [5. Security Model](#5-security-model)",
"- [6. Deployment Plan](#6-deployment-plan)",
"",
"## 1. Summary",
"",
"[Summarise the reader need, the proposed design and the expected outcome. Say what the reader must do next. Name any condition that changes the decision, and any qualification a reader must respect, whether legal, financial or an approval.]",
"",
"## 2. System Architecture",
"",
"### 2.1. What each component is responsible for",
"",
"[Insert a diagram with a text alternative, or a summary table naming each component and its responsibility.]",
"",
"### 2.2. How a request flows through the system",
"",
"[Describe the main request and response flow.]",
"",
"#### 2.2.1. How a sign-in is checked",
"",
"[Describe sign-in, token validation, and failure handling.]",
"",
"## 3. Data Model",
"",
"### 3.1. Entities and Relationships",
"",
"[Name the narrowest width each table must survive, then read them back at that width. Where no width is known, use labelled records instead.]",
"",
"| Entity | Purpose | Relationships |",
"| :--- | :--- | :--- |",
"| **[Entity]** | [Purpose] | [Related entities] |",
"",
"### 3.2. How data enters, changes and leaves",
"",
"[Describe how data enters, changes, persists, and leaves the system.]",
"",
"## 4. API Design",
"",
"### 4.1. Endpoints",
"",
"| Method | Path | Purpose | Request | Response |",
"| :--- | :--- | :--- | :--- | :--- |",
"| `[METHOD]` | `[path]` | [Purpose] | [Request shape] | [Response shape] |",
"",
"### 4.2. Error Handling",
"",
"[Define error categories, response shapes, and retry behaviour.]",
"",
"## 5. Security Model",
"",
"### 5.1. Threats and Controls",
"",
"| Threat | Control | Residual risk |",
"| :--- | :--- | :--- |",
"| **[Threat]** | [Control] | [Residual risk] |",
"",
"### 5.2. Access Control",
"",
"[Define roles, permissions, and enforcement points.]",
"",
"## 6. Deployment Plan",
"",
"### 6.1. Environments",
"",
"[Describe each environment and its release criteria.]",
"",
"### 6.2. How the change ships and how it comes back",
"",
"1. [Prepare and verify the release.]",
"2. [Deploy the change in controlled stages.]",
"3. [Check the release against the criteria in 6.1.]",
"",
"| Check result | What to do |",
"| :--- | :--- |",
"| **[Criteria met]** | [Finish the release and record it.] |",
"| **[Criteria not met]** | [Follow the rollback procedure.] |",
"",
],
"skills/iso-24495-5/assets/runbook-template.md": [
"# [Task Title]",
"",
"- **Purpose:** [What the reader will have done by the end, and what the task covers, in one sentence.]",
"- **For:** [Who runs this task, and when.]",
"- **Version:** [Version or date.]",
"- **Instead of this:** [Link the runbook that may suit the reader better and say when to use it, or delete this line.]",
"",
"## Check these before you start",
"",
"- [ ] [Requirement 1]",
"- [ ] [Requirement 2]",
"",
"> [!CAUTION]",
"> [Critical risks or conditions, before any step runs.]",
"",
"## Run these steps in order",
"",
"1. [First action]",
"2. [Second action]",
" > [!NOTE]",
" > [Expected output for step 2. Where it differs, stop and do not run step 3.]",
"3. [Third action]",
"",
"## Confirm the task worked",
"",
"- Run `[command]` and confirm the output contains `[expected state]`.",
"",
],
"skills/iso-24495-code/SKILL.md": [
"---",
"name: iso-24495-code",
"description: \"Plain language applied to source code (ISO 24495-1:2023 principles). Governs the parts of code a person reads: the order units appear in, their names, comments, and error messages. Applied when writing or restructuring code, not when explaining it.\"",
"metadata:",
" version: \"0.7.0\"",
" iso-standard: \"ISO 24495-1:2023\"",
" iso-status: \"published, applied by analogy to source code\"",
"---",
"",
"# Plain language in code",
"",
"Extends ISO 24495-1 to source code. Code is read far more often than it is written, so the person reading it is the reader the standard is about.",
"",
"**Scope**. This skill governs what a reader reads: the order units appear in, what they are called, what the comments say, and what an error tells the person who hits it.",
"",
"It does not govern correctness, performance, or system design. It does govern local organisation, in rules 1 and 2, because where a unit sits and how far it reaches decide what a reader must hold in their head. For maintainability weaknesses such as complexity and dead code, use a code quality skill built on ISO/IEC 5055.",
"",
"**This is an interpretation of ISO 24495-1 applied by analogy, not a conformance claim.**",
"",
"## The four principles, in code",
"",
"| Principle | In prose | In code |",
"|---|---|---|",
"| Findable | The reader can find what they need | The public entry point appears first |",
"| Understandable | The reader understands it | Names say what the thing is, in the reader's words |",
"| Relevant | The reader gets what they need | A comment says why; interface documentation says what |",
"| Usable | The reader can act on it | An error names the problem and shows a safe value |",
"",
"## Rules",
"",
"### 1. Front-load the main path",
"",
"**Put the public entry point at the top of the file**, before the helpers it calls. A reader opening the file meets the thing it does, then the detail, in that order. This is the code form of leading with the outcome.",
"",
"Where a language forces declarations before use, put a short delegating entry point first and the implementation below it.",
"",
"> Measured on 30 generated implementations of one specification. Without this rule the public function landed anywhere in the file, and in half the files it was the last thing in it.",
"> With the rule it sat in the first fifth of the file every time.",
">",
"> The measure was chosen after those runs rather than before them, and the effect appeared in one model family but not in the two others tested. Treat it as a hypothesis with a clean separation, not a settled result.",
"",
"### 2. One job per unit",
"",
"A function does one thing that its name describes. **A name needing \"and\" is a prompt to look, not an instruction to split.** Some operations are genuinely single and named for a pair, as `compareAndSwap` is, and splitting those breaks them.",
"",
"Helpers belong at the top level or as members of a class, rather than buried as closures inside the function they serve. A reader cannot reach a closure without reading its container first.",
"",
"### 3. Name for the reader",
"",
"- A name says what the thing **is** or **does**, in the vocabulary of someone who knows the domain but not this file.",
"- **Use one name for one concept throughout.** If it is a `token` here it is not a `lexeme` three functions later. Elegant variation confuses code exactly as it confuses prose.",
"- Prefer a longer name that reads to a shorter one that must be decoded. `remainingBudget` beats `rb`.",
"",
"### 4. A comment says why; interface documentation says what a caller needs",
"",
"A comment earns its place when it records something a reader cannot recover from the code: a reason, a constraint, a rejected alternative, a bug it guards against.",
"",
"**Delete a comment that merely restates the line beneath it**, and delete commented-out code.",
"",
"This is not a rule against documentation. An interface comment tells a caller what a function returns, when it returns nothing, and what it throws. That is the reader's work being done for them, so it belongs there even when the body makes it obvious.",
"",
"### 5. An error message serves the person who hits it",
"",
"An error names the problem, shows a value it is safe to show, and where it helps, says what to do instead. Write it in the words its reader would use, so it can be acted on without opening the source.",
"",
"**Never put a secret in an error.** A credential, token, key, password, session identifier or personal detail must not appear in a message, because messages reach logs, telemetry and screens.",
"Name the field and describe the fault instead: `API token rejected: expected 32 characters, got 8`.",
"Where you cannot show a value safely, show its shape.",
"",
"**A value on this path has just failed validation, so its contents are unknown.** Naming the field does not make them safe: whatever the caller passed is what reaches the log.",
"Report the format you expected and the shape of what arrived, never the value itself.",
"Read a length only once you know the value is a string, because any other value can carry a `length` property holding anything at all.",
"",
"```",
"Bad: throw new Error(\"invalid input\")",
"Good: if (typeof duration !== \"string\") {",
" throw new TypeError(`Duration must be a string; got a value of type ${typeof duration}`)",
" }",
" throw new TypeError(",
" `Duration must be a number followed by ms, s, m, h or d; got ${duration.length} characters`)",
"Good: if (typeof token !== \"string\") {",
" throw new TypeError(`API token must be a string; got a value of type ${typeof token}`)",
" }",
" throw new Error(`API token rejected: expected 32 characters, got ${token.length}`)",
"```",
"",
"Quote a value only where you control it, such as one you have already matched against a fixed set. Then the set, not the caller, decides what can appear.",
"",
"### 6. Prefer the plain construction",
"",
"Where two constructions are equally correct, use the one a competent reader understands without pausing. Cleverness that needs a comment to explain it has already failed.",
"",
"## What this skill does not do",
"",
"- It does not require comments. A file with no comments and clear names is fine.",
"- It does not set a line count for a function. Use `iso-5055-code-quality` for size and complexity thresholds, which are measurable.",
"- It does not apply to generated code, vendored code, or code whose layout a formatter owns.",
"",
"## Applying it to existing code",
"",
"Change the reading order and the language. Do not restructure behaviour in the same pass, and never move code and change it at once, because the diff stops being reviewable.",
"",
],
"skills/iso-24495-code/agents/openai.yaml": [
"interface:",
" display_name: \"ISO 24495 Plain Language in Code\"",
" short_description: \"Write code a person can read: entry point first, names, comments, error messages\"",
" default_prompt: \"Use $iso-24495-code when writing or restructuring source, so the public entry point comes first and the names, comments and error messages serve the reader.\"",
"",
],
"skills/iso-24495-text-audit/SKILL.md": [
"---",
"name: iso-24495-text-audit",
"description: Audit user-selected Markdown or text files for deterministic plain-language findings. Use only when the user explicitly invokes this skill.",
"disable-model-invocation: true",
"argument-hint: \"[file-or-directory]\"",
"metadata:",
" version: \"0.7.0\"",
"---",
"",
"# ISO 24495 Text Audit",
"",
"Audit only the path the user selects. Report mechanical findings so the user can decide whether the text suits its readers and purpose.",
"",
"## Language and input scope",
"",
"The audit is written for English and supports English only. The skills and output style are instructions a model interprets, so they are not limited to English in the same way.",
"",
"Its word rules match English words and phrases: `legalese`, `doublet`, `wordy-phrase`, `filler-opening`, `complex-word`, `double-negative`, and the phrases `link-text` looks for. The `filler-opening` rule checks only the opening prose. The `link-text` rule also flags empty labels and labels that are bare web addresses.",
"",
"Five word rules read headings as well as prose: `legalese`, `doublet`, `wordy-phrase`, `complex-word`, and `double-negative`. The rules about sentences and paragraphs read prose only, because a heading is not a sentence.",
"",
"The `sentence-length` and `sentence-average` rules count words separated by whitespace, including spaces and line breaks, and use English benchmarks. The `paragraph-length` rule counts sentences, with a limit of five.",
"",
"The `prose-enumeration` rule flags three or more distinct ranks in a prose block, including rank one. It recognises English ordinal words and numbered markers from one to six.",
"",
"The audit reads Markdown as written and does not interpret raw HTML. It sets HTML tags aside and reads the text between them, even where GitHub would hide or change that text.",
"",
"## Workflow",
"",
"1. Read the path from `$ARGUMENTS`. Ask for a path when none was supplied.",
"2. Resolve the audit script relative to this `SKILL.md` file.",
"3. State the selected file or directory before running the script.",
"4. Treat an explicitly supplied directory as approval to read that directory.",
"5. Ask before expanding the audit beyond the supplied path.",
"6. Run the script with Bun:",
"",
"```text",
"bun <skill-directory>/scripts/audit-text-cli.ts <file-or-directory> --project-dir <project-directory>",
"```",
"",
" Add `--no-front-matter` for text that cannot carry metadata, such as a pull request description. A leading `---` block is then read as text, not set aside as front matter.",
"",
"7. Report every finding with its file, line, rule, and explanation.",
"8. Report skipped or unreadable entries. Never treat an incomplete audit as clean.",
"9. Explain that findings are mechanical proxies, not an ISO judgement.",
"10. Leave the final decision and any rewriting request to the user.",
"",
"## Boundaries",
"",
"- Read `.md`, `.markdown`, and `.txt` files only.",
"- Do not follow a selected or nested symbolic link or directory junction. Report each one as skipped.",
"- Do not alter the selected text unless the user separately requests changes.",
"- Do not create a report file unless the user requests one and names its location.",
"- Do not describe zero findings as proof that text is valid, compliant, or suitable.",
"- Use the relevant sector skill when interpreting findings in legal, technical, scientific, or designed documents.",
"",
],
"skills/iso-24495-text-audit/agents/openai.yaml": [
"interface:",
" display_name: \"ISO 24495 Text Audit\"",
" short_description: \"Audit selected text for plain-language findings\"",
" default_prompt: \"Use $iso-24495-text-audit to audit a selected text file for plain-language findings.\"",
"",
"policy:",
" allow_implicit_invocation: false",
"",
],
};
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |