Plain Language Review
Review text files against the U.S. federal government Plain Language Guidelines (~30 rules across 6 categories) and produce a structured report of findings with concrete rewrites.
Important: This skill produces a report. Do not modify any reviewed files.
Review Workflow
- Select files — Use the user's specified files. If none specified, run
scripts/scan-plaintext-files.sh <project-directory>to discover all.md,.mdx,.markdown,.txt,.rtf,.rst,.adoc,.org, and.wikifiles. The<project-directory>argument is required — it must be the root of the user's project (the repository being reviewed), NOT the skill's own directory. - Load rules — Read
references/rules-quick-ref.mdfor the full rule checklist. - Review each file — For each file, read it and apply all rules. Skip text inside code blocks/fences, inline code, and code-only files. Only review human-readable prose.
- Generate findings — For each issue found, produce a finding using the Output Format below.
- Classify severity — Use
references/severity-rubric.mdto assign high/medium/low. - Verify rewrites — For each suggested rewrite, confirm it resolves the flagged rule violation and does not introduce new violations. If a rewrite still triggers the same or a different rule, revise it before including it in the report.
- Assemble report — Write findings to
plain-language-findings-YYYYMMDD.mdin the project root (use today's date). Group findings by file, then by severity (high first). End with the summary block.
Output Format
Use this exact structure for each finding:
## [file path]
### Finding [N] — [Rule name] (severity: [high|medium|low])
- **Line [N]:** "[original text]"
- **Guideline:** [One-sentence explanation of the rule violated]
- **Suggested:** "[concrete rewrite]"
Example:
## docs/getting-started.md
### Finding 1 — Use simple words (severity: medium)
- **Line 14:** "In order to utilize the configuration module..."
- **Guideline:** Replace complex words with simple alternatives — "utilize" → "use", "in order to" → "to"
- **Suggested:** "To use the configuration module..."
### Finding 2 — Use active voice (severity: high)
- **Line 23:** "The database will be initialized by the setup script."
- **Guideline:** Make the actor the subject of the sentence
- **Suggested:** "The setup script initializes the database."
If a file has no findings, omit it from the report entirely — do not list it.
End the report with a summary:
## Summary
- **Files reviewed:** [N]
- **Total findings:** [N] ([N] high, [N] medium, [N] low)
- **Top issues:** [List the 2-3 most frequent rule violations]
When to Load Reference Files
Load references on demand to conserve context:
| File | When to load |
|---|---|
references/rules-quick-ref.md | Always — load at start of every review |
references/word-substitutions.md | When checking word choice or when you encounter a word that might have a simpler alternative |
references/active-voice-guide.md | When you detect passive voice patterns (forms of "to be" + past participle) |
references/before-and-after-examples.md | When crafting suggested rewrites — use as transformation models |
references/severity-rubric.md | When classifying findings — consult definitions and examples |
Scope Rules
- Review: prose in
.md,.mdx,.markdown,.txt,.rtf,.rst,.adoc,.org,.wikifiles; comments in source code files; UI strings; error messages - Skip: code inside fences/backticks, variable names, import statements, configuration values, URLs, file paths
- Preserve technical terms — flag jargon only when a simpler alternative exists without losing precision
- Do not modify reviewed files — produce recommendations only
Attribution
The plain language guidelines and examples referenced by this skill originate from the U.S. federal government's Plain Language initiative, maintained by the General Services Administration (GSA). All guideline content is U.S. government work in the public domain. Source: https://digital.gov/guides/plain-language