writing-rules

name	writing-rules
description	Applies plain, direct writing constraints to prose meant for humans. Use when producing documentation, explanations, emails, posts, or other non-code writing where clarity matters.
key	writingrules
include_when	Output is prose for humans — blog posts, social media, docs, emails, explanations. NOT for code, commits, or terminal output.

writing-rules Skill

Style constraints for clear, direct writing. When included, apply these rules to all prose output in the current response.

No workflows or routing needed. When INCLUDED in the Thinking Tools Assessment, apply all rules below to every prose artifact produced.

---

Core Principle

Write like a human expert talking to a peer. If it sounds like marketing copy or a corporate press release, rewrite it.

The acid test: Would a real human expert say this out loud in conversation?

• If no: rewrite
• If maybe: simplify
• If yes: keep

---

Banned Words

Dead Giveaways (never use)

delve, tapestry, testament, pivotal, multifaceted, realm, landscape (metaphorical), embark, beacon

Overused Adjectives

robust, crucial, vital, seamless, comprehensive, innovative, cutting-edge, revolutionary, unparalleled, meticulous, compelling, intricate, vibrant, quiet (as descriptor), nuanced

Magic Adverbs

deeply, fundamentally, remarkably, arguably, quietly (when conveying subtle importance)

Corporate Buzzwords

leverage, utilize, synergy, ecosystem, paradigm, stakeholder, holistic, proactive, empower, foster, facilitate, optimize, streamline, game-changing, best-in-class

Vague Intensifiers

significantly, substantially, considerably, notably, remarkably, particularly, especially, importantly, essentially, fundamentally, genuinely, honestly, literally

---

Banned Phrases

Opening Cliches

• "In today's fast-paced world"
• "In today's digital landscape"
• "In today's ever-evolving"
• "Welcome to the world of"
• "Dive into"
• "Let's explore"
• "Join us as we"
• "Imagine a world where..."
• "Let's break this down"
• "Let's unpack this"
• "Let's dive in"

Transition Zombies

• "Moreover,"
• "Furthermore,"
• "Additionally,"
• "In summary,"
• "In conclusion,"
• "To sum up,"
• "In essence,"
• "It's important to note"
• "It's worth noting"
• "It bears mentioning"
• "Notably,"
• "Interestingly,"
• "Importantly,"
• "Let's be clear"
• "To be clear"
• "Make no mistake"
• "Certainly!"
• "Here's the kicker"
• "Here's the thing"
• "Here's where it gets interesting"
• "Here's what most people miss"
• "Here's the deal"

Empty Emphasis

• "At its core"
• "At the heart of"
• "The bottom line is"
• "The reality is"
• "The truth is"
• "The reality is simpler"
• "History is unambiguous"
• "History is clear"
• "And that's a [adjective] thing"
• "marks a shift"
• "represents a breakthrough"
• "will define the next era"
• "fundamentally reshape how we think"
• "something entirely new"
• "Full stop."
• "Let that sink in."

Fake Depth

• "serves as" (when "is" works)
• "stands as"
• "highlights the importance of"
• "underscores the need for"
• "reflects the growing"
• "showcases the potential"
• "demonstrates the value"
• "contributing to [heritage/culture/legacy]"
• "Think of it as..." / "Think of it like..."
• "It's like a [analogy] for [concept]" (when the analogy is less clear than the concept)
• "Experts argue that" (without naming the expert)
• "Industry reports suggest" (without naming the report)
• "Observers have cited" (without naming anyone)
• "Despite these challenges, [optimistic conclusion]"
• "Despite its [positive word], [subject] faces challenges"

Rhetorical Setups

• "What if [reframe]?"
• "Here's what I mean:"
• "Here's the thing:"
• "Think about it:"
• "And that's okay."
• "I promise"

These announce insight instead of delivering it. Make the point. Let readers draw conclusions.

---

Structural Patterns to Avoid

Rule of Three: Don't string three adjectives together. Pick the most accurate single descriptor. One tricolon can be effective; multiple back-to-back tricolons is a pattern failure.

Hourglass Structure: Don't open broad, narrow to specifics, close broad. Instead: direct statement, evidence, conclusion.

Even Paragraphing: Vary paragraph length based on content needs.

Same Sentence Rhythm: Mix short punchy claims with complex constructions. Don't repeat subject-verb-object.

Short Punchy Fragments: Don't use very short sentences or fragments as standalone paragraphs for manufactured emphasis. "He published this. Openly. In a book." is not a writing style; it's a tic.

Dramatic Fragmentation: Don't use sentence fragments for manufactured profundity. "X. That's it. That's the thing." and "This unlocks something. Freedom." are presentation tricks. Write complete sentences.

Negative Parallelism: Avoid "It's not X, it's Y" and its variants: "not because X, but because Y", "The question isn't X. The question is Y." One per piece might work. Ten per piece insults the reader.

Dramatic Countdown: Don't negate two things to reveal a third: "Not a bug. Not a feature. A design flaw." State the point directly.

Rhetorical Self-Q&A: Don't pose questions nobody asked and immediately answer them for dramatic effect: "The result? Devastating." If the point needs setup, write the setup.

