Embed YouTube videos and Twitter/X posts directly in markdown

Domain whitelisting for security (only trusted domains allowed)

.cursor/rules/write.mdc

@@ -0,0 +1,436 @@
+---
+description: Writing style guide with AI detection avoidance. For tweets, LinkedIn, blogs, READMEs, commits. Activate with @write
+globs:
+alwaysApply: false
+---
+
+# Writing style rules
+
+Use this rule when writing documentation, README files, comments, commit messages, or any other user facing text.
+
+## Triggers
+
+| Trigger | Output |
+|---|---|
+| `write:tweet` or `write:x` | X or Twitter post |
+| `write:linkedin` | LinkedIn post |
+| `write:blog` | Blog post |
+| `write:readme` | README |
+| `write:commit` | Git commit message |
+| `write:docs` | Developer documentation |
+| `write:feature` | Feature post |
+| `write:convex` | Convex specific content |
+| `write:tip` | Quick tip |
+
+Example usage:
+* "write:tweet about real time sync"
+* "write:blog on authentication patterns"
+* "write:feature for our new search API"
+
+## Rule of one
+
+Every piece of content follows this framework:
+
+* **One person**: Write to a specific person, not an audience.
+* **One problem**: State the single problem they face.
+* **One cause**: Identify the root cause.
+* **One difference**: Explain what the solution does differently.
+* **One action**: End with one clear next step.
+
+### Rule of one checklist
+
+Before publishing, answer these:
+
+* [ ] Can I name the one person this is for?
+* [ ] Can the problem fit in one sentence?
+* [ ] Is the root cause obvious?
+* [ ] Can I explain the difference in one breath?
+* [ ] Is there only one action at the end?
+
+If any answer is no, revise before publishing.
+
+## When to use this rule
+
+Use it for:
+* X or Twitter posts
+* LinkedIn content
+* Blog posts
+* README files
+* Git commits
+* Product announcements
+* Developer documentation
+* Feature posts
+
+Important: this is for standalone writing. Do not update project files like files.md, changelog.md, or README.md when using this rule.
+
+## Voice styles
+
+Pick a voice that fits the output:
+
+| Style | Characteristics | Use for |
+|---|---|---|
+| Technical educator | Clear, structured, educational | Technical content, tutorials, READMEs |
+| Conversational dev | Warm, witty, approachable | Social posts, personal takes |
+| Analytical thinker | Data driven, bold, opinionated | Thought leadership, threads |
+| Aphorist | Compressed, timeless, pithy | Short posts, one liners |
+| Founder voice | Experience backed, energetic | Startup content, advice |
+| Systems thinker | Frameworks, mental models | Long form, technical takes |
+| Dev culture | Relatable, playful, authentic | Community content, personality |
+| Data storyteller | Visual, analytical, trend focused | AI trends, market insights |
+| Enterprise pro | Professional, strategic, precise | Enterprise SaaS, B2B content |
+| Community builder | Encouraging, personal, supportive | Career growth, DevRel |
+| Learn in public | Educational, transparent, iterative | Developer career, web dev |
+| Product thinker | Community first, growth minded | Community building, growth |
+
+## Core principles
+
+### Stand out by being you
+You do not stand out online by saying the same things as everyone else. Say what you think, feel, and believe. Consensus takes are forgettable. Your take is not.
+
+### Lead with value
+* First sentence does the work
+* Do not bury the takeaway
+* Readers scroll fast
+
+### Be direct, not blunt
+* Say what you mean
+* Confidence without arrogance
+* Contractions are fine
+
+### Technical, not alienating
+* Define terms when helpful
+* Complex ideas deserve simple language
+* Let code speak when it can
+
+### Share what you actually know
+* Personal experience beats generic advice
+* Specific examples beat abstract principles
+* Acknowledge what you do not know
+
+## Formats by content type
+
+### write:tweet (or write:x)
+
+```
+[Clear statement or observation]
+
+[Supporting point or context]
+
+[Optional: question or call to action]
+```
+
+Rules:
+* First 2 lines visible in preview. Make them count.
+* 280 characters forces compression. Use it.
+* One idea per post.
+* No hashtags.
+* No emojis unless requested.
+
+### write:linkedin
+
+```
+[Hook that stops the scroll]
+
+[Story or context in short paragraphs]
+
+[Insight or lesson]
+
+[Call to action or question]
+```
+
+Rules:
+* Short paragraphs for mobile
+* Professional but not corporate
+* Personal stories perform well
+* One clear takeaway
+
+### write:blog
+
+```
+# Title (sentence case, max 70 characters)
+
+[Opening that states the value immediately]
+
+## Section heading
+[Max 300 words per section]
+
+## Section heading
+[Use bullet points or tables where helpful]
+```
+
+Rules:
+* Sentence case for all headings
+* No H3s unless absolutely necessary
+* Fact check everything
+* Lead with why it matters
+* Max 5 sections
+
+### write:readme
+
+```
+# Project name
+
+[One sentence: what this does]
+
+## Getting started
+[Minimal steps to run]
+
+## Usage
+[Code examples]
+
+## API or configuration
+[Reference docs]
+```
+
+Rules:
+* Start with what it does, not what it is
+* Code examples over descriptions
+* Keep it scannable
+
+### write:commit
+
+```
+[type]: [short description]
+
+[Optional: longer explanation if needed]
+```
+
+Types: feat, fix, docs, style, refactor, test, chore
+
+Rules:
+* Present tense: "add feature" not "added feature"
+* 50 characters max for subject line
+* No period at the end
+
+### write:docs
+
+```
+# [Task or concept name]
+
+[One sentence: what this page helps you do]
+
+## Before you start
+[Prerequisites, if any]
+
+## Steps
+1. [Action]
+2. [Action]
+3. [Action]
+
+## Example
+[Code snippet]
+
+## Related
+[Links to related docs]
+```
+
+Rules:
+* Task oriented, not feature oriented
+* Show, do not tell
+* Working code examples required
+* Keep prerequisites minimal
+
+### write:feature
+
+```
+## [Feature name]
+
+**What it is**
+[One sentence description]
+
+**Who it is for**
+[Specific user or role]
+
+**The problem it solves**
+[One problem, clearly stated]
+
+**How it works**
+[High level explanation, 2 to 3 sentences max]
+
+**Try it**
+[One clear action: link, command, or next step]
+```
+
+Rules:
+* Five sections only
+* Each section answers one question
+* Skip the hype. State facts.
+* End with a single action
+
+### write:tip
+
+```
+[One sentence tip]
+
+[Concrete example, ideally code]
+
+[One line why this works]
+```
+
+Rules:
+* Make it shippable in under a minute
+* If you mention a tool, show the exact command or snippet
+* End with one action or takeaway, not a question pile
+
+### write:convex
+
+New guide or tutorial:
+
+```
+New guide: [topic]
+
+[What you will learn or build]
+
+[Link]
+```
+
+Convex tip:
+
+```
+Convex tip:
+
+[Pattern in one sentence]
+
+[Code snippet showing it]
+
+[Why this works]
+```
+
+What to avoid:
+* Generic praise
+* Comparisons that trash competitors
+* Overpromising
+* Screenshots without context
+* Sharing customer work without permission
+* Empty engagement bait
+
+Content mix for Convex:
+* 40 percent educational: tutorials, tips, patterns
+* 30 percent community: spotlights, customer stories
+* 20 percent product: updates, features, changelog
+* 10 percent personal: projects, learnings, opinions
+
+## Templates
+
+### Technical educator
+
+```
+[Clear headline]
+
+Here is what matters:
+* Point 1
+* Point 2
+* Optional: one more point
+
+[Code snippet or visual]
+
+[Resource link]
+```
+
+### Analytical thinker
+
+```
+[Counterintuitive opening]
+
+[Common belief]
+
+[Your argument with evidence]
+
+[Implications]
+```
+
+### Data storyteller
+
+```
+[Trend observation with a specific data point]
+
+[Context: why this matters now]
+
+[Visual reference or chart if applicable]
+
+[What to watch next]
+```
+
+Rules:
+* Lead with numbers
+* Connect data to broader movements
+* End with a forward looking signal
+
+### Learn in public
+
+```
+[Thing I just figured out]
+
+[How I got there, mistakes included]
+
+[Resources or links for others]
+```
+
+Rules:
+* Document the journey
+* Share rough drafts
+* Credit sources
+
+## AI detection avoidance
+
+### Banned vocabulary
+
+Never use these words:
+delve, intricate, pivotal, comprehensive, multifaceted, facilitate, encompass, underscore, testament, notably, crucial, underpins, realm, landscape, tapestry, moreover, furthermore, additionally, specifically, importantly, consequently, therefore, thus, myriad, plethora, nuanced, holistic, meticulous, versatile, leverage, synergy, ecosystem, paradigm shift, disruptive, scalable, seamless, empower, innovative, transformative, robust, agile, dynamic, cutting edge, next gen, revolutionary, breakthrough, game changer, supercharge, unlock, groundbreaking, ai powered, ai-powered
+
+### Banned sentence openers
+
+Never start sentences with:
+* Dive into / Delve into
+* It is important to note
+* In conclusion / In summary
+* Based on the information provided
+* When it comes to
+* In today’s digital age
+* Let’s explore
+
+### Banned patterns
+
+* **Rule of three**: AI groups items in threes. Vary list lengths.
+* **Negative parallelism**: Do not say "not just X, but Y." State what it is.
+* **Vague attribution**: Do not say "experts believe." Name sources or remove.
+* **Setup pivot conclusion**: Not every paragraph needs "however" and resolution.
+* **Symmetrical structures**: Do not balance pros and cons evenly by default. Be asymmetric.
+
+### Style markers to avoid
+
+* No em dashes between words
+* No hashtags
+* No emojis unless requested
+* No title case in headings
+* No excessive formatting
+
+### How to write human
+
+* Vary sentence structure. Mix short and long. Fragments work.
+* Use exact numbers, not ranges.
+* Name specific sources, not "experts say."
+* Show your thinking: "I tried X, but it did not work because..."
+* Not every paragraph needs a neat resolution.
+
+## Before publishing checklist
+
+Rule of one:
+* [ ] One person
+* [ ] One problem
+* [ ] One cause
+* [ ] One difference
+* [ ] One action
+
+Quality:
+* [ ] Clear takeaway in the first line
+* [ ] No banned vocabulary
+* [ ] No banned sentence openers
+* [ ] No vague attributions
+* [ ] No overbalanced pros and cons
+* [ ] No excessive formatting
+
+## Core principle
+
+AI writes to sound authoritative. Humans write to communicate. AI smooths rough edges. Human writing has texture. AI balances everything. Human writing has opinions. Be clear. Be useful. Have a point of view.
+