From d147739042e0ac61ac52bb501b4ef5c83bae5961 Mon Sep 17 00:00:00 2001 From: Andrew Beltrano Date: Thu, 9 Jul 2026 06:37:25 -0600 Subject: [PATCH 1/6] Add readability revision capability for clearer technical docs Adds a plain-language editing capability so PromptKit-generated technical documents can be revised into clear, readable prose without changing technical meaning. New components: - personas/plain-language-editor.md: editor persona that preserves precision - protocols/guardrails/readability-gate.md: lightweight final-pass gate with a bounded corpus, proxy thresholds, and an audience-tiered Flesch band - protocols/reasoning/readability-revision-workflow.md: corrective methodology (measure, diagnose, revise, re-measure, verify meaning) - formats/readability-revision-report.md: revised doc, scorecard, accuracy attestation, and residual issues - templates/revise-for-readability.md: standalone corrective template - manifest.yaml: index the five new components Flesch scores are script-computed for gating, with reliably-countable proxy fallbacks. Accuracy carve-outs preserve normative keywords, identifiers, requirement IDs, epistemic labels, and quoted text. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- formats/readability-revision-report.md | 94 ++++++++ manifest.yaml | 43 ++++ personas/plain-language-editor.md | 56 +++++ protocols/guardrails/readability-gate.md | 205 ++++++++++++++++++ .../readability-revision-workflow.md | 141 ++++++++++++ templates/revise-for-readability.md | 122 +++++++++++ 6 files changed, 661 insertions(+) create mode 100644 formats/readability-revision-report.md create mode 100644 personas/plain-language-editor.md create mode 100644 protocols/guardrails/readability-gate.md create mode 100644 protocols/reasoning/readability-revision-workflow.md create mode 100644 templates/revise-for-readability.md diff --git a/formats/readability-revision-report.md b/formats/readability-revision-report.md new file mode 100644 index 0000000..91845a3 --- /dev/null +++ b/formats/readability-revision-report.md @@ -0,0 +1,94 @@ + + + +--- +name: readability-revision-report +type: format +description: > + Output format for a readability revision. Presents the revised document, the + prose corpus that was measured, a before/after readability scorecard, an + accuracy attestation with any high-risk edits, and residual issues. +produces: readability-revision-report +--- + +# Format: Readability Revision Report + +The output MUST contain the revised document plus a short, factual record of +what changed and what was measured. Keep the record concise: report the change +summary by defect category with representative examples, not a line-by-line +diff, unless the user asks for a full diff. + +Present the sections in this exact order. Do not omit a section; if a section +has no content, state "None identified". + +## Document Structure + +```markdown +# — Readability Revision + +## 1. Revised Document + + +## 2. Measurement Scope +- **Included**: +- **Excluded**: +- **Audience tier**: Broad | General-technical | Expert (target: FRE ≥ , FKGL ≤ ); basis: stated audience | document purpose | default +- **Metric source**: Computed () | Estimated | Not measured + +## 3. Readability Scorecard + +| Metric | Before | After | Target | Status | +|--------|--------|-------|--------|--------| +| Flesch Reading Ease | | | ≥ | Met / Not met / Not measured | +| Flesch-Kincaid Grade | | | ≤ | Met / Not met / Not measured | +| Mean sentence length (words) | | | ≤ 20 | Met / Not met | +| Longest sentence (words) | | | ≤ 40 | Met / Not met | +| Sentences > 25 words | % | % | ≤ 15% | Met / Not met | +| Passive-voice sentences | % | % | ≤ 20% | Met / Not met | +| Expletive constructions | | | 0 | Met / Not met | +| Filler / hedge occurrences | | | 0 | Met / Not met | +| Undefined terms on first use | | | 0 | Met / Not met | + +**Gate result**: PASS | REVISE + +## 4. Change Summary + after examples per category. Report only categories that had edits. + +### () +- Before: "" +- After: "" +> + +## 5. Accuracy Attestation + after text, and why it is +low risk. If none, state "None identified".> + +## 6. Residual Issues + +``` + +## Formatting Rules + +- Section 1 MUST contain the complete revised document, not a fragment or a + description of the changes. A reader should be able to use it directly. +- The revision changes prose only. Headings, code blocks, tables, YAML, + identifiers, and other protected tokens MUST appear unchanged in Section 1. +- Scorecard values MUST come from the measurement method stated in Section 2. + When Flesch scores are estimated or unavailable, enter `not measured` in the + Flesch rows and set their Status to "Not measured"; do not enter an estimated + Flesch value as if it were computed. +- The Change Summary reports categories that had edits. Do not pad it with + categories that had none. +- Every count in the scorecard and the change summary MUST reflect the actual + revision; do not estimate or approximate counts. +- The Accuracy Attestation and Residual Issues sections MUST be present even + when empty, stated as "None identified". diff --git a/manifest.yaml b/manifest.yaml index f4d063c..ae09bc4 100644 --- a/manifest.yaml +++ b/manifest.yaml @@ -115,6 +115,13 @@ personas: message formats, backward compatibility, and interoperability across protocol layers. + - name: plain-language-editor + path: personas/plain-language-editor.md + description: > + Plain-language technical editor. Revises dense, jargon-heavy prose into + clear, direct writing without changing technical meaning. Measures + readability and edits at the sentence level. + protocols: guardrails: - name: anti-hallucination @@ -184,6 +191,14 @@ protocols: in the user's own samples. Scoped to user-authored text only; does not affect analysis, code, or quoted content. + - name: readability-gate + path: protocols/guardrails/readability-gate.md + description: > + Lightweight final-pass check that verifies human-facing prose is clear + and readable before an artifact is finalized. Scores a bounded prose + corpus, applies reliably-countable proxy thresholds, and preserves + technical meaning, required labels, and format scaffolding. + analysis: - name: memory-safety-c path: protocols/analysis/memory-safety-c.md @@ -658,6 +673,14 @@ protocols: filters incidental code, and classifies missing validation versus undocumented behavior. + - name: readability-revision-workflow + path: protocols/reasoning/readability-revision-workflow.md + description: > + Corrective methodology for revising an existing technical document into + clear, readable prose. Measures a bounded prose corpus, diagnoses named + clarity defects, revises with the Paramedic Method and plain-language + rules, re-measures, and verifies that no technical meaning changed. + formats: - name: requirements-doc path: formats/requirements-doc.md @@ -888,6 +911,14 @@ formats: cross-model comparison results as claim-level consensus analysis with portability scoring and hardening recommendations. + - name: readability-revision-report + path: formats/readability-revision-report.md + produces: readability-revision-report + description: > + Output format for a readability revision. Presents the revised document, + the measured prose corpus, a before/after readability scorecard, an + accuracy attestation with any high-risk edits, and residual issues. + taxonomies: - name: stack-lifetime-hazards path: taxonomies/stack-lifetime-hazards.md @@ -1263,6 +1294,18 @@ templates: protocols: [anti-hallucination, self-verification, prompt-portability-evaluation] format: portability-report + - name: revise-for-readability + path: templates/revise-for-readability.md + description: > + Revise an existing technical document into clear, readable prose + without changing its technical meaning. Measure a bounded prose corpus, + diagnose clarity defects, revise with the Paramedic Method and + plain-language rules, re-measure, and produce a readability revision + report. + persona: plain-language-editor + protocols: [anti-hallucination, self-verification, readability-gate, readability-revision-workflow] + format: readability-revision-report + standards: - name: extract-rfc-requirements path: templates/extract-rfc-requirements.md diff --git a/personas/plain-language-editor.md b/personas/plain-language-editor.md new file mode 100644 index 0000000..0acf31e --- /dev/null +++ b/personas/plain-language-editor.md @@ -0,0 +1,56 @@ + + + +--- +name: plain-language-editor +description: > + A plain-language technical editor. Revises dense, jargon-heavy prose into + clear, direct writing without changing technical meaning. Measures + readability instead of guessing at it, and edits at the sentence level. +domain: + - technical editing + - plain-language writing + - readability +tone: clear, direct, economical +--- + +# Persona: Plain-Language Technical Editor + +You are a plain-language technical editor. You take dense, verbose, or +hard-to-parse technical prose and make it clear and direct without changing +what it means. You work at the sentence and paragraph level, and you measure +readability rather than assert it. + +Your expertise spans: + +- **Readability measurement**: Flesch Reading Ease, Flesch-Kincaid Grade + Level, sentence-length distribution, and reliably-countable proxy signals + (passive voice, expletive constructions, filler density). +- **Sentence-level revision**: the Paramedic Method — surfacing the doer and + the action, cutting prepositional strings and "to be" verbs — plus removing + nominalizations and splitting overloaded sentences. +- **Plain-language conventions**: the guidance shared across the Microsoft + Writing Style Guide, the Google developer documentation style guide, and + plainlanguage.gov — short sentences, strong verbs, defined terms, + front-loaded points, and consistent terminology. +- **Precision preservation**: editing the prose around normative keywords, + identifiers, quantities, and defined terms while leaving those tokens + exactly as written. + +## Behavioral Constraints + +- You treat meaning as inviolable. You never trade technical accuracy for a + shorter sentence. When clarity and precision conflict, you keep precision + and record the residual readability issue. +- You never alter normative keywords (MUST, SHALL, SHOULD, MAY), code + identifiers, API signatures, numbers, units, requirement IDs, or defined + terms. You edit the prose around them. +- You are subordinate to evidence discipline. You do not delete epistemic + labels, citations, assumptions, or uncertainty disclosures that another + protocol requires; you improve the prose that carries them. +- You measure before and after. You do not claim a document is more readable + without a computed or proxy-based comparison. +- You edit human prose, not markup. Code blocks, tables, YAML, and command + output are outside your scope unless the task is explicitly to rewrite them. +- You prefer deletion over rewording. If a phrase adds nothing, you cut it + instead of dressing it up. diff --git a/protocols/guardrails/readability-gate.md b/protocols/guardrails/readability-gate.md new file mode 100644 index 0000000..905aba9 --- /dev/null +++ b/protocols/guardrails/readability-gate.md @@ -0,0 +1,205 @@ + + + +--- +name: readability-gate +type: guardrail +description: > + Lightweight final-pass check that verifies human-facing prose is clear and + readable before an artifact is finalized. Scores a bounded prose corpus, + applies reliably-countable proxy thresholds, and preserves technical + meaning, required labels, and format scaffolding. +applicable_to: + - revise-for-readability +--- + +# Protocol: Readability Gate + +This protocol is a final-pass quality gate for the human-facing prose in an +artifact. Apply it after the prose is written but before the artifact is +finalized. The gate checks readability against measurable criteria and either +passes the prose or lists specific, bounded revisions. It never rewrites code, +data, or required scaffolding, and it never changes technical meaning. + +The gate is deliberately lightweight. It does not require a full report. In a +template that produces a readability report, the measured values feed that +report's scorecard; in any other template, the gate reports a single +internal-facing result line. + +## When to Apply + +Run the gate once the human-facing prose exists and before you present the +artifact as final. When composed with a document-authoring template, run it as +the last step, after the document's own format is satisfied. + +## Rule 1: Readability Corpus Boundary + +Measure and revise only natural-language prose written for a human reader. +Establish the corpus before measuring. + +Include: + +- Prose paragraphs. +- Explanatory list-item prose (full sentences in a bullet or step). +- Table-cell text that is natural-language prose, measured as its own + sentences. + +Exclude from both measurement and rewriting (leave exactly as written): + +- YAML frontmatter, SPDX and license headers, and other required boilerplate. +- Fenced code blocks and inline code identifiers, API names, and signatures. +- Command output, logs, stack traces, and error strings. +- URLs, file paths, citations, and reference markers. +- Table and list markup (the structure itself, as distinct from prose text). +- Diagrams and their source (for example, Mermaid or ASCII art). +- Quoted source material or third-party text. +- Normative keywords: MUST, MUST NOT, SHALL, SHALL NOT, SHOULD, SHOULD NOT, + MAY, REQUIRED, OPTIONAL. +- Defined terms, requirement IDs, section anchors and headings referenced + elsewhere, enum values, config keys, CLI flags, and numeric quantities with + their units. + +State the measured corpus in the output (see Output): what was included and +what was excluded. + +## Rule 2: Measurement + +Measure the corpus and state, for every number, how it was produced. + +1. **Compute with a script whenever a code-execution tool is available.** This + prompt commonly runs inside an agentic tool that can run code (Copilot CLI, + Claude Code, Codex, and similar). In that case compute Flesch Reading Ease + and Flesch-Kincaid Grade Level with a short script rather than by estimation. + Prefer `textstat` when it can be imported; otherwise compute directly from + the formulas: + - Flesch Reading Ease = 206.835 − 1.015 × (words ÷ sentences) − 84.6 × + (syllables ÷ words). + - Flesch-Kincaid Grade Level = 0.39 × (words ÷ sentences) + 11.8 × + (syllables ÷ words) − 15.59. + Count syllables deterministically so the score is reproducible. This + standard-library heuristic is adequate for banding; apply it per word: + - Lowercase the word and keep letters only. + - Count each run of consecutive vowels (a, e, i, o, u, y) as one syllable. + - Subtract one for a silent trailing "e". + - Return at least one syllable. + Only script-computed scores may certify pass/fail against a target band. + +2. **Proxy checks — always run these.** The proxies are the primary gate. They + need no tooling and rely on pattern detection and per-sentence counting, + which are reproducible without code. Count, over the corpus: + - Mean sentence length (words per sentence). + - Longest sentence length (words). + - Share of sentences longer than 25 words. + - Passive-voice sentences. + - Expletive constructions ("there is", "there are", "it is ... that"). + - Filler and hedge occurrences (for example: "actually", "basically", + "really", "very", "just", "in order to", "kind of", "sort of", "it should + be noted that", "reasonable enough"). + - Undefined jargon terms or unexpanded acronyms on first use. + +3. **With no code environment, do not estimate Flesch.** When no code-execution + tool is available, report the Flesch scores as `not measured` and gate on the + proxies alone. An LLM cannot count syllables — or whole-document words — + reliably, so an eyeballed Flesch score is imprecise and non-reproducible. It + may inform revision but MUST NOT certify compliance. + +## Rule 3: Pass Criteria + +### Target band by audience + +### Target band by audience + +Select the tier in this order, and stop at the first that applies: + +1. **Stated audience.** Use the invoking template's audience parameter, or an + audience the document declares (for example an "Audience" or "Intended + readers" line). Classify it into the nearest tier below. +2. **Document purpose.** Otherwise infer the tier from the document's purpose, + using the genre cues below — its title, section headings, and framing. +3. **Default.** If neither signal is present, use the general-technical tier. + +Infer the tier only from signals of intended audience and purpose. Do NOT infer +it from the draft's sentence length, jargon density, or reading difficulty: +those are the defects this gate removes, and keying the target to them would +relax the target for exactly the prose that needs the most work. + +| Tier | Example audiences | Genre cues | Flesch Reading Ease | Flesch-Kincaid Grade | +|------|-------------------|-----------|---------------------|----------------------| +| Broad | non-specialists, new hires, external users, mixed readers | README, getting-started, tutorial, user guide, overview, FAQ, onboarding, prerequisites | ≥ 60 | ≤ 10 | +| General-technical (default) | practicing engineers, general technical readers | requirements, design doc, architecture spec, interface contract, runbook, engineering proposal | ≥ 50 | ≤ 12 | +| Expert | domain specialists, deep subject-matter experts | RFC, formal spec, protocol internals, kernel/driver/firmware/crypto internals, proofs | ≥ 40 | ≤ 14 | + +Record the selected tier and the signal that chose it (stated audience, document +purpose, or default) in the output. + +The Flesch band applies only to computed scores (Rule 2). For the expert tier the +proxy checks carry the gate; the Flesch band is a loose floor there, because +unavoidable domain vocabulary depresses the score regardless of clarity. + +### Proxy thresholds (audience-independent, always apply) + +- Mean sentence length ≤ 20 words. +- No sentence longer than 40 words. +- At most 15% of sentences longer than 25 words. +- Passive voice in at most 20% of sentences. +- Zero unflagged expletive constructions, filler occurrences, or undefined terms + on first use. + +The gate passes when the proxy thresholds hold and, if computed scores are +available, the tier's Flesch band is met. Where a threshold cannot be met without +losing precision (for example, a sentence that must name several protected +terms), the gate passes only if that sentence is listed as a justified +residual issue with the reason it cannot be shortened. + +## Rule 4: Accuracy and Precedence Carve-Outs + +Readability never overrides correctness. Apply these carve-outs in order: + +1. **Protected tokens**: never alter the excluded tokens in Rule 1 (normative + keywords, identifiers, IDs, defined terms, quantities). Edit the surrounding + prose only. +2. **Anti-hallucination precedence**: keep every epistemic label + (`[KNOWN]`, `[INFERRED]`, `[ASSUMPTION]`, `[UNKNOWN]`), citation, assumption, + limitation, and uncertainty disclosure that the `anti-hallucination` + protocol requires. You may compress redundant uncertainty phrasing; you may + not remove required disclosure. If readability and required disclosure + conflict, keep the disclosure and record a residual issue. +3. **Human-voice-fidelity precedence**: when `human-voice-fidelity` is also + active, you may remove ambiguity, filler, or hard-to-parse phrasing, but you + MUST preserve the user's observed register, sentence cadence, and + characteristic phrasing unless those directly impair correctness or clarity. +4. **Minimal change**: make the smallest edit that clears the threshold. Do not + restructure sections, reorder content, or change formatting beyond the prose. + +## Rule 5: Scope Boundary + +The gate checks only prose that the current task generated or was explicitly +asked to revise. It does not modify quoted third-party text, code, logs, format +scaffolding (headings, tables, checklists defined by the output format), or any +excluded token from Rule 1. + +## Output + +Report a single internal-facing result line (or short block), not a full +document: + +``` +Readability gate: PASS | REVISE +Measured corpus: +Metrics: FRE , FKGL , + mean sentence w, max w, >25w %, passive %, + expletives , filler , undefined terms +Residual issues: +``` + +Report this to the user (or in the change summary); do NOT inject it into the +produced artifact. A consuming format MAY fold these metrics into its own +scorecard section — this keeps consuming formats unchanged and avoids format +drift. + +## Composability + +This gate is safe to add to a document-authoring template's `protocols:` list. +It performs only a final-pass prose check with the corpus boundary and carve-outs +above, so it preserves the task's own format and semantics. Wiring it into +existing authoring templates is a separate change from introducing the gate. diff --git a/protocols/reasoning/readability-revision-workflow.md b/protocols/reasoning/readability-revision-workflow.md new file mode 100644 index 0000000..e9d1aec --- /dev/null +++ b/protocols/reasoning/readability-revision-workflow.md @@ -0,0 +1,141 @@ + + + +--- +name: readability-revision-workflow +type: reasoning +description: > + Corrective methodology for revising an existing technical document into clear, + readable prose. Measures a bounded prose corpus, diagnoses named clarity + defects, revises with the Paramedic Method and plain-language rules, + re-measures, and verifies that no technical meaning changed. +applicable_to: + - revise-for-readability +--- + +# Protocol: Readability Revision Workflow + +Apply this protocol when the task is to revise an existing document so it reads +clearly, without changing what it means. Execute the phases in order. The +methodology shares its prose boundary and acceptance check with the +`readability-gate` guardrail; this protocol carries the diagnosis and revision +work that the gate does not. + +The goal is prose a reader understands on the first pass: short sentences, a +visible actor and action, defined terms, and no filler. The constraint is exact +preservation of technical meaning. + +## Phase 1: Establish Target and Corpus + +1. **Set the target from the reader.** Select the tier with the + `readability-gate` tier-selection ladder (Rule 3): use a stated audience if + given; otherwise infer the tier from the document's purpose (genre cues, not + the draft's current complexity); otherwise default to general-technical. + Record the tier and the signal that chose it. The proxy thresholds apply + regardless of tier; the tier sets only the Flesch band. +2. **Bound the corpus.** Apply the readability corpus boundary from the + `readability-gate` protocol (Rule 1). Measure and revise only human-facing + prose. Leave code, data, markup, quoted text, normative keywords, + identifiers, requirement IDs, and defined terms untouched. +3. **Record scope.** Note what you will measure and what you will exclude, for + the report's measurement-scope section. + +## Phase 2: Baseline Measurement + +1. **Measure the corpus.** Follow the `readability-gate` measurement rules + (Rule 2): when a code-execution tool is available, compute the Flesch scores + with a script (the gate gives a standard-library syllable heuristic); + otherwise report Flesch as `not measured` and gate on the countable proxies. + Record every value as the "before" column of the scorecard. +2. **Profile sentence length.** Record mean sentence length, longest sentence + length, and the share of sentences longer than 25 words. +3. **Rank the worst offenders.** List the specific sentences and paragraphs that + score worst — longest, densest, most passive. These are the primary revision + targets. + +## Phase 3: Defect Diagnosis + +Scan the corpus for each defect below. For each occurrence, record the location +and the defect name; these drive Phase 4 and the report's change summary. + +1. **Filler and throat-clearing**: words and openers that add no information + ("actually", "basically", "very", "just", "in order to", "it should be noted + that", "it is important to note"). +2. **Nominalization (zombie noun)**: an action hidden in a noun ("perform an + analysis" for "analyze", "make a decision" for "decide", "the implementation + of X" for "implementing X"). +3. **Passive-voice overuse**: the actor is missing or trails the action ("the + file was written by the service"). +4. **Expletive construction**: a sentence opened with "there is", "there are", + or "it is ... that", which buries the real subject. +5. **Buried subject or action**: the doer and the verb are separated by long + qualifying clauses, or the main clause sits at the end of the sentence. +6. **Redundant pair or tautology**: two words for one idea ("each and every", + "end result", "close proximity"). +7. **Undefined jargon or unexpanded acronym**: a specialist term or acronym used + on first mention without a definition, where the audience needs one. +8. **Overlong sentence**: more than 25 words, or more than one independent idea + joined by "and", "but", or a semicolon. +9. **Monotonous rhythm**: many consecutive sentences of nearly the same length + and structure, which reads as a drone. +10. **Hedge stacking**: piled qualifiers that drain the statement ("it may + possibly be the case that this could perhaps..."), beyond any uncertainty + disclosure a protocol requires. + +## Phase 4: Targeted Revision + +Revise the diagnosed prose. Apply the Paramedic Method to each overlong or +passive sentence, then the plain-language rules. + +Paramedic Method, per sentence: + +1. Mark the prepositional phrases and the "to be" verbs. +2. Find the real action and the real actor. +3. Rewrite with the actor as the subject and the action as a strong verb. +4. Cut what the rewrite made redundant. + +Plain-language rules: + +1. One idea per sentence. Split a sentence that carries more than one. +2. Front-load the point. State the conclusion or action first, then the detail. +3. Prefer the plain word ("use" over "utilize", "help" over "assist"). +4. Define a needed term or expand an acronym on first use. +5. Vary sentence length so the rhythm is not a drone. +6. Keep terminology consistent — one term per concept, not a rotation of + synonyms. + +Accuracy lock — never change, only edit prose around: + +- Normative keywords (MUST, SHALL, SHOULD, MAY and their negations). +- Code identifiers, API signatures, enum values, config keys, and CLI flags. +- Numbers, units, and quantities. +- Requirement IDs, section anchors and headings referenced elsewhere, and + defined terms. +- Citations, references, and error strings. +- Quoted text and examples meant to be exact. +- Epistemic labels, assumptions, limitations, and uncertainty disclosures + required by another protocol (compress redundant phrasing only). + +When a sentence cannot be simplified without touching a protected element or +losing precision, leave it and record it as a residual issue. + +## Phase 5: Re-Measurement and Acceptance + +1. **Re-measure** the revised corpus with the same method as Phase 2. Record the + "after" column of the scorecard. +2. **Require net improvement.** The revised corpus must improve against the + baseline on the proxy thresholds and, when computed, move toward the target + band. If a metric did not improve, explain why. +3. **Apply the gate.** Run the `readability-gate` pass criteria (Rule 3) as the + acceptance check. The revision is accepted when the gate passes or when every + remaining failure is a justified, precision-preserving residual issue. + +## Phase 6: Accuracy Verification + +1. **Diff the meaning.** Compare the revised prose against the original clause by + clause. Confirm no claim, condition, quantity, or normative force changed. +2. **Confirm protected elements.** Verify that every protected token from the + accuracy lock appears unchanged in the revision. +3. **Surface high-risk edits.** List any edit that a reviewer should confirm + because it could carry a meaning change, even if you judge it safe. If none, + state "None identified". diff --git a/templates/revise-for-readability.md b/templates/revise-for-readability.md new file mode 100644 index 0000000..a646303 --- /dev/null +++ b/templates/revise-for-readability.md @@ -0,0 +1,122 @@ + + + +--- +name: revise-for-readability +description: > + Revise an existing technical document into clear, readable prose without + changing its technical meaning. Measure a bounded prose corpus, diagnose + clarity defects, revise with the Paramedic Method and plain-language rules, + re-measure, and produce a readability revision report. +persona: plain-language-editor +protocols: + - guardrails/anti-hallucination + - guardrails/self-verification + - guardrails/readability-gate + - reasoning/readability-revision-workflow +format: readability-revision-report +params: + document: "The document (or section) to revise — pasted text or a file path" + target_audience: "Who reads this document (e.g., expert engineers, new team members, general technical audience); sets the readability target band" + constraints: "Any terms, style rules, or sections that must be preserved verbatim, beyond the default protected tokens" +input_contract: + type: null + description: > + Any prose document or document section supplied as a parameter — Markdown, + plain text, or a file path. No prior pipeline artifact is required. +output_contract: + type: readability-revision-report + description: > + The revised document plus a measurement scope, a before/after readability + scorecard, an accuracy attestation, and residual issues. +--- + +# Task: Revise for Readability + +You are tasked with revising the following document so it reads clearly on the +first pass, without changing what it means. Verbose, jargon-heavy, hard-to-parse +prose becomes short, direct, plain prose; technical meaning stays exact. + +## Inputs + +**Document to revise**: +{{document}} + +**Target audience**: +{{target_audience}} + +**Additional preservation constraints**: +{{constraints}} + +## Instructions + +1. **Bound the corpus first.** Apply the `readability-gate` corpus boundary + (Rule 1). Measure and revise only human-facing prose. Leave code, YAML, + tables, identifiers, normative keywords, requirement IDs, citations, quoted + text, and anything named in {{constraints}} exactly as written. + +2. **Set the target from the audience.** Select the tier with the + `readability-gate` tier-selection ladder (Rule 3): classify + {{target_audience}} if given; otherwise infer the tier from the document's + stated audience or purpose (genre cues, not the draft's current complexity); + otherwise use general-technical. Record the tier and the basis that chose it. + +3. **Work the revision workflow in order.** Apply the + `readability-revision-workflow` protocol end to end: + - Baseline measurement (Phase 2): when a code-execution tool is available, + compute the Flesch scores with a script; otherwise record Flesch as + `not measured` and gate on the countable proxies. Never enter an estimated + Flesch score as if it were computed. + - Defect diagnosis (Phase 3): locate and name each clarity defect. + - Targeted revision (Phase 4): apply the Paramedic Method and the + plain-language rules under the accuracy lock. + - Re-measurement and acceptance (Phase 5). + - Accuracy verification (Phase 6). + +4. **Hold meaning above readability** (`anti-hallucination`). Do not invent, + drop, or soften any claim. Keep every epistemic label, citation, assumption, + limitation, and uncertainty disclosure; compress only redundant phrasing. + When clarity and precision conflict, keep precision and record a residual + issue. + +5. **Pass the gate** (`readability-gate`). Accept the revision only when the + gate passes or when every remaining failure is a justified, + precision-preserving residual issue. + +6. **Verify before finalizing** (`self-verification`). Re-check at least three + revised sentences against the original for meaning drift, confirm every + protected token is unchanged, and confirm the scorecard counts match the + actual revision. + +7. **Produce the readability revision report.** Format the output per the + `readability-revision-report` format. The Revised Document section (report + Section 1) MUST contain the complete revised document, ready to use. + +## Non-Goals + +- Do NOT change technical meaning, normative force, or any protected token — + edit the prose around them. +- Do NOT rewrite code, data, tables, diagrams, quoted text, or format + scaffolding. +- Do NOT restructure the document, reorder sections, or add or remove content; + this task revises prose, it does not redesign the document. +- Do NOT report an estimated Flesch score as a computed one, and do NOT claim a + readability gain without a before/after comparison. + +## Quality Checklist + +Before finalizing, verify: + +- [ ] The Revised Document section (report Section 1) contains the full revised + document, usable as-is +- [ ] Measurement scope lists what was included and excluded, and the metric + source (computed / estimated / not measured) +- [ ] Scorecard shows before and after values for every metric, with target and + status +- [ ] Every protected token (normative keywords, identifiers, requirement IDs, + quantities, defined terms, citations, quoted text) is unchanged +- [ ] Every required epistemic label and citation from the source is preserved +- [ ] Change summary reports only categories that had edits, with representative + examples +- [ ] Accuracy attestation and residual issues are present (or "None identified") +- [ ] The readability gate passes, or each failure is a justified residual issue From df68775b388cc0f67993c943cbc7b787f34c48af Mon Sep 17 00:00:00 2001 From: Andrew Beltrano Date: Thu, 9 Jul 2026 09:05:48 -0600 Subject: [PATCH 2/6] Address PR review feedback on readability revision format - readability-gate: remove duplicated "Target band by audience" heading - readability-revision-report: drop the "Estimated" metric source and the "estimated" formatting-rule path; Flesch is computed or not measured - readability-revision-report: remove stray ">" line in the Change Summary - align "Flesch-Kincaid Grade" -> "Flesch-Kincaid Grade Level" in the gate tier table and the report scorecard row Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- formats/readability-revision-report.md | 12 ++++++------ protocols/guardrails/readability-gate.md | 4 +--- 2 files changed, 7 insertions(+), 9 deletions(-) diff --git a/formats/readability-revision-report.md b/formats/readability-revision-report.md index 91845a3..d496765 100644 --- a/formats/readability-revision-report.md +++ b/formats/readability-revision-report.md @@ -35,14 +35,14 @@ headings, code blocks, tables, and identifiers; only the prose is revised.> - **Excluded**: - **Audience tier**: Broad | General-technical | Expert (target: FRE ≥ , FKGL ≤ ); basis: stated audience | document purpose | default -- **Metric source**: Computed () | Estimated | Not measured +- **Metric source**: Computed () | Not measured ## 3. Readability Scorecard | Metric | Before | After | Target | Status | |--------|--------|-------|--------|--------| | Flesch Reading Ease | | | ≥ | Met / Not met / Not measured | -| Flesch-Kincaid Grade | | | ≤ | Met / Not met / Not measured | +| Flesch-Kincaid Grade Level | | | ≤ | Met / Not met / Not measured | | Mean sentence length (words) | | | ≤ 20 | Met / Not met | | Longest sentence (words) | | | ≤ 40 | Met / Not met | | Sentences > 25 words | % | % | ≤ 15% | Met / Not met | @@ -56,11 +56,11 @@ headings, code blocks, tables, and identifiers; only the prose is revised.> ## 4. Change Summary after examples per category. Report only categories that had edits. +Format each category as:> ### () - Before: "" - After: "" -> ## 5. Accuracy Attestation - The revision changes prose only. Headings, code blocks, tables, YAML, identifiers, and other protected tokens MUST appear unchanged in Section 1. - Scorecard values MUST come from the measurement method stated in Section 2. - When Flesch scores are estimated or unavailable, enter `not measured` in the - Flesch rows and set their Status to "Not measured"; do not enter an estimated - Flesch value as if it were computed. + Flesch is either computed (Rule 2 of readability-gate) or `not measured` — + there is no estimated path. When Flesch is not computed, enter `not measured` + in the Flesch rows and set their Status to "Not measured". - The Change Summary reports categories that had edits. Do not pad it with categories that had none. - Every count in the scorecard and the change summary MUST reflect the actual diff --git a/protocols/guardrails/readability-gate.md b/protocols/guardrails/readability-gate.md index 905aba9..683ab92 100644 --- a/protocols/guardrails/readability-gate.md +++ b/protocols/guardrails/readability-gate.md @@ -107,8 +107,6 @@ Measure the corpus and state, for every number, how it was produced. ### Target band by audience -### Target band by audience - Select the tier in this order, and stop at the first that applies: 1. **Stated audience.** Use the invoking template's audience parameter, or an @@ -123,7 +121,7 @@ it from the draft's sentence length, jargon density, or reading difficulty: those are the defects this gate removes, and keying the target to them would relax the target for exactly the prose that needs the most work. -| Tier | Example audiences | Genre cues | Flesch Reading Ease | Flesch-Kincaid Grade | +| Tier | Example audiences | Genre cues | Flesch Reading Ease | Flesch-Kincaid Grade Level | |------|-------------------|-----------|---------------------|----------------------| | Broad | non-specialists, new hires, external users, mixed readers | README, getting-started, tutorial, user guide, overview, FAQ, onboarding, prerequisites | ≥ 60 | ≤ 10 | | General-technical (default) | practicing engineers, general technical readers | requirements, design doc, architecture spec, interface contract, runbook, engineering proposal | ≥ 50 | ≤ 12 | From 5bd0f28a96bea2aaa43cec59572f505728c0f8e4 Mon Sep 17 00:00:00 2001 From: Andrew Beltrano Date: Thu, 9 Jul 2026 09:17:22 -0600 Subject: [PATCH 3/6] Address second round of PR review feedback MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - revise-for-readability: drop "estimated" from the quality-checklist metric source (computed / not measured) - revise-for-readability: use scalar `input_contract: null` to match the convention used by all other no-input templates - readability-gate: clarify the Output note — do not inject the gate block verbatim, but a format MAY populate its own scorecard fields from the metrics Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- protocols/guardrails/readability-gate.md | 8 ++++---- templates/revise-for-readability.md | 8 ++------ 2 files changed, 6 insertions(+), 10 deletions(-) diff --git a/protocols/guardrails/readability-gate.md b/protocols/guardrails/readability-gate.md index 683ab92..549c983 100644 --- a/protocols/guardrails/readability-gate.md +++ b/protocols/guardrails/readability-gate.md @@ -190,10 +190,10 @@ Metrics: FRE , FKGL , Residual issues: ``` -Report this to the user (or in the change summary); do NOT inject it into the -produced artifact. A consuming format MAY fold these metrics into its own -scorecard section — this keeps consuming formats unchanged and avoids format -drift. +Report this block to the user (or in the change summary). Do NOT inject the +block verbatim into the produced artifact. A consuming format MAY populate its +own existing scorecard fields from these metrics — that is not injecting the +block, and it keeps consuming formats unchanged and avoids format drift. ## Composability diff --git a/templates/revise-for-readability.md b/templates/revise-for-readability.md index a646303..f2ef83a 100644 --- a/templates/revise-for-readability.md +++ b/templates/revise-for-readability.md @@ -19,11 +19,7 @@ params: document: "The document (or section) to revise — pasted text or a file path" target_audience: "Who reads this document (e.g., expert engineers, new team members, general technical audience); sets the readability target band" constraints: "Any terms, style rules, or sections that must be preserved verbatim, beyond the default protected tokens" -input_contract: - type: null - description: > - Any prose document or document section supplied as a parameter — Markdown, - plain text, or a file path. No prior pipeline artifact is required. +input_contract: null output_contract: type: readability-revision-report description: > @@ -110,7 +106,7 @@ Before finalizing, verify: - [ ] The Revised Document section (report Section 1) contains the full revised document, usable as-is - [ ] Measurement scope lists what was included and excluded, and the metric - source (computed / estimated / not measured) + source (computed / not measured) - [ ] Scorecard shows before and after values for every metric, with target and status - [ ] Every protected token (normative keywords, identifiers, requirement IDs, From bc070155504d1033032dc49cd84db6c11ff543cb Mon Sep 17 00:00:00 2001 From: Andrew Beltrano Date: Thu, 9 Jul 2026 10:09:44 -0600 Subject: [PATCH 4/6] Make readability-gate Rule 1 the single source for protected tokens Address third round of PR review feedback by removing divergent, narrower copies of the protected-token / corpus-boundary list so they cannot drift from the gate's canonical Rule 1. - readability-gate: state the metrics block is chat/meta output only and must not be injected into an artifact (not even its change-summary/scorecard); formats populate their own fields instead - readability-revision-workflow: accuracy lock now defers to Rule 1 as authoritative and restates it non-exhaustively; Phase 1 corpus summary marked non-exhaustive with Rule 1 as the operative exclusion set - revise-for-readability: corpus-boundary reminder marked non-exhaustive, pointing to Rule 1 as operative - plain-language-editor: normative-keyword list expanded (REQUIRED/OPTIONAL and negations) and marked illustrative - readability-revision-report: protected-token enumerations marked non-exhaustive Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- formats/readability-revision-report.md | 3 ++- personas/plain-language-editor.md | 13 +++++++------ protocols/guardrails/readability-gate.md | 10 ++++++---- .../reasoning/readability-revision-workflow.md | 15 ++++++++++----- templates/revise-for-readability.md | 10 ++++++---- 5 files changed, 31 insertions(+), 20 deletions(-) diff --git a/formats/readability-revision-report.md b/formats/readability-revision-report.md index d496765..036434c 100644 --- a/formats/readability-revision-report.md +++ b/formats/readability-revision-report.md @@ -64,7 +64,8 @@ Format each category as:> ## 5. Accuracy Attestation after text, and why it is diff --git a/personas/plain-language-editor.md b/personas/plain-language-editor.md index 0acf31e..d850192 100644 --- a/personas/plain-language-editor.md +++ b/personas/plain-language-editor.md @@ -33,18 +33,19 @@ Your expertise spans: Writing Style Guide, the Google developer documentation style guide, and plainlanguage.gov — short sentences, strong verbs, defined terms, front-loaded points, and consistent terminology. -- **Precision preservation**: editing the prose around normative keywords, - identifiers, quantities, and defined terms while leaving those tokens - exactly as written. +- **Precision preservation**: editing the prose around protected tokens such as + normative keywords, identifiers, quantities, and defined terms while leaving + those tokens exactly as written. ## Behavioral Constraints - You treat meaning as inviolable. You never trade technical accuracy for a shorter sentence. When clarity and precision conflict, you keep precision and record the residual readability issue. -- You never alter normative keywords (MUST, SHALL, SHOULD, MAY), code - identifiers, API signatures, numbers, units, requirement IDs, or defined - terms. You edit the prose around them. +- You never alter normative keywords (such as MUST, SHALL, SHOULD, MAY, + REQUIRED, OPTIONAL, and their negations), code identifiers, API signatures, + numbers, units, requirement IDs, or defined terms. You edit the prose around + them. - You are subordinate to evidence discipline. You do not delete epistemic labels, citations, assumptions, or uncertainty disclosures that another protocol requires; you improve the prose that carries them. diff --git a/protocols/guardrails/readability-gate.md b/protocols/guardrails/readability-gate.md index 549c983..7f09e58 100644 --- a/protocols/guardrails/readability-gate.md +++ b/protocols/guardrails/readability-gate.md @@ -190,10 +190,12 @@ Metrics: FRE , FKGL , Residual issues: ``` -Report this block to the user (or in the change summary). Do NOT inject the -block verbatim into the produced artifact. A consuming format MAY populate its -own existing scorecard fields from these metrics — that is not injecting the -block, and it keeps consuming formats unchanged and avoids format drift. +Report this block as chat or meta output to the user only. Do NOT inject the +block verbatim into the produced artifact — not even into an artifact's own +change-summary or scorecard section. A consuming format MAY populate its own +existing fields (for example a scorecard row) from these metrics; that is not +injecting the block, and it keeps consuming formats unchanged and avoids format +drift. ## Composability diff --git a/protocols/reasoning/readability-revision-workflow.md b/protocols/reasoning/readability-revision-workflow.md index e9d1aec..3ed5bc7 100644 --- a/protocols/reasoning/readability-revision-workflow.md +++ b/protocols/reasoning/readability-revision-workflow.md @@ -34,9 +34,11 @@ preservation of technical meaning. Record the tier and the signal that chose it. The proxy thresholds apply regardless of tier; the tier sets only the Flesch band. 2. **Bound the corpus.** Apply the readability corpus boundary from the - `readability-gate` protocol (Rule 1). Measure and revise only human-facing - prose. Leave code, data, markup, quoted text, normative keywords, - identifiers, requirement IDs, and defined terms untouched. + `readability-gate` protocol (Rule 1), which is the operative exclusion set. + Measure and revise only human-facing prose; leave everything Rule 1 excludes + unchanged — for example code, data, markup, URLs and file paths, logs and + error strings, diagrams, tables, quoted text, normative keywords, + identifiers, requirement IDs, and defined terms. 3. **Record scope.** Note what you will measure and what you will exclude, for the report's measurement-scope section. @@ -104,9 +106,12 @@ Plain-language rules: 6. Keep terminology consistent — one term per concept, not a rotation of synonyms. -Accuracy lock — never change, only edit prose around: +Accuracy lock — never change, only edit prose around the protected tokens +defined by the readability-gate corpus boundary (Rule 1). That boundary is +authoritative; the list below restates it and is not exhaustive: -- Normative keywords (MUST, SHALL, SHOULD, MAY and their negations). +- Normative keywords (MUST, SHALL, SHOULD, MAY, REQUIRED, OPTIONAL, and their + negations). - Code identifiers, API signatures, enum values, config keys, and CLI flags. - Numbers, units, and quantities. - Requirement IDs, section anchors and headings referenced elsewhere, and diff --git a/templates/revise-for-readability.md b/templates/revise-for-readability.md index f2ef83a..2851191 100644 --- a/templates/revise-for-readability.md +++ b/templates/revise-for-readability.md @@ -47,9 +47,11 @@ prose becomes short, direct, plain prose; technical meaning stays exact. ## Instructions 1. **Bound the corpus first.** Apply the `readability-gate` corpus boundary - (Rule 1). Measure and revise only human-facing prose. Leave code, YAML, - tables, identifiers, normative keywords, requirement IDs, citations, quoted - text, and anything named in {{constraints}} exactly as written. + (Rule 1), which is the operative exclusion set. Measure and revise only + human-facing prose; leave everything Rule 1 excludes unchanged — for example + code, YAML, tables, URLs and file paths, logs and error strings, diagrams, + identifiers, normative keywords, requirement IDs, citations, and quoted + text — plus anything named in {{constraints}}. 2. **Set the target from the audience.** Select the tier with the `readability-gate` tier-selection ladder (Rule 3): classify @@ -110,7 +112,7 @@ Before finalizing, verify: - [ ] Scorecard shows before and after values for every metric, with target and status - [ ] Every protected token (normative keywords, identifiers, requirement IDs, - quantities, defined terms, citations, quoted text) is unchanged + quantities, defined terms, citations, quoted text, and others) is unchanged - [ ] Every required epistemic label and citation from the source is preserved - [ ] Change summary reports only categories that had edits, with representative examples From 1d26569c42b682e660dab9a2949e29df9288bd28 Mon Sep 17 00:00:00 2001 From: Andrew Beltrano Date: Thu, 9 Jul 2026 10:30:37 -0600 Subject: [PATCH 5/6] Resolve Expert-tier Flesch contradiction and clarify metric source MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Address fourth round of PR review feedback and a self-audit for internal contradictions. - readability-gate: reconcile the pass criteria with the Expert-tier "loose floor" note — for the Expert tier the proxy thresholds are authoritative and a missed Flesch band is recorded as a residual issue rather than failing the gate - readability-revision-report: rename "Metric source" to "Flesch metric source" and note that proxy metrics are always measured - revise-for-readability: align the quality-checklist wording to "Flesch metric source" Self-audit confirmed proxy thresholds and Flesch bands are otherwise consistent across the gate, workflow, format, and template. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- formats/readability-revision-report.md | 2 +- protocols/guardrails/readability-gate.md | 10 ++++++---- templates/revise-for-readability.md | 4 ++-- 3 files changed, 9 insertions(+), 7 deletions(-) diff --git a/formats/readability-revision-report.md b/formats/readability-revision-report.md index 036434c..e3f234d 100644 --- a/formats/readability-revision-report.md +++ b/formats/readability-revision-report.md @@ -35,7 +35,7 @@ headings, code blocks, tables, and identifiers; only the prose is revised.> - **Excluded**: - **Audience tier**: Broad | General-technical | Expert (target: FRE ≥ , FKGL ≤ ); basis: stated audience | document purpose | default -- **Metric source**: Computed () | Not measured +- **Flesch metric source**: Computed () | Not measured — proxy metrics are always measured (Rule 2) ## 3. Readability Scorecard diff --git a/protocols/guardrails/readability-gate.md b/protocols/guardrails/readability-gate.md index 7f09e58..22d6a75 100644 --- a/protocols/guardrails/readability-gate.md +++ b/protocols/guardrails/readability-gate.md @@ -144,10 +144,12 @@ unavoidable domain vocabulary depresses the score regardless of clarity. on first use. The gate passes when the proxy thresholds hold and, if computed scores are -available, the tier's Flesch band is met. Where a threshold cannot be met without -losing precision (for example, a sentence that must name several protected -terms), the gate passes only if that sentence is listed as a justified -residual issue with the reason it cannot be shortened. +available, the tier's Flesch band is met. For the Expert tier the proxy +thresholds are authoritative: report the Flesch scores, but a missed Flesch band +does not by itself fail the gate — record it as a residual issue instead. Where a +proxy threshold cannot be met without losing precision (for example, a sentence +that must name several protected terms), the gate passes only if that sentence is +listed as a justified residual issue with the reason it cannot be shortened. ## Rule 4: Accuracy and Precedence Carve-Outs diff --git a/templates/revise-for-readability.md b/templates/revise-for-readability.md index 2851191..0976d8b 100644 --- a/templates/revise-for-readability.md +++ b/templates/revise-for-readability.md @@ -107,8 +107,8 @@ Before finalizing, verify: - [ ] The Revised Document section (report Section 1) contains the full revised document, usable as-is -- [ ] Measurement scope lists what was included and excluded, and the metric - source (computed / not measured) +- [ ] Measurement scope lists what was included and excluded, and the Flesch + metric source (computed / not measured) - [ ] Scorecard shows before and after values for every metric, with target and status - [ ] Every protected token (normative keywords, identifiers, requirement IDs, From fb996289aa12e15ed5ec54f52b639646102033fd Mon Sep 17 00:00:00 2001 From: Andrew Beltrano Date: Thu, 9 Jul 2026 10:50:49 -0600 Subject: [PATCH 6/6] Reconcile no-add-content constraint with defining undefined terms Address the internal contradiction between the "do not add or remove content" constraint and the requirement to eliminate undefined terms on first use. - revise-for-readability: clarify Non-Goals so a minimal definition or acronym expansion that restates existing meaning counts as prose revision, not new content - readability-revision-workflow: plain-language rule 4 now allows definitions only when they restate meaning already present; otherwise the undefined term is recorded as a residual issue Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- protocols/reasoning/readability-revision-workflow.md | 5 ++++- templates/revise-for-readability.md | 7 +++++-- 2 files changed, 9 insertions(+), 3 deletions(-) diff --git a/protocols/reasoning/readability-revision-workflow.md b/protocols/reasoning/readability-revision-workflow.md index 3ed5bc7..ff7e5ab 100644 --- a/protocols/reasoning/readability-revision-workflow.md +++ b/protocols/reasoning/readability-revision-workflow.md @@ -101,7 +101,10 @@ Plain-language rules: 1. One idea per sentence. Split a sentence that carries more than one. 2. Front-load the point. State the conclusion or action first, then the detail. 3. Prefer the plain word ("use" over "utilize", "help" over "assist"). -4. Define a needed term or expand an acronym on first use. +4. Define a needed term or expand an acronym on first use, but only by restating + meaning already present in or established by the document. If a correct + definition would introduce information not derivable from the source, do not + invent it — record the undefined term as a residual issue instead. 5. Vary sentence length so the rhythm is not a drone. 6. Keep terminology consistent — one term per concept, not a rotation of synonyms. diff --git a/templates/revise-for-readability.md b/templates/revise-for-readability.md index 0976d8b..1972120 100644 --- a/templates/revise-for-readability.md +++ b/templates/revise-for-readability.md @@ -96,8 +96,11 @@ prose becomes short, direct, plain prose; technical meaning stays exact. edit the prose around them. - Do NOT rewrite code, data, tables, diagrams, quoted text, or format scaffolding. -- Do NOT restructure the document, reorder sections, or add or remove content; - this task revises prose, it does not redesign the document. +- Do NOT restructure the document, reorder sections, or add or remove + substantive content or claims; this task revises prose, it does not redesign + the document. Adding a minimal definition or acronym expansion that restates + meaning already present in the source counts as prose revision, not new + content. - Do NOT report an estimated Flesch score as a computed one, and do NOT claim a readability gain without a before/after comparison.