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 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.
2. Load rules — Read references/rules-quick-ref.md for the full rule checklist.
3. 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.
4. 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.
5. Classify severity — Use references/severity-rubric.md to assign high/medium/low.
6. 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.