danicat/speedgrapher/readability

Readability: jargon mitigation, deslopification & copyediting

readability turns dense, bureaucratic, or synthetic drafts into clear, human-authored technical prose. It combines three complementary disciplines:

1. The 4-Step HBR Framework to remove status-signaling jargon and raw acronyms while preserving technical accuracy.
2. The 5-Dimension AI Slop Purge (`deslopify`) to eliminate LLM clichés and re-establish natural syntax.
3. Per-Paragraph `fog` and `vale` Hotspot Remediation to fix density issues via Speedgrapher MCP metrics and `references/tropes-and-jargon.md`.

1. Why Technical Prose Gets Bogged Down: The HBR Jargon Insight

Writing loaded with jargon signals insecurity, not mastery. They found that professionals who feel low status lean on unexpanded acronyms and abstract vocabulary to manufacture authority. The strategy backfires: readers trust plain, concrete explanations more. In "Does Your Office Have a Jargon Problem?" (Harvard Business Review, March 2021), Zachariah Brown, Eric M. Anicich, and Adam D. Galinsky analyzed thousands of texts to track why people hide behind buzzwords.

Functional Precision vs. Status-Signaling Jargon

Technical copyediting must never "dumb down" real engineering concepts. Before cutting a technical term, classify it into one of two buckets:

The 4-Step HBR Jargon Mitigation Framework

Apply these four steps from the HBR framework to every document you edit:

1. Start at the Top (Unambiguous Titles & Opening Leads):

• Strip insider code names, unexpanded acronyms, and buzzword stacks from the document title, frontmatter summary/description, and the opening 150-word lead block so any technical reader immediately grasps the topic.

1. Identify Jargon Tripwires & Unexpanded Acronyms:

• Scan for clusters of three or more consecutive multi-syllable nouns ("resource utilization optimization strategy") and undefined initialisms ("E2E CIL SLOs").

1. Check Yourself (Plain-English Substitutions & First-Use Definitions):

• Expand unfamiliar acronyms on first use (for example, "extended Berkeley Packet Filter (eBPF)" or "Generative Engine Optimization (GEO)"), while leaving universally understood primitives (HTTP, JSON, CPU, API, URL, CLI, SQL) unexpanded unless writing for beginners.
• Replace every corporate verb (utilize, leverage, operationalize, facilitate) with its direct plain-English equivalent (use, run, help).

1. Write to Be Understood, Not to Impress:

• Whenever a sentence hides a simple engineering trade-off behind formal passive abstractions ("A determination was made to effectuate memory reclamation"), rewrite it with an explicit subject and active verb ("The collector frees unused heap buffers every five seconds").

2. The 5-Dimension AI Slop Purge (deslopify)

When speedgrapher's slop MCP tool audits a file, it scores synthetic phrasing from 0 to 100 across five dimensions. Load `references/tropes-and-jargon.md` and purge every matched pattern:

3. Deterministic 4-Step Readability & Copyediting Workflow

Execute this four-step loop whenever improving a file's readability or deslopifying a draft:

flowchart LR
    Step1["1. Baseline Telemetry\nRun `fog`, `slop` & `vale`\n+ load `tropes-and-jargon.md`"] --> Step2["2. HBR Jargon & Slop Purge\nCut status jargon, tropes &\nunexpanded acronyms"]
    Step2 --> Step3["3. Paragraph Hotspot Surgery\nAddress paragraphs outside 12–14\nand resolve grammar spans"]
    Step3 --> Step4{"4. Verification Gate\n`slop` < 20, `fog` 12–14,\ngrammar fixed?"}
    Step4 -->|No| Step2
    Step4 -->|Yes| Done["Deliver Clean Text +\nSpeedgrapher Pill"]

Step 1: Baseline Telemetry (fog, slop, vale)

Run fog, slop, and vale on the target .md file and load `references/tropes-and-jargon.md`:

• Inspect both the document-wide scores and the per-paragraph `paragraphs[]` breakdown (start_line, end_line, fog, slop, classification) returned by fog and slop.
• Identify specific paragraph hotspots (paragraphs where fog > 16.0 or slop >= 25) and exact vale line/column alerts so you only rewrite paragraphs that need work rather than churning clean sections.

