| name | blog-experiential |
| description | Write experiential articles for marvinzhang.dev following 3-stage workflow (Outline → Writing → Refine). Use for personal insights, lessons learned, project retrospectives, and reflective pieces. Produces narrative-driven bilingual content with honest, practical takeaways. Requires blog-common skill. |
| metadata | {"author":"marvinzhang","version":"1.0","workflow":"3-stage","style":"experiential"} |
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:
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:
[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:
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:
References
