| name | prose-audit |
| description | Scans content for filler words, hedging, unsubstantiated claims, and redundancy. Produces a line-level issue list with specific replacements or deletions. Use after writing or revising content to tighten prose before shipping. Activates when auditing prose quality, cutting filler, removing noise, or tightening language across one or more MDX content pages. |
| compatibility | Designed for Claude Code. Requires file read access. |
| metadata | {"author":"solutions-architecture","version":"1.0"} |
Prose Audit
Scan content pages for filler, noise, and unsubstantiated claims. Produce a line-level edit list.
When to Use
Run this after content-evaluation scores a page, or after a batch of pages have been written/revised. Content-evaluation judges what's on the page. Prose audit judges how it's said — sentence by sentence.
Principles
- Delete filler, don't replace it. "Simple keyword search" -> "Keyword search". Don't swap one adjective for another.
- Kill unsubstantiated claims. "A complete support agent" -> "A support agent". If you can't prove it, don't say it.
- Cut hedging. "In practice," "In general," "typically" — remove unless the hedge distinguishes a common case from an edge case.
- Remove redundancy. If the code shows it, the prose doesn't need to repeat it. If the heading says it, the first sentence doesn't need to restate it.
- Preserve voice. The site has personality ("dead silence", "scratch paper"). Cut noise, not character. Informal is fine; unsubstantiated is not.
Procedure
- Determine scope. If a specific file is given, audit that file. If no file is given, audit all MDX files in
src/content/docs/.
- Read each file and scan every prose line (skip code blocks, frontmatter, and import statements).
- Two-pass scan:
- Pass 1 — Sentence-level: Flag whole-sentence issues: redundant summaries, paragraphs that restate code, heading-first-sentence duplication.
- Pass 2 — Intra-sentence: Re-read each prose line looking for filler within otherwise-good sentences: unnecessary adjectives ("high-level", "simple", "complete"), padding phrases ("from scratch", "in isolation", "the growing ecosystem of"), and hedges that don't earn their place. These are easy to miss on the first pass because the sentence reads fine — but it reads tighter without them.
- Context check: For each flagged issue, verify the word/phrase is actually noise in context. A word is filler only if removing it loses nothing the reader doesn't already have from the surrounding sentence, heading, or code. Check: is this word establishing a definition? Setting up a contrast with evidence in the next paragraph? Providing a specific number/example? If so, don't flag it.
- Flag issues using the pattern categories below. Record the file path, line number, the problematic text, and the recommended fix (replacement or deletion).
- Calibrate before output. Review the full findings list and ask: "Would applying ALL of these make the page better, or would some make it robotic?" Demote borderline cases to a separate "Borderline" section below the main findings table. A clean page should have few findings — don't invent issues to fill the report.
- Output the audit in the format below.
- Do NOT apply edits automatically. Present the findings for review first. Edits are applied in a separate step after the user approves.
Pattern Categories
Filler Words & Phrases
Words that add length without meaning. Delete them.
| Pattern | Example | Fix |
|---|
| "simple/simply" (when not contrasting with complex) | "Simple keyword search" | "Keyword search" |
| "just" (minimizer) | "just pass the parameter" | "pass the parameter" |
| "basically/essentially/actually/really" | "essentially a wrapper" | "a wrapper" |
| "very/quite/rather/somewhat" | "very important" | "important" |
| "in order to" | "in order to connect" | "to connect" |
| "a number of" | "a number of issues" | "several issues" or a specific count |
| "the fact that" | "due to the fact that" | "because" |
| "it should be noted that" | — | Delete entire phrase |
| "as mentioned earlier/above" | — | Delete or link directly |
| "from scratch" | "build it from scratch" | "build it" or "write custom code" |
| "high-level" (when not contrasting with low-level) | "a high-level class" | "a class" |
| "in isolation" | "test in isolation" | "test locally" or just "test" |
| "the growing ecosystem of" | "the growing ecosystem of MCP servers" | "MCP servers" |
| "automatically" (when obvious from context) | "passes it automatically" | "passes it" |
Hedging (remove unless meaningful)
Hedges that don't distinguish common from edge cases.
| Pattern | When to cut | When to keep |
|---|
| "In practice," | Opening filler | When contrasting with theory |
| "In general," | Opening filler | When listing exceptions next |
| "typically/usually/often" | Vague softener | When the next sentence covers the atypical case |
| "can/may/might" (triple hedge) | "This can sometimes help" | "This may fail if X" (real caveat) |
| "tends to" | "tends to be faster" | Keep if benchmarked |
Unsubstantiated Claims
Superlatives and absolutes without evidence. Downgrade or delete. Two levels:
Word-level — adjectives/adverbs that inflate:
| Pattern | Example | Fix |
|---|
| "complete/comprehensive/full" | "A complete guide" | "A guide" |
| "dramatically/significantly/vastly" | "dramatically improves" | "improves" or cite a number |
| "perfectly/exactly" | "demonstrates this perfectly" | "demonstrates this" |
| "always/never" (unless literally true) | "always outperforms" | "often outperforms" or cite evidence |
| "the best/the most" | "the best approach" | "a strong approach" or justify |
| "every major" | "every major pattern" | "patterns from across" |
| "consistently outperforms" | — | "often beats" unless benchmarked |
Sentence-level — whole sentences that overclaim without evidence:
| Pattern | Example | Fix |
|---|
| "X matters more than Y" (opinion as fact) | "Reliability matters more than elegance" | "Workflows are more reliable" (state the fact, not the value judgment) |
| "pays for itself" / "ship with confidence" | Marketing language in technical content | Rewrite with the concrete benefit: "catches regressions before users do" |
| "the first time you..." (anecdotal) | "pays for itself the first time you catch a bug" | Cut the anecdote, state the benefit directly |
| "X is the basis for Y" (grandiose framing) | "This is the basis for confident prompt development" | "This is empirical prompt development" |
Redundancy
Information stated twice in different forms.
| Pattern | Example | Fix |
|---|
| Heading + first sentence restatement | Heading: "Budget Sizing" / First line: "This section covers budget sizing" | Cut the first line |
| Code + prose duplication | Code shows a loop; prose says "the code loops through" | Cut the prose |
| Summary after code block | "The flow: discover tools, pass them..." when the code just showed this | Delete the summary |
| "Development workflow:" followed by obvious steps | — | Delete if steps are visible from context |
| Double instruction | "Copy and paste the script. Set API_KEY and run." | "Set API_KEY and run." |
Output Format
# Prose Audit: [scope description]
**Files scanned:** [count]
**Issues found:** [count]
## Issues by File
### [file path]
| Line | Category | Current Text | Recommended Fix |
| ---- | ---------- | ----------------------------- | ------------------------ |
| L9 | filler | "Simple keyword search" | "Keyword search" |
| L42 | claim | "dramatically improves" | "improves" |
| L118 | hedge | "In practice, adjusting" | "Adjusting" |
| L200 | redundancy | "The flow: discover tools..." | Delete (code shows this) |
### [next file]
...
## Summary
| Category | Count |
| ---------------------- | ----- |
| Filler | X |
| Hedging | X |
| Unsubstantiated claims | X |
| Redundancy | X |
| **Total** | **X** |
Applying Edits
After the user reviews the audit, apply approved edits using the Edit tool. Work file by file, top to bottom. For deletions, remove the text and any resulting double-spaces or orphaned punctuation.
Gotchas
- Don't over-trim. Informal voice is a feature. "Dead silence" and "scratch paper" are personality, not filler.
- Don't flag technical hedges. "This may fail if the server is unreachable" is a real caveat, not noise.
- Don't flag definitions or setup sentences. "X is a standard communication layer" is a definition, not a claim. Sentences that establish context for a code block or comparison table earn their place.
- Don't flag sentences backed by evidence on the same page. If a claim like "most tasks need workflows" is followed by a comparison table with specifics, the claim is supported — don't flag it.
- Don't count code comments. Only audit prose (paragraphs, callouts, list items, frontmatter descriptions).
- Context matters for "simple". "Simple" is filler when describing something already shown to be simple. It's meaningful when contrasting: "Start with a simple approach before adding complexity."
- Don't flag the same pattern in code blocks. Docstrings are fair game; inline code comments are not.
- Clean pages should stay clean. If a page has strong prose, report that. Don't stretch to find issues — a report with 1-2 findings is a valid result. Over-flagging erodes trust in the audit.
- Line numbers shift after edits. When presenting the audit, use the line numbers from the original file. When applying edits, re-read the file first.
