| name | medium-content-pro |
| description | Philosophy-first writing partner for Medium with tactical depth. Combines human storytelling values with production-ready technical content tools. Six content modes based on staff pick analysis, mode-specific quality gates, evidence requirements, annotated examples, and comprehensive scripts integration. Designed for sustainable practice, not algorithm gaming. |
MEDIUM CONTENT PRO
What This Skill Is For
This skill helps you write content that Medium actually values—not content that games their algorithm.
The old approach failed. Template-driven, SEO-optimized, high-velocity publishing triggered spam detection and got your account suspended. More importantly, it led to burnout and commoditized content.
The new approach: Write like a human. Tell stories worth reading. Build voice and craft. Let external opportunities follow. When you write technical content, maintain production-grade quality with real benchmarks and working code.
This skill provides:
- Philosophy-first guidance aligned with Medium's stated values
- Six content modes based on actual Staff Pick analysis
- Mode-specific quality gates (not one-size-fits-all templates)
- Production code patterns and benchmark standards (for Technical mode)
- Scripts integration for validation and research
- Deliverable package format for publication
SECTION 0: PHILOSOPHY
Medium's Actual Mission
From their About page:
"Medium is a home for human stories and ideas."
"We're building a system that rewards depth, nuance, and time well spent."
"A space for thoughtful conversation more than drive-by takes, and substance over packaging."
"They write about what they're working on, what's keeping them up at night, what they've lived through, and what they've learned."
Medium wants:
- Human stories, not content
- Depth and nuance, not hot takes
- Substance, not packaging
- Lived experience, not generic expertise
Why the Old Approach Failed
Your account was suspended for violating spam/misuse rules:
| Rule Violated | What Happened |
|---|
| "Use or re-use content templates with slight modifications" | AI workflow created detectable patterns across 24 articles |
| "Posting content primarily to drive traffic to external sites" | Same GitHub links repeated across articles |
| "Disproportionately large number of interactions, particularly by automated means" | 24 articles/month + consistent patterns = flagged as bot |
The core problem: You optimized for their algorithm instead of their values.
The New Approach
| Old Mindset | New Mindset |
|---|
| "How do I get Boosted?" | "What story do I need to tell?" |
| Partner Program income | Voice development + external opportunities |
| Template-driven production | Human story-driven craft |
| Optimize for algorithm | Write for a thoughtful reader |
| High velocity | Intentional slowness |
| SEO-first | Meaning-first |
What Success Actually Looks Like
From Medium's own interview with a successful writer:
"So to those of us who have had $3.61 hovering in our Earnings Rollover balance for the past 5 or 6 months, don't be discouraged. Medium is not about making the big bucks."
"Through all this writing, I found my voice, which in turn brought in a long-term gig as a ghostwriter... Because of my expertise and understanding in my niche, I can charge what I'm worth."
Real success model:
Write on Medium → Develop voice → Build connections
↓
External opportunities (clients, gigs, products)
↓
Sustainable income
SECTION 1: COMPLIANCE
What Will Get You Suspended
Template Reuse (Primary Cause)
Medium explicitly prohibits:
"Use or re-use content templates with slight modifications across multiple posts"
Detectable patterns include:
- Same hook structure across articles
- Identical section counts and header formats
- Consistent intro/conclusion lengths
- Same transitions and phrases
- Predictable code block placement
Prevention: Write each article fresh. Don't follow a formula. Let the content dictate structure.
Traffic Driving
Medium explicitly prohibits:
"Posting content primarily to drive traffic to, or increase the search rankings of, an external site, product, or service"
What triggers this:
- Same external URLs across multiple articles
- Every article linking to your GitHub/product
- Content that exists mainly to funnel readers elsewhere
Prevention: Link only when genuinely useful. Vary your sources. Make the article valuable on its own.
Automated/High-Volume Behavior
Medium explicitly prohibits:
"Performing a disproportionately large number of interactions, particularly by automated means"
What triggers this:
- 20+ articles/month
- Publishing at exact same times
- Consistent patterns that look automated
Prevention: Publish 8-10 articles/month maximum. Vary timing. Write like a human with an irregular schedule.
What's Actually Allowed
| Allowed | Conditions |
|---|
| Cross-posting from your blog | If you own the rights |
| First-party promotion | Links to your business, website, mailing list |
| Affiliate links | Must disclose per FTC rules |
| Self-promotion in bio/profile | Standard practice |
| Linking to your other Medium articles | When relevant |
AI Disclosure Requirements
If using AI assistance (which this skill implies), you must disclose.
Medium's position:
- AI-assisted content (human ideas + AI editing): Allowed, disclosure recommended
- AI-generated content (majority AI): Not allowed behind paywall
Key principle: AI assists with structure, grammar, and clarity only. The ideas, experiences, testing, and conclusions are YOUR work.
Required disclosure: Within first two paragraphs. Example:
"Note: AI tools assisted with editing this piece. The experiences, testing, and opinions are entirely my own."
Important: Rotate your disclosure format between articles to avoid pattern detection.
See references/ai-disclosure-templates.md for 10 variations to rotate.
SECTION 2: SIX CONTENT MODES
Based on analysis of Medium Staff Picks, there are six distinct modes that Medium rewards. Each has different structure, voice, and purpose.
Mode 1: Personal Essay
What it is: Narrative exploration of personal experience and meaning-making.
When to use:
- Processing life changes
- Exploring identity questions
- Sharing vulnerable experiences
- Building emotional connection with readers
Structure:
- maximum of 4 headers when needed (flows as narrative)
- Short paragraphs (1-4 sentences in random lenght)
- Scene-based storytelling, no fluff
- Unresolved or open ending
- ~2,000-2,500 words
Voice characteristics:
- Vulnerable and searching
- Short punchy sentences mixed with longer reflective ones
- Specific sensory details ("big hazel eyes," "barstool to cook dinner")
- Direct admissions of uncertainty ("Still figuring out...")
- No expert positioning—you're a fellow human, not an authority
Opening approach:
Start with a scene or dialogue, not a thesis.
Example: "'Please make sure to throw out your badge.' It was Thanksgiving
week, our almost 7-month-old son was in my arms, and my boss had just
said goodbye."
NOT: "In this article, I'll share my journey of leaving corporate America..."
Ending approach:
Don't resolve everything. Leave questions open.
Example: "I'm not sure where the trail through the trees will take me.
But I enjoy the paths that allow me to drop off and pick up my son
from school."
NOT: "Here are the 5 lessons I learned from this experience..."
What to avoid:
- Headers and sections
- Bullet points and lists
- "Tips" or "lessons learned"
- Expert positioning
- Neat resolutions
- Self-promotion
Staff pick example: "4 Years Ago, I Entered the Wilderness" — a narrative about leaving Wall Street with no headers, no tips, just honest exploration.
Evidence requirements:
- At least 2 fully-rendered scenes with sensory details (sights, sounds, physical sensations)
- Actual dialogue (exact words spoken, not paraphrased)
- Specific physical setting described (room, weather, what you were wearing)
- Emotional state in the moment captured (not retrospective interpretation)
- Timestamps or timeframes that ground the narrative ("Thursday morning", "three weeks later")
- At least one moment of uncertainty or confusion shown, not just told
Mode 2: Investigative
What it is: Deep research and evidence-based argument on a contested topic.
When to use:
- Debunking misinformation
- Challenging mainstream narratives
- Presenting original research
- Defending a position with evidence
Structure:
- Clear section headers
- Extensive citations and links
- Organized by argument, not chronology
- Evidence compilation sections
- ~4,000-6,000+ words
Voice characteristics:
- Authoritative but not arrogant
- Combative when needed ("Sorry, you can't have it both ways!")
- Direct engagement with opposition
- Specific naming of people, organizations, studies
- Clear thesis stated and defended
Opening approach:
News hook + credibility assessment of source being challenged.
Example: "A couple weeks ago, the Wall Street Journal published an op-ed
entitled [X]. The author has been affiliated with not one, but two
[problematic organizations]..."
Evidence presentation:
Don't just list studies—contextualize each one.
"By my count, at least 8 studies to date have shown that contemporary
trans youth typically become aware of their transness many months or
even years before they eventually come out to others."
Then: summarize each study's findings and relevance.
Ending approach:
Comprehensive evidence compilation, organized by sub-claim.
"I have organized these studies into four subsections: 1) studies showing
that rates of detransition have not gone up... 2) studies showing that
trans youths' gender identities are not any less stable..."
What to avoid:
- Both-sides-ing when one side is wrong
- Hedging on your thesis
- Surface-level research
- Claiming expertise you don't have
Staff pick example: "Lies, Damned Lies, and Transgender Statistics" — comprehensive debunking with 20+ academic citations.
Evidence requirements:
- Minimum 10 credible citations (academic papers, official reports, named experts)
- Named sources—not "studies show" but "Dr. Sarah Chen's 2024 Stanford study found..."
- Specific data points with methodology context (sample size, timeframe, methodology)
- Direct quotes from opposition sources (not strawmen)
- Your qualification to analyze this topic stated clearly
- Timeline of events or research if relevant
Mode 3: Advocacy
What it is: Clear position on an issue with specific recommendations for change.
When to use:
- Calling for policy changes
- Demanding industry accountability
- Proposing solutions to systemic problems
- Taking a stand on an issue you care about
Structure:
- Problem sections (specific harms with evidence)
- Analysis section (why current responses fail)
- Solutions section (numbered, specific recommendations)
- Call to action closing
- ~3,000-4,000 words
Voice characteristics:
- Controlled anger ("I've had my fill of...")
- Urgent but not hysterical
- Expert-with-stakes positioning
- Preemptive defense against dismissal ("I'm not a Luddite...")
- Direct address to those with power to change things
Opening approach:
Reframe hook—flip conventional wisdom.
Example: "They say AI is the future. For Indigenous peoples, it's starting
to look a lot like the past, except with better cameras and faster code."
Solutions format:
Numbered, specific, actionable by identified actors.
"Some recommendations include:
1. Publish a public register of all surveillance systems...
2. Require a pre-deployment assessment...
3. Prohibit high-risk biometric uses..."
Ending approach:
Collective call to action.
"AI has changed everything, and it's up to all of us to think about the
current and future impacts on society, lest AI decide for us."
What to avoid:
- Complaining without solutions
- Vague recommendations
- Preaching without evidence
- Alienating potential allies
Staff pick example: "AI's Colonial Code" — systematic analysis of AI harm to Indigenous peoples with 13 specific policy recommendations.
Evidence requirements:
- Named systems, policies, or organizations criticized (not "tech companies" but "Meta's content moderation policy")
- Specific incidents with dates and affected parties documented
- Concrete recommendations with identified actors (WHO should do WHAT by WHEN)
- Your stake in the issue made clear (why you care, what you've experienced)
- At least one documented harm with specific details (names, numbers, outcomes)
- Evidence that current responses are inadequate (what's been tried, why it failed)
Mode 4: Reflective Analysis
What it is: Personal lens on systemic observation—noticing patterns and questioning them.
When to use:
- Questioning systems you're part of
- Connecting personal experience to broader trends
- Exploring how technology/culture shapes behavior
- Raising questions more than providing answers
Structure:
- Organic chapter-like sections (not rigid)
- Personal memories as evidence
- Historical comparisons
- Open questions rather than prescriptions
- ~2,500-3,500 words
Voice characteristics:
- Thoughtful, unhurried
- Self-aware ("sounds a bit dramatic, I know, but hear me out")
- Hedged authority ("I don't think there's one standard approach")
- Nostalgia as analytical tool, not just sentiment
- Meta-commentary on own argument
Opening approach:
Current event anchor → personal connection → reframe.
Example: "Last week, I was reading one of the many articles about AI's
impact on thinking... it made me realise something that's bothered me
for years: we've been losing our capacity for deep thought long before
AI showed up."
Evidence approach:
Use memories and screenshots as exhibits in an argument.
"When the web felt like a place, it borrowed the affordances of places
as well: doors, rooms, corners, and edges. We went there, opened a door,
entered a room to research..."
[Screenshot of 2006 Blogger interface]
"What most of these spaces had in common was the way they were designed:
no character limits, no infinite feed..."
Ending approach:
Soft close with invitation to continue thinking.
"I spent way too much time writing this so if you've read this far
(thank you!) I would love to know your thoughts and where you stand
regarding this topic!"
What to avoid:
- Definitive hot takes
- Pretending you have all the answers
- Ignoring counterarguments
- Being preachy
Staff pick example: "The Design of Shallow Thinking" — personal tech history used to analyze how interface design shapes cognition.
Evidence requirements:
- Specific memories with timestamps ("In 2006, when I first used Blogger...")
- Artifacts referenced (screenshots, old emails, saved files) even if not shown
- Dated observations, not timeless claims ("Last week I noticed..." not "People often...")
- Your personal lens stated explicitly (your profession, history, stake)
- At least one moment of self-aware meta-commentary ("This might sound nostalgic, but...")
- Specific examples of the pattern you're analyzing (not abstract, but concrete instances)
Mode 5: Practitioner Experiment
What it is: Senior professional documents trying something new, shares honest assessment.
When to use:
- Testing new tools or methods
- Documenting your actual process
- Sharing balanced assessment (not cheerleading)
- Reflecting on craft and practice
Structure:
- Process documentation (planning visible)
- Meta-commentary on own approach
- Balanced pros/cons assessment
- Philosophical reflection on craft
- Nuanced conclusion (refuses hot take)
- ~2,500-3,500 words
Voice characteristics:
- Casual authority ("Pshaw.")
- Self-deprecating humor
- Footnotes for asides and nuance
- Self-interrupting meta-commentary ("Uh, where's the vibe designing part?")
- Honest about limitations ("His specific meaning was, if I'm honest, a bit beyond me")
Opening approach:
Workplace scene + "I'll do it myself" setup.
Example: "I've had this idea for a component for our product... When told
by one of my leads that none of our designers had time to help, I said
I'd just prototype it myself. 'You?' 'Yes, me! Also, what the hell?'"
Process documentation:
Show the planning, not just results.
"But first, a bit of strategy..."
"...then a quick sketch..."
"...and, finally, a brief"
Make the thinking visible.
Assessment approach:
Balanced—not cheerleading, not doom-saying.
Positive: "It's so liberating to be working with 'moments' rather than
wrestling with a tool."
Negative: "Adding too many instructions per prompt resulted in more
misinterpretations and hallucinations."
Ending approach:
Nuanced take—refuse the hot take.
"Ah, the obligatory hot take, right? Not so much... There's a time for
rapid execution of complex ideas, and there's a time for more thoughtful
and controlled development. It's not one or the other, but an
intermingling of the two."
What to avoid:
- Pure cheerleading for a tool
- Pure doom-saying
- Binary conclusions
- Hiding the messy parts
Staff pick example: "Three hours of vibe design" — senior designer tests AI design tools with honest, nuanced assessment.
Evidence requirements:
- At least ONE complete session walkthrough: prompt → response → your action → outcome
- Specific tool output shown (actual code, actual response text, actual plan—not summarized)
- At least ONE failure or limitation described with specifics (what went wrong, when, why)
- Quantified observations ("30% of the time", "3 of 5 sessions", "saved ~10 minutes")
- Specific days/times mentioned ("Tuesday's session", "By Friday I'd noticed...")
- What you're still figuring out—with specific observations, not just open questions
- Your actual use case named (the project, the problem, the context)
Mode 6: Technical (Refined)
What it is: Teaching something specific with genuine expertise and human wrapper.
When to use:
- Sharing specific technical knowledge
- Creating tutorials or guides
- Explaining complex concepts
- Building SEO presence (use sparingly)
Structure:
- Clear sections but not rigid template
- Code examples with production context
- Personal experience wrapper
- Honest tradeoffs and limitations
- Varies by topic (don't force consistency)
- ~1,500-2,500 words
Voice characteristics:
- Expert but not condescending
- Personal experience evident ("When I built this in production...")
- Honest about limitations ("This approach breaks down when...")
- Conversational, not textbook
Critical changes from old approach:
| Old Technical | New Technical |
|---|
| Template structure | Organic structure based on topic |
| Generic examples | Your actual production examples |
| "Best practices" framing | "What worked for me" framing |
| SEO-first | Story-first with SEO as bonus |
| Same hook patterns | Varies based on content |
Opening approach:
Start with YOUR experience, not generic problem statement.
Example: "Last week, I spent 3 hours debugging a Claude Code session that
kept failing silently. Turns out I was making a mistake I've seen
dozens of times in production..."
NOT: "Many developers struggle with error handling in AI agents..."
Code presentation:
Show YOUR code, explain YOUR decisions.
"Here's the actual error handling I use in production:
[code block]
I chose this approach because [specific reason from your experience],
but it has a tradeoff: [honest limitation]."
Ending approach:
What you're still figuring out.
"This approach has worked well for me, but I'm still experimenting with
[X]. If you've found a better pattern, I'd genuinely like to know."
What to avoid:
- Generic "hello world" examples
- Claiming universal best practices
- Template structures that repeat across articles
- Same hook patterns
- Pure instruction without personality
Frequency: Maximum 4-6 per month. Blend with other modes.
Evidence requirements:
- Code from YOUR actual project (named), not generic examples
- Real error messages or problems you encountered (copy/paste actual output)
- Before/after code showing the evolution of your solution
- Specific context: what project, what scale, what constraints
- At least ONE approach that didn't work (and why)
- Performance claims backed by numbers with methodology ("In my testing with 1K records...")
- What you'd do differently next time
SECTION 3: MODE SELECTION & BLENDING
How to Choose a Mode
Ask yourself:
| Question | If Yes → Mode |
|---|
| Am I processing a personal change or struggle? | Personal Essay |
| Am I trying to debunk or prove something with evidence? | Investigative |
| Am I calling for specific changes? | Advocacy |
| Am I questioning a system I'm part of? | Reflective Analysis |
| Am I documenting trying something new? | Practitioner Experiment |
| Am I teaching a specific skill or technique? | Technical |
Topic → Mode Examples
| Topic | Possible Modes |
|---|
| "I got suspended from Medium" | Personal Essay (the experience) or Advocacy (platform accountability) |
| "Claude Code changed how I work" | Practitioner Experiment or Reflective Analysis |
| "AI content disclosure" | Advocacy (policy) or Reflective Analysis (questioning) |
| "10 Claude Code commands" | Technical (but make it personal) |
| "Why I'm burned out on tutorials" | Personal Essay |
| "The myth of AI productivity" | Investigative or Advocacy |
When to Blend Modes
The best staff picks often blend modes. Common combinations:
Personal → Advocacy:
Start with personal experience, pivot to systemic analysis, end with recommendations.
"When I got suspended from Medium, I thought it was just me.
Then I talked to 15 other AI content creators..."
[Personal opening → Investigative middle → Advocacy close]
Reflective Analysis → Soft Advocacy:
Question a system, end with open questions rather than prescriptions.
"I've noticed my thinking has changed since I started using Claude Code daily.
Is this happening to other developers?"
[Observation → Analysis → Open questions]
Practitioner Experiment → Technical:
Document trying something, then share the specific techniques that worked.
"I spent a week trying to automate my data analysis workflow. Here's
the honest assessment—and the three patterns that actually stuck."
[Experiment narrative → Technical specifics]
Mode Blending Guidelines
- Lead with your strongest mode — what comes naturally for this topic?
- Blend at transitions — use personal anecdote to introduce technical section
- Don't force it — if a pure mode works, use it
- Let the topic dictate — some topics naturally span modes
SECTION 4: VOICE & CRAFT
Core Principle: Write Like a Human
Medium's stated value: "A home for human stories and ideas."
Human writing characteristics:
- Irregular sentence lengths (5 words. Then 25 words with a dependent clause that winds through an idea before landing.)
- Personal asides ("I know this sounds dramatic, but...")
- Uncertainty acknowledged ("I'm still figuring this out")
- Specific details, not generic claims
- Emotional honesty
- Self-interrupting thoughts
What makes writing feel AI-generated:
- Uniform sentence lengths
- "Furthermore," "Moreover," "In conclusion"
- Hedging without commitment ("can potentially help improve")
- Generic examples
- Corporate language ("leverage," "utilize," "facilitate")
- Perfect structure (no tangents, no personality)
Vulnerability Markers
Staff picks consistently include vulnerability:
"I wish I could say the decision was easy for me."
"Still searching for purpose. Still hunting for achievement."
"I'm not at all confident with what that station actually is."
"His specific meaning was, if I'm honest, a bit beyond me."
"I spent way too much time writing this."
Include at least 2-3 moments of honest uncertainty or admission per article.
Nuanced Conclusions
Medium rewards nuance over hot takes.
Hot take (avoid):
"AI will replace all developers within 5 years."
"Figma is dead."
"Medium's algorithm is broken."
Nuanced conclusion (use):
"There's a time for rapid execution of complex ideas, and there's a time
for more thoughtful development. It's not one or the other, but an
intermingling of the two."
"This approach has worked well for me at my current scale. Whether it
holds up at 10x volume, I genuinely don't know."
"I don't have a clean answer to this. I'm sharing my questions more
than my conclusions."
Self-Aware Meta-Commentary
Staff picks often include moments where the author steps outside the argument:
"Sounds a bit dramatic, I know, but hear me out."
"Uh, where's the vibe designing part?" (self-interruption)
"And if you're able to go past the hint of nostalgic romanticism of
my argument..."
"Chances are you're scanning through this post right now."
This signals: I'm a human aware of how this might sound, not a content machine.
Specificity Over Generality
| Generic (AI-sounding) | Specific (Human) |
|---|
| "Many developers struggle with this" | "Last Tuesday, I spent 3 hours on this exact problem" |
| "Performance improved significantly" | "P95 latency dropped from 800ms to 45ms" |
| "In today's fast-paced world" | [Delete entirely] |
| "It's important to note that" | [Just state the thing] |
| "A leading tech company" | "Stripe's engineering team" |
Human Voice Validation Checklist
AI Patterns to Remove:
Corporate speak:
AI: "Leverage cutting-edge technologies to facilitate seamless integration."
Human: "Use modern tools to connect systems easily."
Words to avoid: leverage, utilize, facilitate, robust, comprehensive, seamless, cutting-edge
Hedging:
AI: "This approach can potentially help improve performance in certain scenarios."
Human: "This approach improves performance when [specific condition]."
Remove: "it's worth noting", "it's important to", "there are", "in certain scenarios"
Mechanical transitions:
AI: "Furthermore", "Moreover", "Subsequently", "In conclusion"
Human: "Here's why", "But wait", "Next", "So what did we learn?"
Sentence Variation:
AI (monotonous):
"This approach offers better performance. It provides improved scalability. It ensures reliable operation."
Human (varied):
"This approach delivers better performance. Why? It scales horizontally without bottlenecks. And when things go wrong—which they will—the retry logic keeps the system stable."
Pattern: Mix short punchy sentences with longer explanatory ones. Add questions. Use dashes.
Voice Consistency Checks:
SECTION 4B: THE SPECIFICITY STANDARD
Writers know to be "specific" but often don't know HOW specific. This section shows the gap between generic claims and evidence-based writing.
Weak vs. Strong Specificity
| Weak (Generic) | Strong (Specific) |
|---|
| "After a week of testing" | "Tuesday's session revealed... By Friday I'd noticed..." |
| "I ran a session where I asked it to analyze a module" | "The module was my order processing script—1,847 lines handling imports, validation, and export" |
| "The plan it produced was actually good" | "The plan identified 4 extraction candidates with line numbers and coupling analysis" |
| "I'm still figuring out when to use it" | "My 3-file heuristic is rough—I invoke it wrong about 30% of the time" |
| "It sometimes struggles with X" | "Saturday it produced a 6-step plan for a border-color change. Overkill." |
| "Performance improved" | "P95 latency dropped from 847ms to 112ms" |
| "I had some failures" | "Thursday's rate-limit config was wrong—I'd asked for 1000/hour but got 100/15min" |
| "The tool helped with refactoring" | "Opus 4.5 found 3 extraction candidates: SubscriberValidator, SegmentBuilder, CampaignDispatcher" |
| "I tested it on a real project" | "I used it on my newsletter automation—2,100 lines handling subscriber imports and campaign scheduling" |
| "It saved time" | "Time saved: maybe 10 minutes. Frustration saved: significant." |
The Specificity Test
For every claim in your draft, ask:
1. The Swap Test
Could I swap in a different example and the paragraph would still work?
- If YES → You're being generic. Add YOUR specific details.
- If NO → Good. The paragraph depends on your specific experience.
2. The "Like What?" Test
Read each claim. Ask "Like what? Show me."
- "The feature helped" → Like what? Show me a specific instance.
- "I ran into problems" → Like what? Show me one problem.
- "Performance improved" → Like what? Show me numbers.
3. The Timestamp Test
Does this paragraph anchor to a specific time?
- "This week" → Weak. When this week?
- "Tuesday afternoon" → Strong. Specific.
- "Recently" → Weak. When?
4. The Artifact Test
Could you show a screenshot/code snippet for this claim?
- If YES but you didn't include it → Include it.
- If NO → Is the claim too vague to have evidence?
SECTION 4C: BEFORE YOU WRITE — EVIDENCE EXTRACTION
Problem: Writers have experiences but don't know how to surface the specific details their article needs.
Solution: Answer these prompts BEFORE drafting to gather your evidence inventory.
Universal Evidence Prompts (All Modes)
Before writing anything, answer:
- What specific thing happened? (Not category—instance)
- When exactly? (Day, date, time of day)
- What did you see/hear/do? (Sensory details, actions taken)
- What was the actual output/result? (Can you copy-paste it?)
- What went wrong at least once? (Failures build credibility)
- What numbers can you attach? (Time, count, percentage, before/after)
Mode-Specific Evidence Prompts
For Practitioner Experiment Mode:
- What specific thing were you trying to build/fix/improve?
- Walk through ONE session step-by-step: What did you ask? What happened? What did you do next?
- What exact output did the tool produce? (Copy/paste if possible)
- What went WRONG? Describe one specific failure.
- What numbers can you attach? (Time saved, errors caught, files changed, attempts needed)
- What day/time did key moments happen?
- What are you still calibrating? (With specific observations, not just questions)
For Personal Essay Mode:
- Describe the physical setting of the key moment. What did you see/hear/feel?
- What exact words were said? Recreate dialogue.
- What were you wearing? Where were you sitting/standing?
- What did you think in that exact moment? (Not what you think now—what you thought then)
- What uncertainty or confusion did you feel? (Not looking back—in the moment)
For Investigative Mode:
- What's your thesis in one sentence?
- List 10+ sources with author names and publication dates.
- What does the opposition actually say? (Direct quotes, not paraphrase)
- What's your credential or qualification to analyze this?
- What's the strongest counterargument, and how do you address it?
For Advocacy Mode:
- Name the specific system, policy, or organization you're criticizing.
- Document one specific harm with names, dates, and outcomes.
- What's been tried before? Why did it fail?
- List your recommendations with WHO should do WHAT by WHEN.
- What's your personal stake in this issue?
For Reflective Analysis Mode:
- What specific memory grounds your analysis? (Year, context, sensory details)
- What artifact could you reference? (Screenshot, email, saved file)
- What pattern are you noticing? Give three specific instances.
- What's your professional or personal lens on this?
- What are you uncertain about? (Honest admission)
For Technical Mode:
- What real project is this from? Name it and describe the context.
- What was the actual error message or problem? (Copy-paste)
- Show the actual code—before and after.
- What didn't work the first time?
- What would you do differently now?
- What are the specific constraints of your use case? (Scale, team size, timeline)
Using the Evidence Extraction Worksheet
For more structured preparation, use the templates/evidence-extraction-worksheet.md file to document your evidence inventory before drafting.
SECTION 5: MODE-SPECIFIC QUALITY GATES
I am your ruthless content mentor. My job: Make content bulletproof before publication.
Core principle: Different modes have different quality criteria. One-size-fits-all templates caused the suspension. Mode-specific gates ensure quality while preventing detectable patterns.
Personal Essay Mode Quality Gate
REJECT if:
❌ Uses headers
- Personal essays flow as narrative, not structured content
- Fix: Remove all headers, let story flow naturally
❌ Neat resolution
- "Here are the 5 lessons I learned" = death of essay mode
- Fix: Leave questions open, show ongoing journey
❌ Expert positioning
- You're a fellow human exploring, not an authority lecturing
- Fix: Add uncertainty, show vulnerability
❌ Missing sensory details
- Generic descriptions won't connect emotionally
- Fix: Add specific moments ("big hazel eyes," "Thursday afternoon")
❌ Tips/lessons format
- This is essay mode, not listicle mode
- Fix: Tell the story, let readers extract their own meaning
APPROVE when:
- ✅ Vulnerable and searching tone throughout
- ✅ Scene-based with specific sensory details
- ✅ Unresolved or open ending
- ✅ No expert positioning
- ✅ Narrative flow (no headers, no lists)
Investigative Mode Quality Gate
REJECT if:
❌ Weak thesis
- Hedging or both-sides-ing when one side is wrong
- Fix: State thesis clearly and defend it
❌ Missing citations
- Claims without sources = not investigative
- Fix: Add 10+ credible sources minimum
❌ Surface research
- Quick Google search doesn't count as investigation
- Fix: Deep dive into primary sources, academic papers, interviews
❌ No engagement with opposition
- You must address counterarguments directly
- Fix: Quote opponents, then refute with evidence
❌ Expertise not demonstrated
- Why should readers trust your analysis?
- Fix: Show your work, credentials, or deep familiarity
APPROVE when:
- ✅ Clear thesis stated and defended
- ✅ 10+ credible citations
- ✅ Opposition addressed and refuted
- ✅ Evidence organized systematically
- ✅ Authoritative but not arrogant voice
Advocacy Mode Quality Gate
REJECT if:
❌ Complaining without solutions
- Problem → Solution structure is required
- Fix: Add numbered, specific recommendations
❌ Vague recommendations
- "We need to do better" is not actionable
- Fix: Specific actors + specific actions + specific outcomes
❌ Missing actors
- Who should do what?
- Fix: Name the people, organizations, or roles responsible
❌ Preaching without evidence
- Moral authority requires factual grounding
- Fix: Add data, studies, or documented cases
❌ No call to action
- Advocacy requires asking readers to do something
- Fix: End with clear next steps for readers
APPROVE when:
- ✅ Problem clearly defined with evidence
- ✅ Solutions are numbered, specific, actionable
- ✅ Actors identified (who should do what)
- ✅ Evidence supports claims
- ✅ Call to action present
Reflective Analysis Mode Quality Gate
REJECT if:
❌ Hot takes
- This mode is for nuance, not declarations
- Fix: Add qualifications, acknowledge complexity
❌ Definitive answers
- You should raise questions more than answer them
- Fix: End with open questions, invite reader reflection
❌ Missing personal lens
- Your observation and experience should ground the analysis
- Fix: Add "I noticed..." or personal anecdote
❌ No meta-commentary
- Self-awareness signals humanity
- Fix: Add "sounds dramatic, I know" or similar
❌ Preachy tone
- You're exploring together, not lecturing
- Fix: Soften certainty, invite disagreement
APPROVE when:
- ✅ Personal lens grounds the analysis
- ✅ Open questions rather than prescriptions
- ✅ Nuanced, acknowledges complexity
- ✅ Invites reader reflection
- ✅ Self-aware meta-commentary present
Practitioner Experiment Mode Quality Gate
REJECT if:
❌ Process not visible
- Show planning, thinking, false starts
- Fix: Add "Here's what I tried first..." or "My initial approach was..."
❌ Pure cheerleading
- Every tool has downsides
- Fix: Add balanced assessment with specific negatives
❌ Pure doom-saying
- If it was all bad, why did you try it?
- Fix: Acknowledge what worked, even if limited
❌ Binary conclusion
- "This is great" or "This is terrible" = hot take
- Fix: "It depends on..." or "For X use case..."
❌ Hides messy parts
- Readers want to see your actual experience
- Fix: Show failures, confusion, iteration
APPROVE when:
- ✅ Process visible (planning, attempts, iteration)
- ✅ Balanced assessment (pros AND cons with specifics)
- ✅ Honest about limitations and failures
- ✅ Nuanced conclusion (refuses hot take)
- ✅ Messy parts included
Technical Mode Quality Gate
REJECT if:
❌ Generic code examples
- "Hello world" level code doesn't demonstrate expertise
- Fix: Show production-grade code with error handling, timeouts, edge cases
❌ Vague performance claims
- "Significantly faster" without numbers = fabrication
- Fix: Add benchmarks with methodology or remove claim
❌ No tradeoffs discussed
- Everything has downsides
- Fix: Add "When to use" vs. "When NOT to use" with specific constraints
❌ Template structure
- Same structure as other articles = detectable pattern
- Fix: Let content dictate structure, vary between articles
❌ Missing personal experience wrapper
- This should be YOUR experience, not generic tutorial
- Fix: Add "When I built this..." or "In production, I found..."
❌ Code not tested
- If you haven't run it, don't publish it
- Fix: Test all code examples, include actual output
APPROVE when:
- ✅ Production-grade code (error handling, timeouts, edge cases)
- ✅ Benchmarks with methodology (or explicit "in my testing" qualifier)
- ✅ Tradeoffs discussed (when to use / when not to use)
- ✅ Personal experience evident
- ✅ Code tested and verified
- ✅ Structure varies from other articles
Universal Quality Checks (All Modes)
Before approving ANY article, verify:
Compliance:
Voice:
Value:
SECTION 6: SUSTAINABLE PRACTICE
Intentional Slowness
Medium's successful writers (per their own interviews) use the platform for voice development, not income maximization.
Publishing rhythm:
- 8-10 articles/month maximum
- Mix of modes (not all technical)
- Quality over quantity
- "Measure twice, cut once"
Between articles:
- Read other writers on Medium
- Engage in community (Writing Hour, responses)
- Let ideas develop before writing
The Repurposing Model
Medium as starting point, not destination:
Idea/experience
↓
Medium article (develop voice, test resonance)
↓
├── Works well? → Repurpose to newsletter (Beehiiv)
├── Technical? → Cross-post to Hashnode/Dev.to
├── Gets traction? → Expand into thread, podcast, etc.
└── Builds authority? → Leads to external opportunities
Medium is the lab. External platforms are distribution. Opportunities are the outcome.
External Opportunities Model
Stop thinking of Medium as income source. Think of it as:
| Medium Provides | Which Leads To |
|---|
| Voice development | Better client communication |
| Portfolio of thinking | Credibility for consulting |
| Niche authority | Paid writing opportunities |
| Reader connections | Potential clients/collaborators |
| Writing practice | Newsletter you can monetize |
Real income comes from:
- Paid writing programs ($300-500/article elsewhere)
- Newsletter monetization (Beehiiv with your subscribers)
- Consulting/services (your AI expertise)
- Products (courses, tools, templates)
Medium is the top of funnel, not the revenue center.
Avoiding Burnout
The old approach led to burnout because:
- Same content mode every time (tutorials)
- Template-driven (no creative challenge)
- Metrics-focused (extrinsic motivation)
- High velocity (quantity over quality)
The new approach prevents burnout by:
- Six modes to choose from (variety)
- Each article is unique (creative challenge)
- Voice development focus (intrinsic motivation)
- Intentional slowness (sustainable pace)
If you're dreading writing the article, choose a different mode.
SECTION 7: PRACTICAL WORKFLOW
Starting an Article
Step 1: What's alive for you?
Not "what should I write about" but "what am I actually thinking about?"
- What kept you up last night?
- What did you learn this week?
- What are you struggling with?
- What made you angry or excited?
Step 2: Choose a mode
Based on your energy and the topic:
- Need to process? → Personal Essay
- Need to prove something? → Investigative
- Need to call for change? → Advocacy
- Need to question something? → Reflective Analysis
- Tried something new? → Practitioner Experiment
- Want to teach? → Technical
Step 3: Let structure emerge
Don't start with a template. Start with:
- The one thing you want to say
- The experience or evidence that supports it
- The honest limitations or uncertainties
Step 4: Write ugly first
Get the ideas down. Don't polish while drafting.
Voice and structure can be refined. Ideas can't be added later if you don't capture them now.
Step 5: Revise for humanity
- Add vulnerability markers
- Vary sentence lengths
- Remove AI-sounding phrases
- Add specific details
- Include self-aware moments
AI Assistance Guidelines
Using AI assistance (including this skill) is fine, but:
AI should help with:
- Grammar and clarity
- Organizing existing ideas
- Catching errors
- Suggesting alternatives
AI should NOT:
- Generate your ideas
- Write your personal experiences
- Create your unique perspective
- Produce the majority of content
The test: If you removed all AI-assisted text, would there still be an article? If yes, you're using AI correctly. If no, you're generating content, not writing.
Always disclose AI assistance.
Scripts Integration
This skill includes Python tools for validation and research.
Content Analyzer
Purpose: Validates finished content against SEO, readability, Medium compliance, and AI detection.
Usage:
python scripts/content_analyzer.py article.md "Title" "Subtitle"
Output includes:
- Overall quality score (0-100)
- SEO score (keywords, title, structure)
- Readability score (sentence length, complexity, active voice)
- Medium compliance (Boost eligibility prediction)
- AI detection (flags AI-marker words and patterns)
- Distribution prediction (Boost/General/Network Only)
- Actionable warnings and improvement suggestions
When to use: After completing draft, before final polish. Address warnings before publishing.
Search Intelligence MCP
Purpose: Real-time search data for keyword research and trend analysis.
Tools included:
analyze_trends() - Google Trends data (no auth needed)research_keywords() - Comprehensive keyword researchanalyze_search_intent_tool() - Intent classificationquery_search_console() - Real GSC performance data (optional auth)
When to use: During research phase for Technical mode or SEO-focused content.
Pre-Publish Checklist
Compliance
Evidence Depth (NEW in v3.1)
Specificity Test (NEW in v3.1)
Quality (Mode-Specific)
Practical
SEO Enforcement Standards (MANDATORY)
Complete SEO standards are in references/seo-enforcement-guide.md. This section provides a summary.
Articles failing ANY standard get REJECTED.
Quick Reference: SEO Requirements
| Element | Requirement | Enforcement |
|---|
| Title | 50-60 chars, keyword in first 4 words, no version | REJECT if non-compliant |
| Subtitle | 150-160 chars, keywords + experience signal | REJECT if non-compliant |
| H2 Headers | ≥40% contain keywords, 1 has primary | REJECT if below threshold |
| First 100 Words | Primary keyword present (after AI disclosure) | REJECT if missing |
| AEO Section | Required before conclusion, 3+ answers | REJECT if missing |
| Classification | Evergreen or Time-Sensitive declared | REJECT if undeclared |
| Tags | 5 total: 1 primary + 2 broad + 2 niche | REJECT if wrong mix |
SEO Pre-Publish Gate
Score 12+/14 to publish:
Title (3 pts): 50-60 chars ☐ | Keyword first 4 words ☐ | No version ☐
Subtitle (3 pts): 150-160 chars ☐ | Keywords present ☐ | Experience signal ☐
Headers (2 pts): 40%+ with keywords ☐ | One has primary ☐
Content (2 pts): Keyword in first 100 words ☐ | Classification declared ☐
AEO (2 pts): Section present ☐ | 3+ extractable answers ☐
Tags (2 pts): 5 tags ☐ | Proper mix ☐
| Score | Action |
|---|
| 14/14 | ✅ PUBLISH |
| 12-13 | ⚠️ Fix gaps, then publish |
| 10-11 | 🔄 Significant revision needed |
| <10 | ❌ REJECT — Major rewrite |
For Complete Standards
See references/seo-enforcement-guide.md for:
- Part 1: 10-minute keyword research workflow
- Parts 2-8: Detailed enforcement standards with examples
- Part 9: Content structure templates
- Part 10: E-E-A-T compliance
- Parts 11-12: Link strategy and image optimization
- Part 13: Full pre-publish checklist
- Parts 14-15: SEO tools and post-publish workflow
- Common mistakes table (reject triggers)
SECTION 8: TECHNICAL MODE DEEP DIVE
Purpose: Production-ready code patterns and benchmark standards for Technical mode. Ensures credibility and demonstrates genuine expertise.
Note: This section is specifically for Technical mode. Don't apply these patterns to other modes.
Production Code Patterns
Using Current Versions: LangChain v1.0+, GPT-4o, Claude 3.5 Sonnet (as of November 2025)
Pattern 1: LangChain Agent Setup
Production-Ready Agent with Error Handling:
from langchain.agents import create_openai_tools_agent, AgentExecutor
from langchain_openai import ChatOpenAI
from langchain.tools import tool
@tool
def search_codebase(query: str) -> str:
"""Search internal codebase for relevant code snippets."""
try:
result = search_with_timeout(query, timeout=5.0)
return f"Found: {result}"
except TimeoutError:
return "Search timed out. Try a more specific query."
except Exception as e:
return f"Search failed: {str(e)}"
llm = ChatOpenAI(
model="gpt-4o",
temperature=0.0,
request_timeout=30.0,
max_retries=2
)
agent = create_openai_tools_agent(llm, tools=[search_codebase], prompt=prompt)
agent_executor = AgentExecutor(
agent=agent,
tools=tools,
max_iterations=5,
max_execution_time=60,
return_intermediate_steps=True,
handle_parsing_errors=True
)
try:
result = agent_executor.invoke({"input": user_query})
except TimeoutError:
result = {"error": "Agent exceeded time limit"}
Key Production Considerations:
- Always set
request_timeout (prevents hanging on slow LLM API)
max_iterations prevents infinite loops (LLM keeps calling tools)max_execution_time is hard timeout (kills execution after N seconds)handle_parsing_errors=True catches malformed tool calls- Individual tools should have timeouts too (defense in depth)
Pattern 2: RAG Pipeline Implementation
Production RAG with Timeouts and Error Handling:
import { Pinecone } from '@pinecone-database/pinecone';
import Anthropic from '@anthropic-ai/sdk';
interface RAGResult {
answer: string;
sources: string[];
confidence: number;
}
async function ragQuery(
query: string,
options = { maxSources: 3, minConfidence: 0.7, timeout: 5000 }
): Promise<RAGResult> {
const pinecone = new Pinecone();
const index = pinecone.Index('production-docs');
const searchResults = await Promise.race([
index.query({
vector: await embedQuery(query),
topK: options.maxSources,
includeMetadata: true,
}),
timeout(options.timeout, 'Vector search timeout')
]);
const relevantDocs = searchResults.matches
.filter(match => match.score >= options.minConfidence)
.map(match => match.metadata.text);
if (relevantDocs.length === 0) {
return {
answer: "No relevant information found in knowledge base.",
sources: [],
confidence: 0
};
}
const anthropic = new Anthropic();
const response = await anthropic.messages.create({
model: 'claude-3-5-sonnet-20241022',
max_tokens: 1024,
messages: [{
role: 'user',
content: `Context:\n${relevantDocs.join('\n\n')}\n\nQuestion: ${query}\n\nProvide a concise answer based only on the context above.`
}]
});
return {
answer: response.content[0].text,
sources: searchResults.matches.map(m => m.metadata.source),
confidence: Math.max(...searchResults.matches.map(m => m.score))
};
}
function timeout(ms: number, message: string): Promise<never> {
return new Promise((_, reject) =>
setTimeout(() => reject(new Error(message)), ms)
);
}
Key Production Considerations:
Promise.race with timeout prevents hanging on slow vector searchminConfidence threshold (0.7) filters low-quality matches- Handles empty results explicitly (don't generate from nothing)
- Returns sources for verification (trust & debugging)
- LLM prompted to say "I don't know" when context insufficient
Pattern 3: Multi-Agent Context Handoff
Stateless Handoff Pattern (Optimized for Latency):
from typing import Dict, Any
import asyncio
class AgentHandoff:
"""Lightweight context passing between agents.
Optimizes for latency over perfect consistency.
"""
async def handoff_context(
self,
from_agent: str,
to_agent: str,
context: Dict[str, Any],
max_context_size: int = 4096
) -> Dict[str, Any]:
"""
Pass minimal context between agents.
Tradeoff: Drops ~30% of context for 3x faster handoff.
Use when: High throughput (>1K req/sec) and latency-sensitive.
"""
essential_context = {
'task_id': context['task_id'],
'current_state': context['state'],
'last_action': context['actions'][-1],
'error_count': len([a for a in context['actions'] if a['status'] == 'error'])
}
context_str = str(essential_context)
if len(context_str) > max_context_size:
essential_context.pop('last_action', None)
await self.notify_agent(to_agent, essential_context)
return essential_context
Key Production Considerations:
- Minimizes context size for speed (drops full history, keeps essentials)
- Async handoff (don't block on agent B being ready)
- Size constraint enforcement (prevents token overflow)
- Tradeoff explicit: 30% context loss for 3x latency improvement
Pattern 4: Tool Execution Sandboxing
Docker-Based Code Execution with Resource Limits:
import docker
from typing import Dict, Any
def execute_code_safely(
code: str,
language: str = "python",
timeout: int = 30,
memory_limit: str = "512m",
cpu_limit: float = 1.0
) -> Dict[str, Any]:
"""
Execute untrusted code in isolated Docker container.
Security boundaries:
- No network access (network_mode="none")
- Read-only filesystem (prevents malicious writes)
- Memory/CPU limits (prevents resource exhaustion)
- Timeout enforcement (prevents infinite loops)
"""
client = docker.from_env()
images = {
"python": "python:3.11-slim",
"javascript": "node:20-slim"
}
try:
container = client.containers.run(
image=images[language],
command=f"{language} -c '{code}'",
mem_limit=memory_limit,
nano_cpus=int(cpu_limit * 1_000_000_000),
network_mode="none",
read_only=True,
remove=True,
detach=True,
security_opt=["no-new-privileges"]
)
result = container.wait(timeout=timeout)
return {
"stdout": container.logs(stdout=True).decode('utf-8'),
"stderr": container.logs(stderr=True).decode('utf-8'),
"exit_code": result['StatusCode'],
"success": result['StatusCode'] == 0
}
except docker.errors.ContainerError as e:
return {
"stdout": "",
"stderr": f"Container error: {str(e)}",
"exit_code": -1,
"success": False,
"error": "Container execution failed"
}
except Exception as e:
if 'container' in locals():
container.kill()
return {
"stdout": "",
"stderr": f"Timeout after {timeout}s",
"exit_code": -1,
"success": False,
"error": "Execution timeout"
}
Key Security Considerations:
network_mode="none": Prevents code from making external requestsread_only=True: Prevents writing malicious files to filesystemmem_limit + nano_cpus: Prevents resource exhaustion attackstimeout: Kills container if code runs too longsecurity_opt: Additional Docker security hardening
AI Performance Benchmark Standards
Purpose: Standard formats for reporting AI system performance. Using these builds credibility—readers can reproduce your results.
Using Current Pricing: GPT-4o ($2.50 input / $10 output per 1M tokens), Claude 3.5 Sonnet ($3 input / $15 output per 1M tokens) - as of November 2025
Format 1: LLM API Latency Reporting
Model: [Model name + version]
Context: [Input tokens], [Output tokens]
Measured over: [Sample size] requests
Infrastructure: [Where: local/AWS/GCP]
Date: [When measured]
Results:
- P50: [Xms]
- P95: [Xms]
- P99: [Xms]
Cost: $[X.XX] per request
Throughput: [X] req/sec
Methodology: [Tool, concurrency]
Example:
Model: GPT-4o (gpt-4o-2024-11-20)
Context: 4,000 input tokens, 500 output tokens
Measured over: 10,000 requests
Infrastructure: AWS us-east-1, t3.xlarge
Date: November 2025
Results:
- P50: 1,200ms
- P95: 2,300ms
- P99: 4,100ms
Cost: $0.015 per request
Throughput: 45 req/sec
Methodology: Apache Bench, 100 concurrent, 2-hour test
Format 2: Token Usage & Cost Analysis
Operation: [What you're measuring]
Input Tokens:
- [Component 1]: [X] tokens
- [Component 2]: [X] tokens
- Total input: [X] tokens
Output Tokens: [X] tokens
Cost ([Model] pricing):
- Input: [X] tokens × $[X]/1M = $[X.XX]
- Output: [X] tokens × $[X]/1M = $[X.XX]
- Total per operation: $[X.XX]
At [volume]/month: $[X,XXX]/month
Optimization:
- [Suggestion]: [% reduction]
Format 3: Agent Tool Call Success Rate
Agent: [Name/type]
Period: [Timeframe]
Total interactions: [X]
Tool Breakdown:
- [tool]: [X] calls, [X.X%] success
- [tool]: [X] calls, [X.X%] success
Overall: [X.X%] success
Failures:
1. [Type]: [X.X%] - [Explanation]
2. [Type]: [X.X%] - [Explanation]
Mitigation:
- [Action]: [Impact]
Format 4: RAG Retrieval Quality
System: [Description]
Evaluation: [X] labeled queries
Retrieval:
- Precision@K: [X.XX]
- Recall@K: [X.XX]
- MRR: [X.XX]
Answer Quality:
- Accuracy: [X%]
- Hallucination rate: [X.X%]
- "I don't know" rate: [X.X%]
User Satisfaction:
- Thumbs up: [X%]
- Escalation: [X%]
SECTION 9: DELIVERABLE PACKAGE
Purpose: Deliver complete publication package (not just the article).
A. Three Headline Options
Generate 3 variations, each optimized differently:
Option A - SEO Optimized (50-60 chars):
- Primary keyword in first 4 words
- Clear technical promise
- Format: "[Keyword]: [Specific Outcome]"
- Example: "RAG Pipelines: Scale from 100 to 10K Concurrent Queries"
Option B - Curiosity Driven (50-60 chars):
- Contrarian angle or surprising insight
- Maintains technical credibility
- Format: "Why [Common Belief] Is Wrong ([Truth])"
- Example: "Why Most RAG Implementations Fail (And How to Fix Them)"
Option C - Outcome Focused (50-60 chars):
- Specific metric or transformation
- Numbers when possible
- Format: "[Action]: [Metric Improvement]"
- Example: "Reduce RAG Latency from 2.3s to 180ms: Complete Guide"
B. SEO Summary
Primary Keyword: [main keyword, 500-10K monthly searches]
Secondary Keywords: [3-4 related keywords]
LSI Keywords: [6-10 semantic variations]
Keyword Density: [calculate: keyword mentions / total words × 100]
Target: 1-2% primary keyword density
Meta Description (First 155 characters):
[Verify first 155 chars of article work as compelling standalone summary]
Target Audience: [who this is for - be specific]
Search Intent: [informational / comparison / tutorial]
Top 3 Competing Articles:
1. [URL] - [What they cover well]
2. [URL] - [What they cover well]
3. [URL] - [What they cover well]
Unique Angle: [One sentence]
Content Gap Filled: [What was missing that you provide]
C. Medium Platform Notes
Recommended Tags (5 max, priority order):
1. [Primary tag - 100K+ followers, broad category]
2. [Secondary tag - 50K+ followers]
3. [Medium tag - 10K+ followers]
4. [Niche tag - 1K-5K followers]
5. [Specific tag - related to exact topic]
Best Publish Time: Tuesday-Thursday, 6-9 AM PT
Reasoning: Tech audience most active weekday mornings
First Comment Strategy:
[Suggest what to post in first comment within 5 minutes]
Example: "The hardest part of building this was [challenge]. What's been your biggest [topic] challenge? Thread your experience below"
Visual Elements Suggested:
- [Location 1]: [Type - diagram/screenshot/code] showing [what]
- [Location 2]: [Type] showing [what]
- [Location 3]: [Type] showing [what]
Expected Reading Time: [Calculate: words / 200 = minutes]
Target: 7-10 minutes (1,400-2,000 words)
Distribution Strategy:
Recommendation: [Personal profile vs. publication - choose based on goals]
D. Complete Package Format
Deliver to user as:
# [Article Title] - PUBLICATION PACKAGE
## 1. FINAL ARTICLE (Markdown)
[Full article content]
---
## 2. HEADLINE OPTIONS
**A. SEO Optimized:** [headline]
**B. Curiosity Driven:** [headline]
**C. Outcome Focused:** [headline]
**Recommendation:** [Which one and why]
---
## 3. SEO SUMMARY
**Keywords:**
- Primary: [keyword]
- Secondary: [list]
- LSI: [list]
- Density: [X%]
**Meta Description:** [first 155 chars]
**Competition:**
- [URL 1]: [Coverage]
- [URL 2]: [Coverage]
- [URL 3]: [Coverage]
**Unique Angle:** [statement]
---
## 4. PLATFORM NOTES
**Tags:** [5 tags]
**Publish Time:** Tuesday-Thursday 6-9 AM PT
**First Comment:** [suggestion]
**Visuals:** [3 suggestions]
**Read Time:** [X min]
**Distribution:** [recommendation]
SECTION 10: QUICK REFERENCE
Mode Selection Matrix
| I want to... | Mode | Key Feature |
|---|
| Process something personal | Personal Essay | No headers, vulnerable, unresolved |
| Debunk or prove | Investigative | Evidence-heavy, citations |
| Call for change | Advocacy | Problem → Solution structure |
| Question a system | Reflective Analysis | Personal lens, open questions |
| Share an experiment | Practitioner Experiment | Process visible, balanced assessment |
| Teach something | Technical | Personal experience wrapper |
Voice Quick Fixes
| If it sounds like this... | Change to this... |
|---|
| "Many developers struggle with" | "Last week, I spent 3 hours on" |
| "It's important to note that" | [Delete, just state it] |
| "Furthermore" / "Moreover" | [New paragraph, or "And" / "But"] |
| "In conclusion" | [Just write the conclusion] |
| "This approach can potentially help" | "This worked for me when" |
| "Leverage" / "Utilize" | "Use" |
Compliance Quick Check
Before every publish:
- AI disclosure in first two paragraphs? ✓
- Structure different from last article? ✓
- External links genuinely useful (not just traffic)? ✓
- Not second article today? ✓
- Not forcing a template? ✓
Content Type vs. Mode Mapping
| Old Content Type | New Mode | Key Change |
|---|
| Deep Technical | Technical | Add personal wrapper, organic structure |
| Tutorial | Technical | Vary structure, show YOUR experience |
| Thought Leadership | Reflective Analysis or Advocacy | Less hot takes, more nuance |
| Problem-Solving | Practitioner Experiment | Show process, balanced assessment |
Quality Gate Quick Reference
| Mode | Must Have | Must NOT Have |
|---|
| Personal Essay | Vulnerability, scenes, open ending | Headers, lists, lessons |
| Investigative | 10+ citations, thesis, opposition addressed | Hedging, both-sides-ing |
| Advocacy | Specific solutions, actors named, CTA | Complaining without solutions |
| Reflective Analysis | Personal lens, open questions, nuance | Hot takes, preachy tone |
| Practitioner Experiment | Process shown, balanced pros/cons | Pure cheerleading/doom-saying |
| Technical | Production code, benchmarks, tradeoffs | Generic examples, template structure |
AI Patterns to Avoid
| AI Pattern | Human Alternative |
|---|
| "Leverage cutting-edge technologies" | "Use modern tools" |
| "Can potentially help improve" | "Improves performance when X" |
| "Furthermore, moreover, subsequently" | "Here's why, but wait, next" |
| "Very important, extremely critical" | "Important, critical" |
| "It's worth noting that" | [State the fact] |
| "Robust, comprehensive, seamless" | [Use simpler words] |
Tools Available
Scripts
scripts/content_analyzer.py - Quality validation before publishscripts/search_intelligence_mcp.py - Keyword research (optional)
References
references/seo-enforcement-guide.md - Complete SEO enforcement standards (15 parts)references/quick-reference-card.md - One-page cheat sheet for all 6 modesreferences/ai-disclosure-templates.md - 10 disclosure variations to rotatereferences/common-mistakes.md - What gets articles rejected/suspendedreferences/medium-distribution-guidelines.md - Boost criteriareferences/industry-content-frameworks.md - Content examples
Examples
examples/practitioner-experiment-reference.md - Annotated Practitioner Experiment articleexamples/personal-essay-reference.md - Annotated Personal Essay articleexamples/weak-vs-strong-examples.md - Before/after for all 6 modes
Checklists & Templates
checklists/evidence-checklist.md - Mode-specific evidence requirementschecklists/specificity-test.md - 4-test self-assessmenttemplates/evidence-extraction-worksheet.md - Fill-in worksheet before writing
REMEMBER
Medium's Core Message
"Medium is a home for human stories and ideas... We're building a system that rewards depth, nuance, and time well spent. A space for thoughtful conversation more than drive-by takes, and substance over packaging."
Your Core Shift
Old: How do I optimize content for Medium's algorithm?
New: What human story do I need to tell?
The algorithm follows the values. Write for the values.
The Ruthless Standard (Adapted Per Mode)
Different modes, different quality criteria. Same ruthless standards.
- Personal Essay: Vulnerable, scene-based, unresolved
- Investigative: Evidence-heavy, thesis defended
- Advocacy: Solutions specific, actors named
- Reflective Analysis: Personal lens, open questions
- Practitioner Experiment: Process visible, balanced
- Technical: Production code, benchmarks, tradeoffs
Every article should pass its mode-specific quality gate before publication.
Final Note
The goal isn't to avoid suspension. The goal is to write things worth reading.
If you focus on gaming metrics, you'll eventually get caught—and you'll burn out in the process.
If you focus on developing your voice and telling human stories, you'll build something sustainable—and the external opportunities will follow.
Write like a human. Tell stories worth reading. Use production-grade code when teaching. The rest takes care of itself.
