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:

The core problem: You optimized for their algorithm instead of their values.

The New Approach

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

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

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:

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:

Topic → Mode Examples

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

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:

• Would I say this to a colleague? (If no → rewrite)
• Sounds like me or a textbook? (If textbook → add personality)
• Using words I don't normally use? (If yes → simplify)
• Every paragraph sounds the same? (If yes → vary structure)
• Would a reader know this is human? (If unsure → add vulnerability)

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

SubscriberValidator

SegmentBuilder

CampaignDispatcher

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:

1. What specific thing happened? (Not category—instance)
2. When exactly? (Day, date, time of day)
3. What did you see/hear/do? (Sensory details, actions taken)
4. What was the actual output/result? (Can you copy-paste it?)
5. What went wrong at least once? (Failures build credibility)
6. What numbers can you attach? (Time, count, percentage, before/after)

Mode-Specific Evidence Prompts

For Practitioner Experiment Mode:

1. What specific thing were you trying to build/fix/improve?
2. Walk through ONE session step-by-step: What did you ask? What happened? What did you do next?
3. What exact output did the tool produce? (Copy/paste if possible)
4. What went WRONG? Describe one specific failure.
5. What numbers can you attach? (Time saved, errors caught, files changed, attempts needed)
6. What day/time did key moments happen?
7. What are you still calibrating? (With specific observations, not just questions)

For Personal Essay Mode:

1. Describe the physical setting of the key moment. What did you see/hear/feel?
2. What exact words were said? Recreate dialogue.
3. What were you wearing? Where were you sitting/standing?
4. What did you think in that exact moment? (Not what you think now—what you thought then)
5. What uncertainty or confusion did you feel? (Not looking back—in the moment)

For Investigative Mode:

1. What's your thesis in one sentence?
2. List 10+ sources with author names and publication dates.
3. What does the opposition actually say? (Direct quotes, not paraphrase)
4. What's your credential or qualification to analyze this?
5. What's the strongest counterargument, and how do you address it?

For Advocacy Mode:

1. Name the specific system, policy, or organization you're criticizing.
2. Document one specific harm with names, dates, and outcomes.
3. What's been tried before? Why did it fail?
4. List your recommendations with WHO should do WHAT by WHEN.
5. What's your personal stake in this issue?

For Reflective Analysis Mode:

1. What specific memory grounds your analysis? (Year, context, sensory details)
2. What artifact could you reference? (Screenshot, email, saved file)
3. What pattern are you noticing? Give three specific instances.
4. What's your professional or personal lens on this?
5. What are you uncertain about? (Honest admission)

For Technical Mode:

1. What real project is this from? Name it and describe the context.
2. What was the actual error message or problem? (Copy-paste)
3. Show the actual code—before and after.
4. What didn't work the first time?
5. What would you do differently now?
6. 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

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:

• AI disclosure in first two paragraphs (if AI assisted)
• Structure differs from recent articles
• External links are genuinely useful (not traffic-driving)
• Not publishing too frequently (<2 articles in 24 hours)

Voice:

• Sounds human (varied sentence length, personality)
• 2-3 vulnerability markers present
• No AI-marker words (leverage, utilize, facilitate, robust, comprehensive, seamless)
• Natural transitions (not "Furthermore," "Moreover")

Value:

• Unique contribution (not just restating common knowledge)
• Would I read this if someone else wrote it?
• Did I take at least one risk?

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:

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 research

• analyze_search_intent_tool()

  - Intent classification

• query_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

• AI assistance disclosed in first two paragraphs
• No template reuse (structure differs from recent articles)
• External links are genuinely useful (not traffic-driving)
• Not publishing too frequently (<2 articles in 24 hours)

Evidence Depth (NEW in v3.1)

• At least ONE specific example shown in full detail (not summarized)
• Specific dates/days mentioned (not "recently" or "this week")
• Actual output/code/response included (not just described)
• At least ONE failure or limitation with specifics
• Numbers/metrics where applicable (not "improved" but "improved by X")
• Mode-specific evidence requirements met (see Section 2)

Specificity Test (NEW in v3.1)

• Swap Test passed: Could NOT swap in different examples—these are MY specific details
• "Like what?" answered: Every claim has a concrete instance backing it
• Timestamps present: Specific days/times anchor the narrative
• Artifacts included: Where possible, actual output/code/screenshots shown

Quality (Mode-Specific)

• Passes mode-specific quality gate (Section 5)
• Includes vulnerability/uncertainty moments
• Has nuanced conclusion (not hot take)
• Sounds like me, not like content