Step 2: HBR Jargon & AI Trope Purge

Apply the 4-Step HBR Jargon Mitigation Framework and the diagnostic tables in `references/tropes-and-jargon.md`:

• Replace status-signaling buzzwords and bureaucratic noun stacks with plain verbs and exact system actors.
• Expand unfamiliar domain acronyms on first mention.
• Strip lexical tells (delve, tapestry, landscape, leverage, utilize, robust, seamless), magic adverbs (quietly, deeply, merely, simply), negative parallelisms ("It's not X, it's Y"), and em dashes (— or --).

Step 3: Per-Paragraph fog & vale Hotspot Surgery

For every paragraph flagged in paragraphs[] or by vale:

• When Paragraph `fog` is Outside Target Range (12.0–14.0):
• Check readability balance to keep paragraph density aligned with the 12.0–14.0 target range.
• When `vale` Reports Alerts:
• Vale grammar checks must always be fixed.
• Vale style checks are informational and must be presented to the user for discussion.
• If a vale rule produces a genuine false positive on a domain term across the project, note that the author can mute the rule or add the term to the custom vocabulary via the Mute Rule / + Add to Vocab buttons in the alert popover, or the ⚙️ Settings modal in Speedgrapher.

Step 4: Verification Gate

Re-run fog, slop, and vale on the edited file to verify measurable improvement:

• Target `slop` Score: $< 20$ (never finish with a Slop Score $\ge 25$).
• Target `fog` Index: $12.0\text{–}14.0$ overall.
• Target `vale` Status: All grammar checks fixed; style checks presented to user for discussion.
• Report a concise Before $\rightarrow$ After Telemetry Table (fog, slop, and vale counts) and surface [file.md](sidecar://speedgrapher/panel/?file=/absolute/path/to/file.md).

4. Before & After Transformation Example

Before (slop: 68 | fog: 19.2 | Status-Signaling Jargon + AI Tropes)

In today's fast-paced distributed systems landscape, observability isn't just a nice-to-have — it's a foundational paradigm. Let's delve into how our E2E telemetry orchestration methodology quietly utilizes L7 CIL ring buffers to operationalize trace collection.

Here's the kicker: traditional head-based sampling strategies leverage naive probabilistic decisions. The result? Blind spots during critical latency spikes.

- Resilience: Leverages lock-free ring buffers to prevent data loss.

- Efficiency: Seamlessly compresses spans before network transmission.

- Scalability: Serves as a robust catalyst for high-cardinality debugging.

After (slop: 6 | fog: 13.1 | Functional Precision + Clean Human Cadence)

Head-based trace sampling drops 99% of requests at ingress, which often discards the exact traces needed to debug a p99 latency spike. To capture every slow or failing request without storing every healthy one, we moved our sampling decision to the collector tier.

Each collector holds spans in a lock-free ring buffer for five seconds while waiting for the root span to finish. If any span in the trace records an HTTP 5xx status or exceeds 250 ms, the collector compresses the full trace with Zstandard and flushes it to storage. Otherwise, it drops the buffer. Across 140 Go services in production, this tail-based pipeline cut trace storage volume by 62% while keeping 100% of error traces.

Operational Constraints

• Zero Silent Edits & Explicit User Sign-Off: Never overwrite files on disk or rewrite user prose directly without explicit confirmation. Present all suggested adjustments as a numbered list of line-indexed recommendations and wait for user approval before applying.
• Preserve Technical Accuracy: Never alter code blocks, CLI flags, benchmark numbers, API signatures, or URLs while copyediting surrounding prose.
• Preserve Author Voice: Strip status-signaling jargon and synthetic LLM tropes without flattening the author's natural personality, dry humor, colloquialisms, or first-person engineering stories. Never let rigid linter rules sanitize authentic human voice.
• Strictly No Em Dashes: Never use em dashes (— or --) as mid-sentence connectors. Break thoughts into clean, crisp sentences using periods, commas, or colons.
• No Git Operations: Never execute git commit, git push, or other repository mutation commands.