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/templates.test.ts
View on GitHubimport { describe, expect, test } from "bun:test";
import { existsSync, readFileSync } from "node:fs";
import { join } from "node:path";
import { auditText } from "../../iso-24495-4/scripts/audit-corpus.ts";
import { headings } from "../../iso-24495-4/scripts/lib/parse.ts";
const SKILL_DIR = join(import.meta.dir, "..");
const ASSETS_DIR = join(SKILL_DIR, "assets");
const TEMPLATE_NAMES = ["adr-template.md", "runbook-template.md", "design-doc-template.md"];
function readTemplate(name: string): string {
return readFileSync(join(ASSETS_DIR, name), "utf8");
}
function githubSlug(heading: string): string {
return heading
.trim()
.toLowerCase()
.replace(/[^\w -]/g, "")
.replace(/ /g, "-");
}
describe("Part 5 document templates", () => {
test("ships the ADR, runbook, and design document templates", () => {
for (const name of TEMPLATE_NAMES) {
expect(existsSync(join(ASSETS_DIR, name))).toBe(true);
}
});
test("all templates produce zero audit violations", () => {
for (const name of TEMPLATE_NAMES) {
expect(auditText(readTemplate(name))).toEqual([]);
}
});
test("no template exceeds level 4 and the design document reaches it once", () => {
for (const name of TEMPLATE_NAMES) {
const levels = readTemplate(name)
.split(/\r?\n/)
.flatMap((line) => line.match(/^(#{1,6})\s/)?.[1].length ?? []);
expect(Math.max(...levels)).toBeLessThanOrEqual(4);
if (name === "design-doc-template.md") {
expect(levels.filter((level) => level === 4)).toHaveLength(1);
}
}
});
test("design document contents links resolve to identically worded headings", () => {
const lines = readTemplate("design-doc-template.md").split(/\r?\n/);
const headings = new Map(
lines.flatMap((line) => {
const match = /^## (.+)$/.exec(line);
return match && match[1] !== "Contents" ? [[githubSlug(match[1]), match[1]]] : [];
}),
);
const contents = lines.flatMap((line) => {
const match = /^- \[(.+)\]\(#([^)]+)\)$/.exec(line);
return match ? [{ text: match[1], anchor: match[2] }] : [];
});
expect(contents).toHaveLength(6);
for (const entry of contents) {
expect(entry.anchor).toBe(githubSlug(entry.text));
expect(headings.get(entry.anchor)).toBe(entry.text);
}
});
// Round 10 found every template breaking a rule it exists to demonstrate, and
// no test able to see it. Round 11 then defeated the first version of these
// gates by mutating the templates, so each one now tests content, not labels.
test("every template opens with a title and a filled opening block", () => {
for (const name of TEMPLATE_NAMES) {
const lines = readTemplate(name).split("\n").map((line) => line.trimEnd());
expect(lines[0], `${name} opens with a title`).toMatch(/^# .+/);
const fields = new Map(
lines.slice(0, 10)
.filter((line) => /^- [*][*][A-Za-z ]+:[*][*]/.test(line))
.map((line) => [line.slice(4, line.indexOf(":**")), line.slice(line.indexOf(":**") + 3).trim()]),
);
for (const field of ["Purpose", "For", "Version"]) {
expect([...fields.keys()], `${name} states ${field}`).toContain(field);
expect((fields.get(field) ?? "").length, `${name} fills ${field}`).toBeGreaterThan(10);
}
const purposeLines = lines.filter((line) => line.startsWith("- **Purpose:**"));
expect(purposeLines, `${name} keeps purpose to one line`).toHaveLength(1);
// A continuation line under the purpose would make it two lines in fact.
const after = lines[lines.indexOf(purposeLines[0] as string) + 1] ?? "";
expect(after === "" || after.startsWith("- "), `${name} does not continue purpose`).toBe(true);
}
});
test("a template needing an overview asks for all three things an overview keeps", () => {
for (const name of TEMPLATE_NAMES) {
const body = readTemplate(name);
const sections = body.split("\n").filter((line) => /^## /.test(line));
if (sections.length < 6) continue;
const summary = body.slice(body.indexOf("## 1."), body.indexOf("## 2."));
expect(summary.split("\n")[0], `${name} labels its overview`).toMatch(/summary|overview|abstract/i);
expect(summary, `${name} asks for the conclusion`).toMatch(/outcome|conclusion|recommend/i);
expect(summary, `${name} asks for the required action`).toMatch(/must do|required action|do next/i);
expect(summary, `${name} asks for the qualifications`).toMatch(/condition|qualification|caveat/i);
expect(summary, `${name} does not tell the author to omit them`)
.not.toMatch(/omit|leave out|deliberately omitted/i);
}
});
test("every template holding a table tells the author to name a width and test it", () => {
const divider = /^[|\s:-]*[|][\s:-]*-{3,}[\s:-]*[|]?[\s:-]*$/;
for (const name of TEMPLATE_NAMES) {
const body = readTemplate(name);
const hasTable = body.split("\n").some((line) => divider.test(line.trim()) && line.includes("-"));
if (!hasTable) continue;
expect(body, `${name} names a target width`).toMatch(/[[]Name the narrowest width/);
expect(body, `${name} says to read the table back at it`).toMatch(/read (it|them) back at that width/);
expect(body, `${name} offers the labelled-record fallback`).toMatch(/labelled records/);
expect(body, `${name} does not negate its width instruction`)
.not.toMatch(/(do|should|must|shall|can|will|need)( ?n.t| not) (read|use)|never (read|use)/i);
}
});
test("a template that numbers its headings says why, and how to undo it", () => {
for (const name of TEMPLATE_NAMES) {
const body = readTemplate(name);
// Arabic, Roman, "1)", "(1)" and "[1]" all count as numbering.
const numbered = body.split("\n").filter((line) => /^#{2,4} [([]?([0-9]+|[ivxIVX]+)[.)\]]/.test(line));
if (numbered.length === 0) continue;
expect(body, `${name} justifies numbering`).toMatch(/cite these sections by number/);
// "Do not cite these sections by number" contains the phrase above, so refuse the negation.
expect(body, `${name} does not negate its own reason`).not.toMatch(/(do|should|must|shall|can|will|need)( ?n.t| not) cite these sections|no need to cite/i);
// Removing numbers without the contents list breaks the anchors beneath it.
expect(body, `${name} says to update the contents too`).toMatch(/from this contents list/);
}
});
// Round 17: asserting fragments let a line keep its label while losing its
// meaning. These are whole lines, so an edit to any part of one turns it red.
const REQUIRED_LINES: Record<string, string[]> = {
"adr-template.md": [
"- **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.]",
"- **Version:** [Version or date.]",
"- **Status:** [Proposed or accepted. Where deprecated or superseded, name the decision that replaces this one.]",
"- **Instead of this:** [Link the decision that may suit the reader better and say when to read it, or delete this line.]",
"[Name the narrowest width this table must survive, then read it back at that width. Where no width is known, use labelled records instead.]",
],
"runbook-template.md": [
"- **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.]",
"> [!CAUTION]",
"> [Critical risks or conditions, before any step runs.]",
"> [!NOTE]",
"> [Expected output for step 2. Where it differs, stop and do not run step 3.]",
],
"design-doc-template.md": [
"- **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.]",
"[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.]",
"[Name the narrowest width each table must survive, then read them back at that width. Where no width is known, use labelled records instead.]",
],
};
// Twenty-three rounds of adversarial review found the same lesson in eight
// different disguises: a test that checks a fragment, a count, a label or a
// position leaves everything it does not name unprotected. Fragments fell to
// rewording, counts to moving, tables to hollowing out, and a verification
// section could be deleted whole while every assertion held.
//
// These three files are this repository's own canonical assets, so the honest
// guarantee is that no change to them is accidental. The whole text is the
// expectation. Editing a template means editing this list in the same commit,
// which is the point rather than a cost.
const HEADING_SEQUENCE: Record<string, { level: number; text: string }[]> = {
"adr-template.md": [
{ level: 1, text: "[Decision Title]" },
{ level: 2, text: "Context" },
{ level: 2, text: "What each option offers and costs" },
{ level: 2, text: "Decision" },
{ level: 2, text: "Consequences" },
],
"runbook-template.md": [
{ level: 1, text: "[Task Title]" },
{ level: 2, text: "Check these before you start" },
{ level: 2, text: "Run these steps in order" },
{ level: 2, text: "Confirm the task worked" },
],
"design-doc-template.md": [
{ level: 1, text: "[Project Name] Design Document" },
{ level: 2, text: "Contents" },
{ level: 2, text: "1. Summary" },
{ level: 2, text: "2. System Architecture" },
{ level: 3, text: "2.1. What each component is responsible for" },
{ level: 3, text: "2.2. How a request flows through the system" },
{ level: 4, text: "2.2.1. How a sign-in is checked" },
{ level: 2, text: "3. Data Model" },
{ level: 3, text: "3.1. Entities and Relationships" },
{ level: 3, text: "3.2. How data enters, changes and leaves" },
{ level: 2, text: "4. API Design" },
{ level: 3, text: "4.1. Endpoints" },
{ level: 3, text: "4.2. Error Handling" },
{ level: 2, text: "5. Security Model" },
{ level: 3, text: "5.1. Threats and Controls" },
{ level: 3, text: "5.2. Access Control" },
{ level: 2, text: "6. Deployment Plan" },
{ level: 3, text: "6.1. Environments" },
{ level: 3, text: "6.2. How the change ships and how it comes back" },
],
};
const TEMPLATE_SNAPSHOT: Record<string, string[]> = {
"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]",
],
"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]`.",
],
"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.] |",
],
};
test("no reader-visible template change happens without this test changing too", () => {
for (const name of TEMPLATE_NAMES) {
const actual = readTemplate(name).replace(/\r\n/g, "\n").replace(/\n+$/, "").split("\n");
expect(actual, `${name} matches its recorded text`).toEqual(TEMPLATE_SNAPSHOT[name] ?? []);
}
});
// Kept beside the snapshot because it names the failure. A snapshot says the
// file differs; this says which heading moved.
test("every template heads its sections exactly as its rules require", () => {
for (const name of TEMPLATE_NAMES) {
const found = headings(readTemplate(name))
.map((heading) => ({ level: heading.level, text: heading.text.trim() }));
expect(found, `${name} heads its sections as expected`).toEqual(HEADING_SEQUENCE[name] ?? []);
}
});
test("Part 5 skill references every required template path", () => {
const skill = readFileSync(join(SKILL_DIR, "SKILL.md"), "utf8");
for (const name of TEMPLATE_NAMES) {
expect(skill).toContain(`assets/${name}`);
}
});
});
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 |