Add readability revision capability for clearer technical docs#264
Open
abeltrano wants to merge 6 commits into
Open
Add readability revision capability for clearer technical docs#264abeltrano wants to merge 6 commits into
abeltrano wants to merge 6 commits into
Conversation
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>
Contributor
There was a problem hiding this comment.
Pull request overview
Note
Copilot was unable to run its full agentic suite in this review.
Adds a “revise-for-readability” capability (template + persona + protocols + report format) to support measured, meaning-preserving readability revisions of technical documents.
Changes:
- Introduces a new
revise-for-readabilitytemplate driven by a plain-language editor persona. - Adds a readability gate guardrail and a step-by-step readability revision workflow protocol.
- Defines a structured “readability revision report” output format and wires everything into
manifest.yaml.
Reviewed changes
Copilot reviewed 6 out of 6 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
| templates/revise-for-readability.md | New template that composes the persona, gate, workflow, and report format. |
| protocols/reasoning/readability-revision-workflow.md | New reasoning protocol defining the phased revision process. |
| protocols/guardrails/readability-gate.md | New guardrail describing corpus boundary, measurement rules, and pass criteria. |
| personas/plain-language-editor.md | New persona focused on measurable readability improvements without meaning drift. |
| formats/readability-revision-report.md | New output format for reporting the revised document + before/after metrics and attestations. |
| manifest.yaml | Registers the new persona, protocols, format, and template. |
- 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>
- 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>
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>
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>
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>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Add a readability-revision capability to PromptKit so technical documents can be
revised into clear, plain prose without changing their technical meaning. The
capability targets the Flesch readability scales, diagnoses named clarity
defects, and revises with established plain-language methods.
New Components
Design Decisions
final-pass check that can later be composed into authoring templates to make
their default output readable. The reasoning protocol
(readability-revision-workflow) carries the heavy corrective work for the
standalone template and delegates its acceptance check to the gate. One
methodology, no duplication.
reliably. When a code-execution tool is available (the common agentic launch
path), the gate computes the scores with a script — preferring textstat, else
the formulas with an embedded standard-library syllable heuristic. With no code
environment it reports Flesch as "not measured" and gates on reliably-countable
proxies (sentence length, passive share, expletives, filler, undefined terms),
which are always the primary gate.
(broad FRE ≥ 60 / FKGL ≤ 10; general-technical FRE ≥ 50 / FKGL ≤ 12; expert
FRE ≥ 40 / FKGL ≤ 14). The tier is selected by a ladder — a stated audience,
else inferred from the document's purpose via genre cues (never the draft's
current complexity, which would be circular), else general-technical — and the
report records which basis chose it. Proxy thresholds are audience-independent.
normative keywords, requirement IDs, citations, and quoted text from both
measurement and rewriting.
labels and citations required by anti-hallucination, and the register and
cadence preserved by human-voice-fidelity.
a taxonomy later if a second consumer or cross-document aggregation needs
shared labels.
existing authoring templates is a separate follow-up PR (this workflow does not
modify existing components).
Follow-up (separate PR)
Wire guardrails/readability-gate into the author-* template frontmatter so new
documents are readable by default. The gate is designed for this: it performs
only a final-pass prose check and preserves each template's own format and
semantics.
Validation
out on Windows local runs; reproduced identically with these changes stashed.
Checklist