From 9151fe225257d8fd11d513c788cc65241e35b262 Mon Sep 17 00:00:00 2001 From: Tom di Mino Date: Wed, 18 Feb 2026 23:56:49 -0500 Subject: [PATCH] Add register-aware rules, positive writing guidance, and expanded patterns MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add 5-register system (academic, technical, narrative, casual, professional) with per-register acceptable vs. flagged patterns and scoring adjustments - Add positive.md: what good writing does (specificity, active voice, rhythm, voice, reader trust) — not just what to avoid - Expand phrases.md with 8 new categories (~120 entries): AI vocabulary cluster, copula avoidance, significance inflation, promotional language, chatbot artifacts, filler phrases, academic hedging, sycophantic tone - Expand structures.md with 8 new patterns: format slop, -ing clauses, false ranges, rule-of-three overuse, synonym cycling, generic conclusions, challenges-and-prospects formula, knowledge-cutoff disclaimers - Expand examples.md with 9 register-specific before/after transformations - Rewrite SKILL.md with 3-step workflow (detect register → remove slop → score), 6-dimension scoring (added Specificity), clean frontmatter - Update README.md to reflect new structure and sources Sources: Antislop (Paech et al., ICLR 2026), Wikipedia AI Cleanup patterns, Strunk's Elements of Style, Claude prompting best practices Co-Authored-By: Claude Opus 4.6 --- README.md | 48 +++++++++---- SKILL.md | 81 +++++++++++++++------ references/examples.md | 139 ++++++++++++++++++++++++++++++++++++ references/phrases.md | 143 +++++++++++++++++++++++++++++++++++++ references/positive.md | 89 ++++++++++++++++++++++++ references/registers.md | 147 +++++++++++++++++++++++++++++++++++++++ references/structures.md | 103 +++++++++++++++++++++++++++ 7 files changed, 712 insertions(+), 38 deletions(-) create mode 100644 references/positive.md create mode 100644 references/registers.md diff --git a/README.md b/README.md index 126063d..8ebc310 100644 --- a/README.md +++ b/README.md @@ -1,23 +1,26 @@ # Stop Slop -A skill for removing AI tells from prose. +A skill for removing AI tells from prose. Register-aware — works across casual, professional, academic, technical, and narrative writing. G-Yg4RVbIAAhVxW ## What this is -AI writing has patterns. Predictable phrases, structures, rhythms. Once you notice them, you see them everywhere. This skill teaches Claude (or any LLM) to avoid them. +AI writing has patterns. Predictable phrases, structures, rhythms. Once you notice them, you see them everywhere. This skill teaches Claude (or any LLM) to avoid them — and replaces them with clear, specific, human-sounding prose. -## Skill Structure +## Skill structure ``` stop-slop/ -├── SKILL.md # Core instructions +├── SKILL.md # Core instructions (register detection → slop removal → scoring) ├── references/ -│ ├── phrases.md # Phrases to remove -│ ├── structures.md # Structural patterns to avoid -│ └── examples.md # Before/after transformations +│ ├── phrases.md # 200+ phrases to cut or replace (AI vocabulary, chatbot artifacts, jargon) +│ ├── structures.md # 14 structural patterns to avoid (format slop, synonym cycling, -ing clauses) +│ ├── positive.md # What good writing does (specificity, active voice, rhythm, voice) +│ ├── registers.md # Per-register rules (academic, technical, narrative, casual, professional) +│ └── examples.md # 14 before/after transformations across all registers ├── README.md +├── CHANGELOG.md └── LICENSE ``` @@ -33,29 +36,44 @@ stop-slop/ ## What it catches -**Banned phrases** — Throat-clearing openers, emphasis crutches, business jargon. See `references/phrases.md`. +**Phrases** — Throat-clearing openers, emphasis crutches, business jargon, AI vocabulary (delve, tapestry, multifaceted), chatbot artifacts, copula avoidance, significance inflation, sycophantic tone. See `references/phrases.md`. -**Structural clichés** — Binary contrasts, dramatic fragmentation, rhetorical setups. See `references/structures.md`. +**Structures** — Binary contrasts, dramatic fragmentation, rhetorical setups, format slop (emoji headings, inline-header lists), superficial -ing clauses, synonym cycling, rule-of-three overuse, generic conclusions, knowledge-cutoff disclaimers. See `references/structures.md`. -**Stylistic habits** — Tripling, immediate question-answers, metronomic endings. +**What to do instead** — Be specific, use simple constructions, active voice, vary rhythm, have a voice, trust readers, acknowledge complexity. See `references/positive.md`. + +## Register awareness + +Different writing contexts tolerate different patterns. The skill detects register from context and adjusts rules: + +| Register | Key adjustments | +|----------|----------------| +| Academic | Hedging OK when expressing epistemic uncertainty. Passive OK when agent unknown. | +| Technical | Bullets and headers OK. Promotional adjectives still flagged. | +| Narrative | Rhythm variation is a feature. Em dashes valid. Synonym cycling still flagged. | +| Casual | All rules at full force. | +| Professional | Similar to casual, tolerates more structure. | + +See `references/registers.md` for full details. ## Scoring -Rate 1-10 on each dimension: +Rate 1-10 on each dimension (adjusted for register): | Dimension | Question | |-----------|----------| | Directness | Statements or announcements? | | Rhythm | Varied or metronomic? | | Trust | Respects reader intelligence? | -| Authenticity | Sounds human? | +| Authenticity | Sounds human, not generated? | | Density | Anything cuttable? | +| Specificity | Claims backed by evidence? | -Below 35/50: revise. +Below 42/60: revise. -## Author +## Sources -[Hardik Pandya](https://hvpandya.com) +Based on [hardikpandya/stop-slop](https://github.com/hardikpandya/stop-slop) by [Hardik Pandya](https://hvpandya.com). Enhanced with register-aware rules, positive writing guidance, and expanded pattern coverage synthesized from Antislop (Paech et al., ICLR 2026), Wikipedia AI Cleanup patterns, and Strunk's *Elements of Style*. ## License diff --git a/SKILL.md b/SKILL.md index 18436c4..ef62745 100644 --- a/SKILL.md +++ b/SKILL.md @@ -1,53 +1,88 @@ --- name: stop-slop -description: Remove AI writing patterns from prose. Use when drafting, editing, or reviewing text to eliminate predictable AI tells. -metadata: - trigger: Writing prose, editing drafts, reviewing content for AI patterns - author: Hardik Pandya (https://hvpandya.com) +description: Remove AI writing patterns from prose. This skill should be used when drafting, editing, or reviewing text to eliminate predictable AI tells. Register-aware — handles casual, professional, academic, technical, and narrative writing. --- # Stop Slop -Eliminate predictable AI writing patterns from prose. +Eliminate predictable AI writing patterns. Produce clear, specific, human-sounding prose across any register. -## Core Rules +## Step 1: Detect register -1. **Cut filler phrases.** Remove throat-clearing openers and emphasis crutches. See [references/phrases.md](references/phrases.md). +Infer the register from context before applying rules. Different registers tolerate different patterns. -2. **Break formulaic structures.** Avoid binary contrasts, dramatic fragmentation, rhetorical setups. See [references/structures.md](references/structures.md). +| Signal | Register | +|--------|----------| +| Citations, methodology, "we hypothesize" | `academic` | +| API docs, READMEs, changelogs, error messages | `technical` | +| Fiction, essays, memoir, creative nonfiction | `narrative` | +| Blog posts, social media, emails | `casual` | +| Reports, proposals, business comms | `professional` | -3. **Vary rhythm.** Mix sentence lengths. Two items beat three. End paragraphs differently. +If the user specifies a register, use it. See [references/registers.md](references/registers.md) for per-register acceptable vs. flagged patterns. -4. **Trust readers.** State facts directly. Skip softening, justification, hand-holding. +## Step 2: Remove slop -5. **Cut quotables.** If it sounds like a pull-quote, rewrite it. +Apply these rules, adjusted for register: -## Quick Checks +1. **Cut filler phrases and AI vocabulary.** Remove throat-clearing openers, chatbot artifacts, significance inflation, and words that appear 100-1,000x more in LLM output than human text. See [references/phrases.md](references/phrases.md). -Before delivering prose: +2. **Break formulaic structures.** Avoid binary contrasts, dramatic fragmentation, format slop, synonym cycling, rule-of-three overuse, and generic conclusions. See [references/structures.md](references/structures.md). -- Three consecutive sentences match length? Break one. -- Paragraph ends with punchy one-liner? Vary it. -- Em-dash before a reveal? Remove it. -- Explaining a metaphor? Trust it to land. +3. **Use simple constructions.** Prefer "is" over "serves as." Prefer "has" over "boasts." Prefer "use" over "leverage." Active voice. Positive form. + +4. **Be specific.** Replace vague claims with dates, names, numbers, sources. "Significant improvement" becomes "latency dropped from 340ms to 90ms." + +5. **Vary rhythm.** Mix sentence lengths. Two items in a list beat three. End paragraphs differently from each other. + +6. **Trust readers.** State facts. Skip softening, justification, hand-holding. If a metaphor needs explaining, rewrite the metaphor. + +7. **Have a voice.** React to facts, don't just report them. Acknowledge complexity. Let personality through. -## Scoring +See [references/positive.md](references/positive.md) for what good writing does (not just what to avoid). -Rate 1-10 on each dimension: +## Step 3: Score + +Rate 1-10 on each dimension, adjusted for register: | Dimension | Question | |-----------|----------| | Directness | Statements or announcements? | | Rhythm | Varied or metronomic? | | Trust | Respects reader intelligence? | -| Authenticity | Sounds human? | +| Authenticity | Sounds human, not generated? | | Density | Anything cuttable? | +| Specificity | Claims backed by evidence? | + +Below 42/60: revise. -Below 35/50: revise. +**Register adjustments** (see [references/registers.md](references/registers.md)): +- `academic`: Do not penalize precise hedging or longer qualified sentences +- `technical`: Consistent structure in reference docs is not a rhythm flaw +- `narrative`: Indirection and dramatic rhythm variation are valid techniques -## Examples +## Quick checks + +Before delivering prose: -See [references/examples.md](references/examples.md) for before/after transformations. +- Three consecutive sentences match length? Break one. +- Paragraph ends with punchy one-liner? Vary it. +- Em-dash before a reveal? Remove it. +- Explaining a metaphor? Trust it to land. +- "Serves as," "stands as," "represents"? Rewrite with "is." +- -ing clause at end of sentence adding no information? Delete it. +- Three-item list? Try two items or one. +- Different words for the same thing in adjacent sentences? Pick one term and reuse it. + +## Reference files + +| File | Purpose | +|------|---------| +| [phrases.md](references/phrases.md) | Words and phrases to cut or replace | +| [structures.md](references/structures.md) | Structural patterns to avoid | +| [positive.md](references/positive.md) | What good writing does | +| [registers.md](references/registers.md) | Per-register rules and tolerances | +| [examples.md](references/examples.md) | Before/after transformations (all registers) | ## License diff --git a/references/examples.md b/references/examples.md index 0376b6d..6612df8 100644 --- a/references/examples.md +++ b/references/examples.md @@ -57,3 +57,142 @@ > "The best teams optimize for learning, not productivity." **Changes:** Direct claim. No rhetorical scaffolding. + +--- + +# Register-Specific Examples + +## Academic + +### Example 6: Significance Inflation + Vague Attribution + +**Register:** `academic` + +**Before:** +> "Scholars have long debated the relationship between Minoan and Semitic cultures, a multifaceted topic that underscores the importance of cross-cultural analysis. It is well-established that trade networks facilitated linguistic exchange, fostering a vibrant tapestry of shared cultural elements. This pivotal finding has profound implications for our understanding of Bronze Age connectivity." + +**After:** +> "Gordon (1966) and Astour (1967) proposed cognate links between Linear A sequences and West Semitic lexemes. Trade networks between Crete and the Levant are attested by LM I pottery at Ugarit and Canaanite amphora handles at Kommos. These finds suggest regular contact, though the degree of linguistic exchange remains unresolved." + +**Changes:** Named specific scholars. Replaced "well-established" with cited evidence. Cut "multifaceted," "tapestry," "pivotal," "profound"—all AI vocabulary. Replaced "fostering" -ing clause with concrete archaeological evidence. + +--- + +### Example 7: Academic Hedging Done Right vs. Wrong + +**Register:** `academic` + +**Before (wrong hedging):** +> "It could potentially be argued that the evidence may suggest a possible connection between the Minoan and Phoenician writing systems, which could have implications for further research." + +**After (precise hedging):** +> "The sign correspondence between Linear A *AB 04* and Proto-Sinaitic *bet* suggests a shared graphic ancestor, though the sample size (n=7 secure parallels) limits statistical confidence." + +**Changes:** Hedging should express genuine epistemic uncertainty with specifics, not stack qualifiers. "Could potentially be argued that... may suggest a possible" is four layers of nothing. One precise hedge ("suggests... though") with a stated reason ("sample size") is stronger. + +--- + +## Technical + +### Example 8: Promotional Adjectives + Buzzwords + +**Register:** `technical` + +**Before:** +> "Our cutting-edge, robust authentication module leverages state-of-the-art JWT handling to deliver a seamless, enterprise-grade security experience. This groundbreaking approach enhances the overall security posture of your application." + +**After:** +> "The auth module uses RS256-signed JWTs with automatic key rotation every 24 hours. Tokens expire after 15 minutes. Refresh tokens are stored in HttpOnly cookies with SameSite=Strict." + +**Changes:** Removed every promotional adjective. Replaced "leverages" with "uses." Replaced vague claims with specific configuration. "Cutting-edge," "robust," "seamless," "enterprise-grade," "groundbreaking"—none of these tell you what the code does. + +--- + +### Example 9: Format Slop — Inline-Header Vertical List + +**Register:** `technical` + +**Before:** +> **Key Features:** +> - **Blazing Fast Performance:** Our module processes requests with minimal latency +> - **Effortless Integration:** Simply drop in the middleware and you're good to go +> - **Rock-Solid Reliability:** Built to handle millions of requests without breaking a sweat + +**After:** +> The middleware processes requests in under 2ms at p99 (benchmarked on a 4-core VM with 1,000 concurrent connections). Add it to your Express pipeline with `app.use(authMiddleware())`. No configuration required for default settings. + +**Changes:** Replaced inline-header vertical list with prose. Removed promotional adjectives ("blazing fast," "effortless," "rock-solid"). Added a benchmark instead of asserting performance. Described integration concretely instead of vaguely. + +--- + +### Example 10: -ing Clauses in Technical Docs + +**Register:** `technical` + +**Before:** +> "The database migration adds a composite index on (user_id, created_at), ensuring reliability and enhancing query performance while showcasing the team's commitment to scalability." + +**After:** +> "The migration adds a composite index on (user_id, created_at). The `GET /users/:id/events` query drops from 340ms to 12ms on a table with 2M rows." + +**Changes:** Cut all three -ing clauses. They claimed outcomes without evidence. The after version gives the benchmark. + +--- + +## Narrative + +### Example 11: Synonym Cycling + Rule of Three + +**Register:** `narrative` + +**Before:** +> "The archaeologist descended into the chamber. The researcher paused at the threshold. The scholar steadied herself against the wall. The academic took a breath. Innovation, curiosity, and determination drove her forward." + +**After:** +> "She descended into the chamber, paused at the threshold, and steadied herself against the wall. She took a breath and kept moving." + +**Changes:** "Archaeologist," "researcher," "scholar," "academic"—four names for one person. Pick one and reuse it (or use a pronoun). Cut the rule-of-three abstract nouns. People don't think in triads of virtues; they just act. + +--- + +### Example 12: Generic Positive Conclusion + +**Register:** `narrative` + +**Before:** +> "As the sun set over the ancient ruins, she realized that the journey had changed her in ways she couldn't fully articulate. The future looked bright, full of endless possibilities. And maybe that was enough." + +**After:** +> "She sat on the broken wall and watched the sun go down. She didn't know what she'd found. She wasn't sure she wanted to." + +**Changes:** Cut "the future looked bright" and "endless possibilities"—generic positive closers. Cut "maybe that was enough"—false profundity. The rewrite lets ambiguity exist without announcing it. + +--- + +## Professional + +### Example 13: Business Jargon + Throat-Clearing + +**Register:** `professional` + +**Before:** +> "I wanted to circle back and take a step back to unpack the current landscape. Moving forward, we need to lean into the challenges and double down on our commitment to synergy across cross-functional teams." + +**After:** +> "Three problems from last quarter's review are still open. I'll send specifics by Thursday with a proposed owner for each." + +**Changes:** Seven jargon phrases in two sentences, zero information. The rewrite says what's happening, when, and who's responsible. + +--- + +### Example 14: Chatbot Artifacts in Professional Writing + +**Register:** `professional` + +**Before:** +> "Great question! I'd be happy to help with that. Here is an overview of the quarterly results. It's worth noting that revenue increased significantly. I hope this helps! Let me know if you have any questions." + +**After:** +> "Q4 revenue was $2.3M, up 18% from Q3. Full breakdown attached." + +**Changes:** Stripped five chatbot artifacts. Replaced "significantly" with a number. Professional writing respects the reader's time. diff --git a/references/phrases.md b/references/phrases.md index 6d964f3..f07f347 100644 --- a/references/phrases.md +++ b/references/phrases.md @@ -85,3 +85,146 @@ Announcing difficulty or significance rather than demonstrating it: - "This is genuinely hard" - "This is what leadership actually looks like" - "This is what X actually looks like" + +## AI Vocabulary Cluster + +Words that appear 100-1,000x more in LLM output than human text (per Antislop, Paech et al. 2025). Replace with plain alternatives or cut entirely. + +| Avoid | Use instead | +|-------|-------------| +| Delve | Examine, explore, look at | +| Tapestry (figurative) | Mix, combination, range | +| Multifaceted | Complex, varied | +| Nuanced | Subtle, detailed, complex | +| Foster | Encourage, support, build | +| Realm | Area, field, domain | +| Leverage (verb) | Use, apply | +| Interplay | Interaction, relationship | +| Intricate / intricacies | Complex, detailed | +| Pivotal | Important, key | +| Underscore (verb) | Show, emphasize | +| Garner | Gain, earn, attract | +| Enduring | Lasting, persistent | +| Showcase (verb) | Show, demonstrate | +| Vibrant | Lively, active | +| Testament | Evidence, proof | +| Enhance | Improve, strengthen | +| Align with | Match, fit, support | +| Crucial | Important, essential | +| Paramount | Critical, top priority | +| Myriad | Many, numerous | +| Plethora | Many, abundance | +| Commence | Start, begin | +| Endeavor | Effort, attempt, try | +| Facilitate | Help, enable | +| Utilize | Use | +| Subsequent | Next, later, following | + +## Copula Avoidance + +LLMs substitute elaborate constructions for simple "is"/"are"/"has". Use the simple form. + +| Avoid | Use instead | +|-------|-------------| +| Serves as | Is | +| Stands as | Is | +| Functions as | Is | +| Represents a | Is a | +| Boasts a | Has | +| Features a | Has | +| Offers a | Has, provides | +| Marks a | Is a | + +## Significance Inflation + +Puffing up importance with empty claims. Remove or replace with evidence. + +- "marking a pivotal moment in" +- "a vital/significant/crucial role" +- "setting the stage for" +- "indelible mark" +- "deeply rooted" +- "a testament to" +- "underscores the importance of" +- "reflects broader trends" +- "shaping the future of" +- "contributing to the evolution of" + +## Promotional Language + +Adjectives that sell rather than describe. Cut or replace with specifics. + +- Nestled +- Breathtaking +- Groundbreaking (figurative) +- Renowned +- Must-visit +- Stunning +- Seamless +- Robust +- Cutting-edge +- State-of-the-art +- World-class +- In the heart of +- Rich (figurative: "rich history", "rich tradition") +- Profound + +## Chatbot Artifacts + +Conversational assistant phrases that leak into content. Remove entirely. + +- "I hope this helps!" +- "Great question!" +- "Certainly!" +- "Of course!" +- "Absolutely!" +- "Would you like me to..." +- "Let me know if you have questions" +- "Feel free to ask" +- "Here is an overview of" +- "I'd be happy to help" +- "That's a great point!" +- "You're absolutely right!" + +## Filler Phrases + +Wordy constructions with shorter equivalents. + +| Avoid | Use instead | +|-------|-------------| +| In order to | To | +| Due to the fact that | Because | +| At this point in time | Now | +| Has the ability to | Can | +| It is important to note that | (delete — just state the thing) | +| It should be noted that | (delete) | +| With regard to | About, regarding | +| In the event that | If | +| A large number of | Many | +| On a daily basis | Daily | +| Prior to | Before | +| In close proximity to | Near | +| Serves to highlight | Shows | +| The fact of the matter is | (delete) | + +## Academic Hedging (Register-Aware) + +**In casual/professional writing**: flag and remove these. +**In academic writing**: tolerate when expressing genuine epistemic uncertainty. + +- "It is well-established that" — established by whom? Cite. +- "The literature suggests" — which literature? Cite specific works. +- "Further research is needed" — true of everything; cut from conclusions +- "Contributes to a growing body of" — vague; say what it contributes +- "Scholars have long debated" — which scholars? +- "It could potentially be argued that" — just argue it + +## Sycophantic Tone + +Over-agreeable or people-pleasing language. Cut. + +- "That's an excellent observation" +- "You raise a very important point" +- "This is a really thoughtful question" +- "You're right that..." +- "As you correctly noted..." diff --git a/references/positive.md b/references/positive.md new file mode 100644 index 0000000..41e7ab6 --- /dev/null +++ b/references/positive.md @@ -0,0 +1,89 @@ +# What Good Writing Does + +Anti-slop is half the job. Removing bad patterns produces clean but lifeless text. This file describes what to aim for. + +## Be Specific + +Replace vague claims with concrete facts. Dates, names, numbers, sources. + +| Vague | Specific | +|-------|---------| +| "Many experts agree" | "A 2024 MIT study of 200 firms found" | +| "significant improvement" | "latency dropped from 340ms to 90ms" | +| "has been widely adopted" | "used by 14,000 teams as of January 2026" | + +## Use Simple Constructions + +Prefer "is", "are", "has" over elaborate substitutes. + +| Elaborate | Simple | +|-----------|--------| +| "serves as a foundation for" | "is the foundation of" | +| "stands as a reminder of" | "reminds us" | +| "boasts a collection of" | "has" | +| "represents a shift toward" | "is a shift toward" | + +## Active Voice + +Subject does the thing. Passive voice hides the actor. + +| Passive | Active | +|---------|--------| +| "The decision was made by the team" | "The team decided" | +| "Errors were introduced during migration" | "The migration introduced errors" | +| "It has been argued that" | "[Scholar] argues that" | + +Exception: passive is appropriate when the agent is genuinely unknown or irrelevant ("The temple was built in the 3rd century BCE"). + +## Positive Form + +State what is, not what isn't. Negatives require readers to invert. + +| Negative | Positive | +|----------|---------| +| "He was not very often on time" | "He usually came late" | +| "She did not think the study was useful" | "She thought the study was useless" | +| "not unlike" | "like" | +| "not infrequently" | "often" | + +## Vary Rhythm + +Monotone sentence length signals algorithmic generation. Mix it up. + +Short sentence. Then a longer one that takes its time. Then short again. This creates natural reading cadence that no pattern-matching detector flags. + +Two items in a list beat three. Three is the LLM default. + +## Have a Voice + +Soulless writing is as detectable as slop. Signs of voiceless text: +- Every sentence is the same length and structure +- No opinions, only neutral reporting +- No acknowledgment of uncertainty or mixed feelings +- No humor, edge, or personality + +How to fix it: +- React to facts, don't just report them +- "I don't know how to feel about this" is more human than a balanced pros-and-cons list +- Use "I" when appropriate—first person is not unprofessional +- Let some mess in—tangents and half-formed thoughts are human + +## Trust the Reader + +Don't explain what you just showed. Don't announce significance. + +| Hand-holding | Trusting | +|-------------|---------| +| "This is significant because it shows that..." | Just show it. | +| "In other words, ..." | If your first words were clear, you don't need other ones. | +| "Let that sink in." | It already did. | +| "Think about it." | They already are. | + +## Acknowledge Complexity + +Real subjects are messy. Pretending otherwise signals synthetic origin. + +| Oversimplified | Human | +|----------------|-------| +| "AI coding tools are transformative" | "AI coding tools speed up boilerplate but don't help with design decisions" | +| "The policy was successful" | "The policy reduced emissions 12% but displaced 3,000 workers" | diff --git a/references/registers.md b/references/registers.md new file mode 100644 index 0000000..ab6686c --- /dev/null +++ b/references/registers.md @@ -0,0 +1,147 @@ +# Register-Specific Rules + +Different writing contexts tolerate different patterns. Detect the register from context, then apply the right rules. + +## Register Detection + +Infer the register from the content and context: + +| Signal | Register | +|--------|----------| +| Citations, methodology, "we hypothesize" | `academic` | +| API docs, READMEs, changelogs, error messages | `technical` | +| Fiction, essays, memoir, creative nonfiction | `narrative` | +| Blog posts, social media, emails, LinkedIn | `casual` | +| Reports, proposals, business comms | `professional` | + +If the user specifies a register, use it. Otherwise, infer from content. + +--- + +## Academic + +**Principle**: Precision over brevity. Claims require evidence. + +### Acceptable in academic writing + +- Hedging qualifiers: "may", "suggests", "appears to", "it is possible that" — these are epistemic precision, not weakness +- Passive voice when agent is unknown: "The temple was constructed in the 3rd century BCE" +- Longer sentences when subordinate clauses add necessary qualification +- Citation stacking: "(Gordon 1966; Astour 1967; Harrison 1912)" is not slop +- Field-specific terminology used precisely + +### Flag in academic writing + +- **Significance inflation without evidence**: "marking a pivotal moment" — pivotal according to whom? +- **Vague attribution**: "scholars have long debated" — which scholars? Name them. +- **-ing padding**: "highlighting the importance of this finding" — just state the finding +- **Promotional adjectives**: "groundbreaking study" — let the reader judge +- **Empty hedging**: "further research is needed" as a conclusion — this is true of everything +- **"The literature"** without specific citations — which literature? +- **Synonym cycling**: switching between "study", "research", "investigation", "inquiry" for the same thing + +### Scoring adjustments + +- Density: do not penalize longer sentences that carry necessary qualification +- Directness: hedging that reflects genuine epistemic uncertainty is direct, not evasive +- Trust: citing sources IS trusting the reader to evaluate evidence + +--- + +## Technical + +**Principle**: Clarity and accuracy. Say what it does, not what it means. + +### Acceptable in technical writing + +- Bullet points and numbered lists for steps, options, parameters +- Headers and subheaders for navigation +- Code blocks and examples +- Domain jargon when used precisely ("idempotent", "backpressure", "memoization") +- Imperative voice: "Run the migration", "Set the environment variable" + +### Flag in technical writing + +- **Promotional adjectives**: "robust", "seamless", "cutting-edge", "blazing fast", "elegant" — give benchmarks or remove +- **Vague claims**: "significantly faster" — how much faster? Benchmark it. +- **Chatbot artifacts**: "I hope this helps!", "Let me know if you have questions" +- **Explanation padding**: "It's worth noting that..." — just note it +- **Buzzword stacking**: "leveraging our cloud-native, AI-powered, enterprise-grade platform" +- **Emoji-decorated headings**: remove +- **Inline-header vertical lists** when prose would work better + +### Scoring adjustments + +- Rhythm: consistent structure is a feature in reference docs, not a flaw +- Density: technical docs should be scannable; some redundancy aids comprehension +- Authenticity: measured, impersonal tone is appropriate + +--- + +## Narrative + +**Principle**: Voice, rhythm, and imagery. Technique serves story. + +### Acceptable in narrative writing + +- Em dashes for parenthetical asides, interruption, tonal shifts +- Sentence fragments for deliberate effect (not as default compression) +- Metaphor and imagery without explanation +- Varying sentence length dramatically — short punches followed by long flowing passages +- First person, strong opinions, emotional register +- Repetition for rhetorical effect (distinct from synonym cycling) + +### Flag in narrative writing + +- **Synonym cycling**: "The protagonist... The main character... The central figure..." — pick one and use it +- **Rule of three**: forcing every list into three items +- **AI vocabulary clusters**: delve, tapestry, multifaceted, nuanced, intricate, interplay +- **Generic conclusions**: "the future looks bright", "exciting times lie ahead" +- **Dramatic fragmentation when unearned**: "Hope. That's it. That's the word." — earn the emphasis +- **Physical tell cliches**: "jaw tightened", "breath caught", "something shifted behind his eyes" +- **Explaining metaphors**: if you need to explain it, rewrite it +- **False profundity**: "And maybe that was enough." as a paragraph closer + +### Scoring adjustments + +- Rhythm: variation is the goal, not consistency +- Authenticity: voice and personality matter more than neutrality +- Directness: indirection is a valid narrative technique + +--- + +## Casual + +**Principle**: All stop-slop rules apply at full force. + +Current `phrases.md` and `structures.md` rules are calibrated for this register. Shortest path from thought to reader. No throat-clearing, no filler, no jargon. + +### Additional casual flags + +- Exclamation mark overuse (more than 1 per paragraph) +- Emoji in professional-adjacent contexts +- "Actually" and "literally" as filler intensifiers +- Starting sentences with "So," or "Look," + +--- + +## Professional + +**Principle**: Clear and direct. Respect the reader's time. + +Similar to casual but tolerates slightly more structure: + +### Acceptable in professional writing + +- Bullet points for action items, decisions, or options +- Formal salutations and closings in emails +- Measured hedging: "We recommend X, though Y may also work" +- Executive summary format + +### Flag in professional writing + +- **Business jargon**: "synergy", "leverage", "circle back", "double down", "move the needle" +- **Throat-clearing**: "I wanted to reach out to share that..." — just share it +- **Filler adverbs**: "basically", "essentially", "fundamentally" +- **Vague commitments**: "We'll look into this" — when? What specifically? +- **Meeting-speak**: "Let's take this offline", "parking lot this" diff --git a/references/structures.md b/references/structures.md index 9a1a876..75fd48a 100644 --- a/references/structures.md +++ b/references/structures.md @@ -69,3 +69,106 @@ These announce insight rather than deliver it. |---------|---------| | Absolute words (always, never, everyone, everybody, nobody) | False authority | | AI-overused intensifiers (deeply, truly, fundamentally, inherently, simply, literally, inevitably) | Empty emphasis | + +## Format Slop + +Formatting patterns that signal AI generation. + +| Pattern | Problem | Fix | +|---------|---------|-----| +| Bullet points where prose works | Fragmenting ideas that flow naturally | Write connected paragraphs | +| Emoji-decorated headings (rocket, lightbulb, checkmark) | Infantilizing, visually noisy | Remove emojis from headings | +| `- **Bold label:** description` lists | Inline-header vertical lists | Incorporate into prose or use real headings | +| Boldface on every other phrase | Mechanical emphasis | Bold only what truly needs emphasis, or nothing | +| Title Case In Every Heading | ChatGPT default, not standard | Use sentence case | +| Numbered lists for non-sequential items | Imposing false order | Use bullets or prose | + +**Register note:** Bullet points and headers are appropriate in `technical` register (reference docs, READMEs). Flag them in `casual`, `professional`, and `narrative`. + +## Superficial -ing Analyses + +Trailing present participle clauses that fake depth. They add no information. + +| Pattern | Problem | +|---------|---------| +| "...highlighting its importance" | Tells you something is important without showing why | +| "...ensuring reliability" | Asserts an outcome without evidence | +| "...showcasing the team's commitment" | Promotional, not descriptive | +| "...reflecting broader trends" | Vague gesture at significance | +| "...underscoring the need for" | Announcing importance instead of demonstrating it | +| "...fostering collaboration" | What does this actually mean in practice? | +| "...contributing to a more sustainable future" | Generic aspiration | + +**Instead:** Delete the -ing clause. If the information matters, give it its own sentence with evidence. + +## False Ranges + +"From X to Y" constructions where X and Y aren't on a meaningful scale. + +| Pattern | Problem | +|---------|---------| +| "from hobbyist experiments to enterprise rollouts" | Vague sweep | +| "from the Big Bang to the cosmic web" | Dramatic but content-free | +| "from solo developers to cross-functional teams" | Scale-faking | + +**Instead:** Pick the specific claim that matters and support it. + +## Rule of Three Overuse + +LLMs force ideas into groups of three to appear comprehensive. Two items often suffice. + +| Pattern | Problem | +|---------|---------| +| "innovation, inspiration, and industry insights" | Alliterative padding | +| "speed, quality, cost" | Cliche triad | +| "streamlining processes, enhancing collaboration, and fostering alignment" | Three vague verbs | + +**Instead:** Use two items. Or one. State what actually matters. + +## Elegant Variation (Synonym Cycling) + +Repetition-penalty code causes LLMs to substitute synonyms for the same thing, creating confusion about whether different words refer to different concepts. + +| Pattern | Problem | +|---------|---------| +| "The protagonist... The main character... The central figure... The hero..." | Are these four different people? | +| "The study... The research... The investigation... The inquiry..." | Ambiguity | +| "The company... The firm... The organization... The enterprise..." | Same entity, four names | + +**Instead:** Pick one term and reuse it. Repetition is clarity. + +## Generic Positive Conclusions + +Vague upbeat endings that could apply to anything. + +- "The future looks bright" +- "Exciting times lie ahead" +- "This represents a major step in the right direction" +- "As we continue this journey toward excellence" +- "The possibilities are endless" + +**Instead:** End with a specific claim, a concrete next step, or nothing. Not every piece needs a conclusion. + +## Challenges-and-Prospects Formula + +"Despite challenges... continues to thrive" is an LLM default structure for any topic. + +| Pattern | Problem | +|---------|---------| +| "Despite its challenges, X continues to..." | Formulaic resilience narrative | +| "While facing obstacles, X remains committed to..." | Same formula | +| "Challenges and Future Outlook" as a heading | Template section | + +**Instead:** Name the specific challenge. Name the specific response. Or omit if you have nothing concrete to say. + +## Knowledge-Cutoff Disclaimers + +Hedges about incomplete information that leak from chatbot context into content. + +- "As of [date]" +- "Up to my last training update" +- "While specific details are limited/scarce..." +- "Based on available information..." +- "Details about X are not extensively documented in readily available sources" + +**Instead:** State what you know with specific sources. If you don't know, don't write about it.