diegosouzapw 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:
- Story structure: Context → Challenge → Approach → Outcome → Lessons
- Key moments: Pivotal decisions, turning points, realizations
- Lesson extraction: Actionable insights from experience
- 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(withunlisted: 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:
- Story review: Ensure narrative cohesion and flow
- Lesson validation: Ensure insights are clear and actionable
- Tone check: Balance humility with authority
- Chinese translation: Apply 形不同而意同 principle
- 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(removeunlisted: 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