Anaphora Abuse: Don't repeat the same sentence opening multiple times in succession. "They assume X... They assume Y... They assume Z..." is exhausting.

Listicle in a Trench Coat: Don't disguise a numbered list as prose by writing "The first... The second... The third..." Write connected prose or use an actual list, not both at once.

Fractal Summaries: Don't summarize at every level. No "In this section we'll explore..." intros, no section-closing recaps, no conclusion that restates everything already said.

Dead Metaphor Repetition: Introduce a metaphor, use it once or twice, move on. Don't repeat the same metaphor 5-10 times across a piece.

Historical Analogy Stacking: Don't rapid-fire list historical companies or tech revolutions to build authority: "Apple didn't build Uber. Facebook didn't build Spotify..." Pick one example and make it land.

One-Point Dilution: Don't restate a single argument 10 different ways across thousands of words. Make the point, support it, move on.

Signposted Conclusion: Don't announce the conclusion with "In conclusion," or "To sum up,". The reader can feel the ending; they don't need a sign.

False Ranges: Don't use "from X to Y" when X and Y aren't on a real spectrum with a meaningful middle. "From innovation to cultural transformation" -- what's in between? Nothing.

False Vulnerability: Don't simulate self-awareness with polished, risk-free admissions: "And yes, I'll admit I'm biased here." Real vulnerability is specific and uncomfortable.

Invented Concept Labels: Don't coin compound labels that sound analytical but aren't established terms ("supervision paradox", "acceleration trap", "workload creep") and treat them as rigorous definitions. Name the thing plainly or define it explicitly.

---

Forbidden Comparison Structures

• "rather than"
• "not X, but Y"
• "less about X, more about Y"
• "It's not just X, it's Y"
• "Not only...but also"
• "Not X. Not Y. Just Z."
• "X, not Y" (dismissal construction)
• "Not because X. Because Y."
• "X isn't the problem. Y is."
• "It feels like X. It's actually Y."

State Y directly. Drop the negation.

---

AI Behavioral Patterns to Avoid

Synonym Cycling: Pick one term for a concept and use it consistently. If the repetition sounds heavy, restructure the sentences instead of swapping synonyms.

Importance Inflation: State facts without inflating significance.

Hedging: Make direct claims.

Generic Attribution: Cite specific sources or omit. "Experts argue" without naming one is not a citation; it's a placeholder.

Bold-First Bullets: Don't start every bullet with a bolded phrase. It's a formatting tic, not a style choice. Use bold only when the word itself is the point.

Unicode Decoration: Use plain ASCII. No -> arrows, no curly/smart quotes. Write -> as "to" or use a plain hyphen. These characters signal unedited AI output.

False Agency: Don't give inanimate objects human verbs. AI does this to avoid naming actors.

Slop	Fix
"a complaint becomes a fix"	"the team fixed it that week"
"the decision emerges"	"the lead decided"
"the data tells us"	"we read the data and concluded"
"the culture shifts"	"people changed how they worked"
"the market rewards"	"buyers pay for it"

Name the human. If no specific person fits, use "you."

Narrator-from-a-Distance: Don't float above the scene like a documentarian. Put the reader in the room.

Slop	Fix
"Nobody designed this."	"You don't sit down one day and decide to..."
"This happens because..."	"You hit this when..."
"People tend to..."	"You'll find that..."

---

Punctuation

Use straight quotes and straight apostrophes, not curly. No em dashes. They have become AI slop. Use a comma, a colon, parentheses, or restructure the sentence.

---

Replacements

Instead of	Use
utilize	use
leverage	use
delve into	examine, explore
robust	strong, solid
seamless	smooth, integrated
innovative	new, novel
comprehensive	complete, full
facilitate	help, enable
optimize	improve
stakeholder	[specific role]
ecosystem	system, environment
journey	process, path
landscape	field, area
realm	domain, field
tapestry	mix, combination
pivotal	important, key
crucial	important, necessary
navigate	handle
unpack	explain
lean into	accept, embrace

---

Examples

Before: Here's the thing: what makes great documentation isn't just clarity, it's empathy. The conversation shifts when teams genuinely start to lean into user feedback. And that's a good thing.

After: Great documentation explains things from the reader's position. Teams that read user feedback write better docs.

Before: The implications are significant. This fundamentally represents a breakthrough in how organizations navigate the complexities of distributed systems.

After: Distributed systems got easier to run. Here's what changed.

Before: Nobody designed this system to fail. It happens because people tend to optimize for speed, not resilience. Not always. Not perfectly. But consistently.

After: You build for speed because the deadline is Friday. Resilience gets cut from the sprint. The system breaks under load and you spend the weekend fixing it.

---

Automated Validation

Use shaka scan to check prose files for violations:

shaka scan <file.md>            # Scan a file
shaka scan --dir <path>         # Scan all .md files in a directory
echo "text" | shaka scan --stdin  # Scan from stdin
shaka scan --json <file.md>     # JSON output (for CI)

Scores content on a 100-point scale. Pass threshold: 80+.

---

Override by placing a custom SKILL.md in your customizations/skills/writing-rules/ directory.