Writing production workflow for technical B2B and developer-community content pieces. Invoke when an author needs to produce a migration story, technical deep dive, architectural decision piece, how-to guide, or thought-leadership article from scratch. This skill selects the right story framework, produces the draft structure, and runs a pre-publish editorial checklist. It does not review completed content — use `pmm/content-review/SKILL.md` for that gate. Appropriate for any technical B2B product; no brand-specific knowledge required.
Writing production workflow for technical B2B and developer-community content pieces. Invoke when an author needs to produce a migration story, technical deep dive, architectural decision piece, how-to guide, or thought-leadership article from scratch. This skill selects the right story framework, produces the draft structure, and runs a pre-publish editorial checklist. It does not review completed content — use `pmm/content-review/SKILL.md` for that gate. Appropriate for any technical B2B product; no brand-specific knowledge required.
triggers
["/content-craft","/write-article","user wants to draft a technical article or blog post","user says \"help me write a story about\"","user says \"I built X, help me write it up\"","user says \"we migrated from X, help me tell that story\""]
Framework selection is driven by the author's story type, not forced on an ill-fitting piece
Every draft produced follows the practitioner voice standard in pmm/DOMAIN.md
Editorial checklist runs before the draft is handed to content-review
Anti-patterns are flagged before the draft leaves this workflow
Output is a structurally complete draft with all required sections populated, not a bullet outline
Brain reads / writes
Before starting, if a companion aether-growth-brain repo is connected:
Read knowledge/icp-map.md — confirm the intended audience aligns with a validated ICP card; flag if the intended audience does not match any ICP in the map
Read playbooks/messaging.md — if approved positioning exists, the article's framing must not contradict it; bring any approved category terms into the draft deliberately
On completion, write a one-line log entry to decisions/content-craft-log.md:
Notes, bullet points, or a rough draft. This skill does not invent engineering facts. If raw material is missing, return NEEDS_CONTEXT.
ICP definition
Role, seniority, primary pain category. "Technical audience" is not enough — specify (e.g. "backend engineers at mid-market SaaS, migration pain").
At least one real constraint
A specific bottleneck, error message, metric, or decision that drove the story. Vague setups produce vague stories.
Product truth doc or approved terminology
Official names, banned aliases, component names. This skill does not invent naming.
Optional but improves output
Input
Effect
Destination platform
Adjusts length target and CTA approach (blog, HN, LinkedIn, community forum)
Competitor context
Enables a fair comparison arc in Framework A or C
Published examples from the same program
Calibrates terminology precision and voice
BLOCK rule
If raw material (author's actual engineering experience) is missing:
BLOCK. Return:
"This skill does not invent engineering facts. Please provide:
- What you built, migrated, or decided (and why)
- At least one real constraint, error, or metric from your experience
- What you tried that didn't work
I can then help shape and write."
Decision logic — framework selection
Do not blend two frameworks in one piece. Select the dominant framework based on the author's story.
Framework selection criteria
If the author says…
Select
"We moved from X to Y" / "We migrated from…"
Framework A — Migration story
"I built X using [product/technology]" / "Here's how we implemented…"
Framework B — Technical deep dive
"We chose X over Y and Z" / "Here's why we picked…"
Framework C — Architectural decision
"Here's how to do X" / "Step-by-step guide for…"
Framework D — How-to guide
"The industry is wrong about X" / "Here's a new way to think about…"
Framework E — Category narrative
When the story could fit multiple frameworks: ask the author which element they most want readers to remember. The memorable takeaway determines the framework.
Do not force a framework on a short piece. Under 600 words: use practitioner voice mechanics only (no framework structure required). Respect the surface.
Framework structures
Framework A — Migration story
Target: 1,800–2,500 words
Section
Focus
Target words
The Pain
Name the problem with a specific term the reader recognizes instantly as their own. Structure pain across at least 2 of 3 dimensions: operational inconvenience + engineering/performance risk + compliance/cost risk. Anchor with exact errors, failure times, SLA misses.
300–400
The Dead Ends
Fair comparison arc: 2–3 alternatives, each given their strongest case first. Format per alternative: what it does well → where it specifically failed for your workload → why that was disqualifying. Never strawman. Engineers who evaluated the same options will catch it.
200–300
Why This Solution
The reframing move: "Instead of [old mental model], we started thinking of [new frame]." Then map specific capabilities to the named constraints from The Pain — feature → mechanism → specific workflow → outcome. Not a feature list.
300–400
The Work
Migration strategy, code, config, unexpected challenges. Show the struggle: what you tried first and why it failed, what you learned, how that led forward.
600–900
The Outcome
Measured results with full methodology context. What you gave up. What you would do differently. Close with one specific, understated production metric delivered matter-of-factly.
300–400
Framework B — Technical deep dive
Target: 1,500–2,200 words
Section
Focus
Target words
The Goal
What is being built and why it is technically interesting. Name the constraint or capability gap that made this worth building.
200–300
The Stack
Technology choices and the reasoning behind them. Constraints drove these choices — name them.
150–200
The Architecture
System design with the key decision points. For complex systems, include a diagram placeholder.
300–400
The Implementation
Step-by-step code walkthrough. Every code block wrapped with context-before-code rule (see pmm/DOMAIN.md). Show at least one wrong turn or unexpected challenge.
700–1,000
The Result
Demo link, repo, benchmark, lessons, next steps. Close with one specific production or scale signal.
200–300
Framework C — Architectural decision
Target: 1,200–1,800 words
Section
Focus
Target words
The Scenario
Requirements with specific numbers: throughput, dataset size, latency target, consistency model. Name the constraint that made "keep the current setup" no longer viable.
250–350
The Options
Fair comparison arc: 2–3 alternatives. Per option: what it does well → specific limitation for this workload → disqualifier. Give each alternative its strongest case before naming why it didn't fit.
500–700
The Evaluation
How you tested (tools, methodology, dataset). Specific metrics from the POC. Include at least one structural contrast if relevant: "X was designed for [old assumption] — our workload no longer fits that assumption because [why]."
300–400
The Verdict
Technical justification. Explicitly name what you are giving up.
200–300
Framework D — How-to guide
Target: 800–1,500 words
Section
Focus
Target words
The Goal
What the reader will be able to do after following this guide. Name the specific outcome.
100–150
Prerequisites
Exact requirements (versions, access, prior steps). Do not skip these — missing prerequisites are the primary cause of tutorial failure.
100–150
Steps
Numbered steps. Every step has a clear action verb. Every code block wrapped with context-before-code rule. Include at least one "gotcha" or common failure point per major step.
500–900
Validation
How to confirm it worked. Specific output or state to verify.
100–150
Next step
One concrete next action or resource — not a list of five things.
50–100
Framework E — Category narrative (thought leadership)
Target: 1,000–1,800 words
Section
Focus
Target words
The Market Shift
Name the structural change making the old approach inadequate. One specific, observable signal — not generic "the world is changing."
200–300
The Broken Assumption
The assumption the old approach was built on — now violated. State it precisely.
200–300
The New Model
"Instead of X, think of Y." The reframing move. One memorable frame — not a list of five improvements.
300–400
The Structural Implication
What changes in how people work, build, or buy as a result of the new model. Product appears here as evidence, not feature list.
200–300
The Hard Question
End on a question or sharpened worldview — not a CTA. The question should be one the reader cannot dismiss.
100–150
Editorial mechanics (apply to all frameworks)
These mechanics are defined in full in pmm/DOMAIN.md. Summary for reference during drafting:
Mechanic
Rule
Context-before-code
2–3 sentences before every code block (what/why/how). 1–2 sentences after (what to notice/result). Never place a code block immediately after a section header.
Show the struggle
At least one wrong turn per major decision: what you tried, why it failed, what you learned. A piece with no wrong turns reads as marketing.
Metrics-with-methodology
Never bare numbers. Always state: what was tested, how it was tested, why the number matters.
Problem naming
Coin a specific term the reader recognizes as their own pain. Not generic framing — a name they would use in a 2 AM Slack message.
Reframing move
At the turn from problem to solution: "Instead of X, think of Y." One sentence. Acknowledges the reader's current model; makes the solution feel inevitable.
Feature-to-use-case translation
Never introduce a capability without immediately translating it: capability → one-sentence mechanism → specific workflow → measurable outcome.
Scale proof as closer
Close technical stories with one specific, understated production metric. Specific beats approximate. Understated beats promoted.
Trusted-source proof chain
All proof attributed to named company + named role + specific metric. "A large enterprise customer" = noise.
Output format
Produce in three passes:
Pass 1 — Brief confirmation (before drafting)
## Content Craft — Brief Confirmation
**Framework selected:** [A / B / C / D / E] — [name]
**Reason:** [one sentence on why this fits the author's story]
**ICP:** [role, seniority, pain]
**Platform target:** [if provided]
**Target word count:** [range]
**Named problem:** [the specific term that will anchor the piece]
**Key constraint to anchor:** [the specific bottleneck, error, or metric]
**Wrong turn to include:** [what failed first]
**Closer metric:** [the production/scale signal for the ending]
Proceed to draft? [yes / no / adjustments needed]
Pass 2 — Structured draft
Full draft with all framework sections populated according to the selected framework structure. All code blocks wrapped with context-before-code. All metrics with methodology. At least one wrong turn visible.
Pass 3 — Editorial checklist
Run this checklist on the completed draft before handing to content-review:
Story arc and structure
One framework selected; not blended with another
Problem named with a specific term (not generic pain framing)
Pain covers at least 2 of 3 dimensions (operational / engineering-performance / compliance-cost) — for Framework A and C
Wrong turns visible: what was tried first and why it failed
Reframing move present ("Instead of X, think of Y") — for Framework A, C, E
Story closes with one specific, understated production metric or scale signal
Voice and mechanics
Every code block has 2–3 sentences before it (what/why/how)
Every code block has 1–2 sentences after it (what to notice/result)
All metrics include: what was tested, how, why it matters
No banned hype patterns (see pmm/content-review/SKILL.md banned list)
Tone is peer-to-peer, not marketing
Comparison content (Frameworks A, C only)
Each alternative receives its strongest case before limitations are stated
Limitations are specific to the author's workload, not generic category criticisms
No alternative described in a way the vendor would publicly dispute
