Plain Language

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

1. Select files — Use the user's specified files. If none specified, run scripts/scan-files.sh <project-directory> to discover all .md, .mdx, .txt, .rst, and .adoc files. 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.
2. Load rules — Read references/rules-quick-ref.md for the full rule checklist.
3. 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.
4. Generate findings — For each issue found, produce a finding using the output format below.
5. Classify severity — Use references/severity-rubric.md to assign high/medium/low.
6. 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.
7. Assemble report — Group findings by file, then by severity (high first).

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:

Key Rules by Priority

Critical (always flag):

• Use simple words and phrases (check against the Dirty Dozen first)
• Avoid jargon (unnecessary complexity, not legitimate technical terms)
• Use active voice (passive voice hides responsibility)

High (flag unless context justifies):

• Avoid hidden verbs ("make a determination" → "determine")
• Use terms consistently (don't synonym-swap)
• Write short sentences (~20 words)
• Keep subject-verb-object close together
• Use present tense
• Use "must" not "shall" for requirements
• Address the user ("you")
• Place main idea before exceptions

Medium (flag with lighter touch):

• Avoid noun strings (3+ stacked nouns)
• Minimize abbreviations
• Write short paragraphs and sections
• Use lists for series
• Use positive language (avoid double negatives)
• Add useful headings
• Cut excess modifiers (really, very, basically, totally, etc.)
• Avoid doublets and triplets ("cease and desist" → "stop", "null and void" → "void")
• Use general-to-specific order (broad info first, specialized details later)
• Use chronological order for processes (steps in the sequence users follow)

Low (note, don't belabor):

• Use contractions where natural (context-dependent)
• Don't use slashes ("and/or")
• Minimize cross-references

Scope Rules

• Review: prose in .md, .mdx, .txt, .rst, .adoc files; comments in source code files; UI strings; error messages
• Skip: code inside fences/backticks, variable names, import statements, configuration values, URLs, file paths
• Don't rewrite files — produce recommendations only. The human or agent decides what to apply.
• Preserve technical terms — flag jargon only when a simpler alternative exists without losing precision. "Brinulator valve" is fine; "utilize the brinulator valve" is not.

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