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 the user has not specified files or a project directory, ask them before proceeding — do not default to the current working directory. If none specified, run
scripts/scan-plaintext-files.sh <project-directory> to discover all .md, .mdx, .markdown, .txt, .rtf, .rst, .adoc, .org, and .wiki 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.
- Load rules — Read
references/rules-quick-ref.md for the full rule checklist.
- Review files in parallel — Spawn parallel sub-agents (via the Task tool — see Model & Effort Guidance for tier selection) to review files concurrently. Batch files into groups of 3–5 per sub-agent. Each sub-agent receives: the list of files to review, the rules from
references/rules-quick-ref.md, and instructions to apply all rules, verify each rewrite resolves the flagged violation without introducing new ones, and produce findings in the Output Format below. Run up to 5 sub-agents concurrently. Once all complete, collect their findings. If a sub-agent fails, log the error and continue — do not block the rest of the review.
- Collect and deduplicate findings — Gather findings from all sub-agents. Remove exact duplicates if file batches overlapped. For each finding, verify the rewrite resolves the flagged rule violation and does not introduce new violations.
- Classify severity — Use
references/severity-rubric.md to assign high/medium/low.
- Assemble report — Write findings to
.agents/plain-language/plain-language-findings-YYYYMMDD.md (create the directory if it doesn't exist; use today's date). Group findings by file, then by severity (high first). End with the summary block.
Model & Effort Guidance
| Task |
Model tier |
Rationale |
| File discovery (script) |
None — run scripts/scan-plaintext-files.sh |
Deterministic shell script; no model needed. |
| File-review sub-agents |
Fast cheap model (e.g. Claude Haiku 4.5, Gemini Flash 2.5) |
Rule application is structured pattern matching against a fixed checklist. |
| Orchestration, rewrite verification, severity classification |
Capable reasoning model (e.g. Claude Sonnet 4.5, Gemini 2.5 Pro) |
Judgment tasks: deduplication, severity calls, cross-finding coherence. |
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 include a "no issues found" entry. The summary's "Files reviewed" count should still include 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 reviewing word choice in any finding |
references/active-voice-guide.md |
When you detect passive voice patterns (forms of "to be" + past participle) |
references/before-and-after-examples.md |
When a rewrite requires restructuring (sentence split, list conversion, undoing a hidden verb, or reorder) rather than a simple word swap |
references/severity-rubric.md |
When classifying findings — consult definitions and examples |
Scope Rules
- Review: prose in
.md, .mdx, .markdown, .txt, .rtf, .rst, .adoc, .org, .wiki 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
- Plain-language review checks how text reads, not whether its claims about the code are accurate. For docs/code drift detection (does this README command still exist?), see
tidy-project's Phase 1 docs drift reviewer.
Gotchas
- Do not review files inside this skill's own directory — always use the user's project root, not the skill directory.
- Do not flag technical terms that have no simpler equivalent — precision beats plainness.
- Do not review text inside code fences, backticks, or inline code spans — only prose.
- A file with zero findings is still counted in "Files reviewed" — do not omit it from the summary count.
1---2name: plain-language3description: Use when asked to review project text for plain language compliance. Produces structured findings with rewrites. Triggers: plain language review, readability check, copy audit, make this clearer.4---5
6# Plain Language Review
7
8Review 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.
9
10**Important: This skill produces a report. Do not modify any reviewed files.**
11
12---
13
14## Review Workflow
15
161. **Select files** — Use the user's specified files. If the user has not specified files or a project directory, ask them before proceeding — do not default to the current working directory. If none specified, run `scripts/scan-plaintext-files.sh <project-directory>` to discover all `.md`, `.mdx`, `.markdown`, `.txt`, `.rtf`, `.rst`, `.adoc`, `.org`, and `.wiki` 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.
172. **Load rules** — Read `references/rules-quick-ref.md` for the full rule checklist.
183. **Review files in parallel** — Spawn parallel sub-agents (via the Task tool — see Model & Effort Guidance for tier selection) to review files concurrently. Batch files into groups of 3–5 per sub-agent. Each sub-agent receives: the list of files to review, the rules from `references/rules-quick-ref.md`, and instructions to apply all rules, verify each rewrite resolves the flagged violation without introducing new ones, and produce findings in the Output Format below. Run up to 5 sub-agents concurrently. Once all complete, collect their findings. If a sub-agent fails, log the error and continue — do not block the rest of the review.
194. **Collect and deduplicate findings** — Gather findings from all sub-agents. Remove exact duplicates if file batches overlapped. For each finding, verify the rewrite resolves the flagged rule violation and does not introduce new violations.
205. **Classify severity** — Use `references/severity-rubric.md` to assign high/medium/low.
216. **Assemble report** — Write findings to `.agents/plain-language/plain-language-findings-YYYYMMDD.md` (create the directory if it doesn't exist; use today's date). Group findings by file, then by severity (high first). End with the summary block.
22
23---
24
25## Model & Effort Guidance
26
27| Task | Model tier | Rationale |
28|------|-----------|-----------|
29| File discovery (script) | None — run `scripts/scan-plaintext-files.sh` | Deterministic shell script; no model needed. |
30| File-review sub-agents | Fast cheap model (e.g. Claude Haiku 4.5, Gemini Flash 2.5) | Rule application is structured pattern matching against a fixed checklist. |
31| Orchestration, rewrite verification, severity classification | Capable reasoning model (e.g. Claude Sonnet 4.5, Gemini 2.5 Pro) | Judgment tasks: deduplication, severity calls, cross-finding coherence. |
32
33---
34
35## Output Format
36
37Use this exact structure for each finding:
38
39```
40## [file path]
41
42### Finding [N] — [Rule name] (severity: [high|medium|low])
43- **Line [N]:** "[original text]"
44- **Guideline:** [One-sentence explanation of the rule violated]
45- **Suggested:** "[concrete rewrite]"
46```
47
48**Example:**
49
50```
51## docs/getting-started.md
52
53### Finding 1 — Use simple words (severity: medium)
54- **Line 14:** "In order to utilize the configuration module..."
55- **Guideline:** Replace complex words with simple alternatives — "utilize" → "use", "in order to" → "to"
56- **Suggested:** "To use the configuration module..."
57
58### Finding 2 — Use active voice (severity: high)
59- **Line 23:** "The database will be initialized by the setup script."
60- **Guideline:** Make the actor the subject of the sentence
61- **Suggested:** "The setup script initializes the database."
62```
63
64If a file has no findings, omit it from the report entirely — do not include a "no issues found" entry. The summary's "Files reviewed" count should still include it.
65
66End the report with a summary:
67
68```
69## Summary
70- **Files reviewed:** [N]
71- **Total findings:** [N] ([N] high, [N] medium, [N] low)
72- **Top issues:** [List the 2-3 most frequent rule violations]
73```
74
75---
76
77## When to Load Reference Files
78
79Load references on demand to conserve context:
80
81| File | When to load |
82|------|-------------|
83| `references/rules-quick-ref.md` | Always — load at start of every review |
84| `references/word-substitutions.md` | When reviewing word choice in any finding |
85| `references/active-voice-guide.md` | When you detect passive voice patterns (forms of "to be" + past participle) |
86| `references/before-and-after-examples.md` | When a rewrite requires restructuring (sentence split, list conversion, undoing a hidden verb, or reorder) rather than a simple word swap |
87| `references/severity-rubric.md` | When classifying findings — consult definitions and examples |
88
89---
90
91## Scope Rules
92
93- **Review:** prose in `.md`, `.mdx`, `.markdown`, `.txt`, `.rtf`, `.rst`, `.adoc`, `.org`, `.wiki` files; UI strings; error messages
94- **Skip:** code inside fences/backticks, variable names, import statements, configuration values, URLs, file paths
95- **Preserve technical terms** — flag jargon only when a simpler alternative exists without losing precision
96- **Do not modify reviewed files** — produce recommendations only
97- Plain-language review checks how text reads, not whether its claims about the code are accurate. For docs/code drift detection (does this README command still exist?), see `tidy-project`'s Phase 1 docs drift reviewer.
98
99---
100
101## Gotchas
102
103- Do not review files inside this skill's own directory — always use the user's project root, not the skill directory.
104- Do not flag technical terms that have no simpler equivalent — precision beats plainness.
105- Do not review text inside code fences, backticks, or inline code spans — only prose.
106- A file with zero findings is still counted in "Files reviewed" — do not omit it from the summary count.
aibot88