Add readability revision capability for clearer technical docs

formats/readability-revision-report.md

@@ -0,0 +1,95 @@
+<!-- SPDX-License-Identifier: MIT -->
+<!-- Copyright (c) PromptKit Contributors -->
+
+---
+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
+# <Document Title> — Readability Revision
+
+## 1. Revised Document
+<The full revised document, ready to use. Preserve all original structure,
+headings, code blocks, tables, and identifiers; only the prose is revised.>
+
+## 2. Measurement Scope
+- **Included**: <the prose that was measured and revised>
+- **Excluded**: <code, YAML, tables, identifiers, normative keywords,
+  requirement IDs, citations, quoted text, and other protected tokens>
+- **Audience tier**: Broad | General-technical | Expert (target: FRE ≥ <n>, FKGL ≤ <n>); basis: stated audience | document purpose | default
+- **Flesch metric source**: Computed (<tool/library>) | Not measured — proxy metrics are always measured (Rule 2)
+
+## 3. Readability Scorecard
+
+| Metric | Before | After | Target | Status |
+|--------|--------|-------|--------|--------|
+| Flesch Reading Ease | <value / not measured> | <value / not measured> | ≥ <band> | Met / Not met / Not measured |
+| Flesch-Kincaid Grade Level | <value / not measured> | <value / not measured> | ≤ <band> | Met / Not met / Not measured |
+| Mean sentence length (words) | <n> | <n> | ≤ 20 | Met / Not met |
+| Longest sentence (words) | <n> | <n> | ≤ 40 | Met / Not met |
+| Sentences > 25 words | <n>% | <n>% | ≤ 15% | Met / Not met |
+| Passive-voice sentences | <n>% | <n>% | ≤ 20% | Met / Not met |
+| Expletive constructions | <n> | <n> | 0 | Met / Not met |
+| Filler / hedge occurrences | <n> | <n> | 0 | Met / Not met |
+| Undefined terms on first use | <n> | <n> | 0 | Met / Not met |
+
+**Gate result**: PASS | REVISE
+
+## 4. Change Summary
+<Grouped by defect category, with a count and one or two representative
+before -> after examples per category. Report only categories that had edits.
+Format each category as:>
+
+### <Defect category> (<count>)
+- Before: "<original phrase>"
+- After: "<revised phrase>"
+
+## 5. Accuracy Attestation
+<State that every protected token (normative keywords, identifiers, requirement
+IDs, quantities, defined terms, citations, quoted text, and other protected
+tokens) is unchanged.
+
+**High-risk edits**: any edit a reviewer should confirm because it could carry a
+meaning change. For each: the location, the before -> after text, and why it is
+low risk. If none, state "None identified".>
+
+## 6. Residual Issues
+<Sentences that could not be simplified without touching a protected element or
+losing precision. For each: the location, the reason it was left, and the metric
+it fails. If none, state "None identified".>
+```
+
+## 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.
+  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
+  revision; do not estimate or approximate counts.
+- The Accuracy Attestation and Residual Issues sections MUST be present even
+  when empty, stated as "None identified".

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

personas/plain-language-editor.md

@@ -0,0 +1,57 @@
+<!-- SPDX-License-Identifier: MIT -->
+<!-- Copyright (c) PromptKit Contributors -->
+
+---
+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 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 (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.
+- 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.