Practical

• Title is honest (not clickbait)
• Would I be proud to share this?
• Did I take at least one risk?
• Content analyzer run (scripts/content_analyzer.py)
• Evidence extraction worksheet completed (templates/evidence-extraction-worksheet.md)

SEO Enforcement Standards (MANDATORY)

Complete SEO standards are in

references/seo-enforcement-guide.md

Articles failing ANY standard get REJECTED.

Quick Reference: SEO Requirements

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 ☐

For Complete Standards

See

references/seo-enforcement-guide.md

• 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

# Define tools with proper error handling
@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)}"

# Initialize with production settings
llm = ChatOpenAI(
    model="gpt-4o",  # Current flagship (Nov 2025)
    temperature=0.0,  # Deterministic for production
    request_timeout=30.0,  # Prevent hanging
    max_retries=2  # Handle transient failures
)

agent = create_openai_tools_agent(llm, tools=[search_codebase], prompt=prompt)

# AgentExecutor with safety limits
agent_executor = AgentExecutor(
    agent=agent,
    tools=tools,
    max_iterations=5,  # Prevent infinite tool-calling loops
    max_execution_time=60,  # Hard timeout (seconds)
    return_intermediate_steps=True,  # For debugging
    handle_parsing_errors=True  # Graceful degradation on malformed LLM output
)

# Usage
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> {

  // 1. Vector search with timeout
  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')
  ]);

  // 2. Filter by confidence threshold
  const relevantDocs = searchResults.matches
    .filter(match => match.score >= options.minConfidence)
    .map(match => match.metadata.text);

  // 3. Handle no results case
  if (relevantDocs.length === 0) {
    return {
      answer: "No relevant information found in knowledge base.",
      sources: [],
      confidence: 0
    };
  }

  // 4. Generate answer with Claude
  const anthropic = new Anthropic();
  const response = await anthropic.messages.create({
    model: 'claude-3-5-sonnet-20241022',  // Current flagship
    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))
  };
}

// Helper: Timeout wrapper
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 search

• minConfidence

  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  # tokens
    ) -> 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.
        """

        # 1. Compress to essential fields only
        essential_context = {
            'task_id': context['task_id'],
            'current_state': context['state'],
            'last_action': context['actions'][-1],  # Only most recent
            'error_count': len([a for a in context['actions'] if a['status'] == 'error'])
        }

        # 2. Verify size constraint
        context_str = str(essential_context)
        if len(context_str) > max_context_size:
            # Drop least critical information
            essential_context.pop('last_action', None)

        # 3. Async handoff (non-blocking)
        await self.notify_agent(to_agent, essential_context)

        return essential_context

# Production Metrics (from 10M+ handoffs):
# - Latency: P50=50ms, P95=120ms, P99=250ms
# - Context retention: ~70% (acceptable for most workflows)
# - Throughput: 10K handoffs/sec on single instance
# - Error rate: 0.02% (mostly timeout-related)

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",  # No network access
            read_only=True,  # No filesystem writes
            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 requests

• read_only=True

  : Prevents writing malicious files to filesystem

• mem_limit

  +

  nano_cpus

  : Prevents resource exhaustion attacks

• timeout

  : Kills container if code runs too long

• security_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

Voice Quick Fixes

Compliance Quick Check

Before every publish:

1. AI disclosure in first two paragraphs? ✓
2. Structure different from last article? ✓
3. External links genuinely useful (not just traffic)? ✓
4. Not second article today? ✓
5. Not forcing a template? ✓

Content Type vs. Mode Mapping

Quality Gate Quick Reference

AI Patterns to Avoid

Tools Available

Scripts

• scripts/content_analyzer.py

  - Quality validation before publish

• scripts/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 modes

• references/ai-disclosure-templates.md

  - 10 disclosure variations to rotate

• references/common-mistakes.md

  - What gets articles rejected/suspended

• references/medium-distribution-guidelines.md

  - Boost criteria

• references/industry-content-frameworks.md

  - Content examples

Examples

• examples/practitioner-experiment-reference.md

  - Annotated Practitioner Experiment article

• examples/personal-essay-reference.md

  - Annotated Personal Essay article

• examples/weak-vs-strong-examples.md

  - Before/after for all 6 modes

Checklists & Templates

• checklists/evidence-checklist.md

  - Mode-specific evidence requirements

• checklists/specificity-test.md

  - 4-test self-assessment

• templates/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.