Blog Writing: Experiential Style

Write personal, reflective articles that share lessons learned and practical insights from real experiences.

Prerequisites

Load blog-common skill for formatting, localization, quality standards, and writing principles.

When to Use

• •Lessons learned from projects or experiences
• •Personal insights and reflections
• •Project retrospectives and case studies
• •Career reflections and growth stories
• •Problem-solving journeys

Example topics: "What I Learned from 5 Years in Open Source", "Building Crawlab: A Technical Retrospective", "My Journey from Vibe Coding to SDD"

Questionnaire-First Workflow

Start every experiential article with the questionnaire to gather structured input:

lean-spec create "article-slug" --template=experiential

This creates a spec with embedded questionnaire covering:

• •Context (project, timeline, role, scale)
• •The challenge and what made it difficult
• •Your approach and pivots
• •Lessons learned (3-5 key takeaways)
• •Advice for others

Fill out the questionnaire, then tell AI "questionnaire complete". This helps capture the full story before writing begins.

[See questionnaire guide in references/questionnaire.md]

Workflow: 3-Stage Process

Stage 1: Outline (1 interaction)

Objective: Create narrative arc and identify key lessons

Activities:

1. •Story structure: Context → Challenge → Approach → Outcome → Lessons
2. •Key moments: Pivotal decisions, turning points, realizations
3. •Lesson extraction: Actionable insights from experience
4. •Tone setting: Balance humility and authority

Structure Template:

## Introduction (300-500 words)
- Hook: Compelling moment or question
- Context: What you were trying to do
- Why it matters: Relevance to readers
- Roadmap: Journey preview

## The Context (400-600 words)
- Situation and background
- Initial approach/assumptions
- What you expected to happen

## The Challenge (500-700 words)
- What went wrong or surprised you
- Key turning points
- Decisions made and why

## The Approach (500-700 words)
- How you tackled it
- What worked and what didn't
- Iterations and adaptations

## The Outcome (400-600 words)
- Final result
- Unexpected learnings
- What you'd do differently

## Lessons & Takeaways (400-600 words)
- 3-5 concrete lessons
- Actionable advice for readers
- Broader implications

Deliverables:

• •Complete specs/{spec-number}-{slug}/outline.md
• •Narrative arc defined
• •Key lessons identified
• •Honest tone established

Quality Gates:

• • Clear narrative arc (context → challenge → resolution)
• • Specific stories, not vague generalities
• • Lessons are actionable and concrete
• • Tone is humble and honest

Stage 2: Writing (3-5 interactions)

Objective: Create engaging narrative with practical insights

Approach: Write ONE section per interaction directly to final files:

• •English: blog/YYYY-MM-DD-slug.mdx (with unlisted: true)
• •Track progress in spec folder

Section Standards:

• •Specific stories: Real examples with details, not abstractions
• •Honest reflection: Include failures and mistakes
• •Visual elements: Use diagrams for process, tables for comparisons
• •Actionable lessons: Readers can apply to their own situations
• •Balance: Technical depth + personal reflection

Section Completion Checklist:

• • Specific examples with details
• • Honest about challenges and failures
• • Visual element where helpful (diagram/table)
• • Lessons clearly articulated
• • Actionable takeaways
• • Natural story flow

[See complete writing guidelines in blog-common/SKILL.md]

Stage 3: Refine (1 interaction)

Objective: Polish narrative and finalize

Activities:

1. •Story review: Ensure narrative cohesion and flow
2. •Lesson validation: Ensure insights are clear and actionable
3. •Tone check: Balance humility with authority
4. •Chinese translation: Apply 形不同而意同 principle
5. •Final validation: Build, format, links

Quality Assessment:

• • Narrative flows naturally
• • Lessons are concrete and actionable
• • Honest about failures/mistakes
• • Balance of story and technical depth
• • Tone is humble but authoritative
• • Chinese reads naturally
• • Build succeeds: pnpm run build

Publication Files:

• •English: blog/YYYY-MM-DD-slug.mdx (remove unlisted: true)
• •Chinese: i18n/zh/docusaurus-plugin-content-blog/YYYY-MM-DD-slug.mdx

Experiential-Specific Principles

Specificity Over Generality

Share concrete stories, not platitudes:

❌ "Communication is important in teams"
✅ "When our team missed a critical deadline because I assumed others understood 
   the database migration requirements, I learned to over-communicate technical 
   dependencies"

Honesty and Vulnerability

Share failures and mistakes openly:

• •What went wrong and why
• •What you misunderstood or overlooked
• •How you recovered or adapted
• •What you'd do differently

Actionable Lessons

Extract practical insights readers can apply:

❌ "Be more careful with technical debt"
✅ "Set a 'debt ceiling': if fixing takes >2 hours, create a spec and schedule it. 
    We reduced emergency fixes by 60% after implementing this rule."

Balance Technical and Personal

Weave technical depth with personal reflection:

• •Technical challenges and solutions
• •Personal growth and realizations
• •Team dynamics and collaboration
• •Industry patterns and trends

Quality Gates (Experiential-Specific)

Beyond blog-common standards:

• • Specific stories with details, not vague generalities
• • Lessons clearly articulated and actionable
• • Honest about failures and mistakes
• • Balance of narrative and technical content
• • Takeaways applicable to readers
• • Natural story flow throughout
• • Humility and authenticity in tone

References

• •blog-common/SKILL.md - Formatting, localization, quality, style
• •references/questionnaire.md - Questionnaire guide
• •LeanSpec template - Full spec template with questionnaire