Content craft

Content Craft — Writing Production Workflow

Contract

This skill guarantees:

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

[date] [article-title] | framework: [A/B/C/D/E] | ICP: [role] | verdict: DRAFT_COMPLETE

---

Inputs

Required before proceeding

Input	Notes
Author's raw material	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

Feature translation

• Every key capability translated: capability → mechanism → workflow → outcome
• No capability introduced naked (named without use-case translation)

Proof chain

• All proof attributed to named company + named role + specific metric
• No anonymous customer references ("a large enterprise")
• Product version specified where behavior is version-dependent

Thought-leadership guardrails (Framework E only)

• One memorable frame per piece — not a symmetrical bullet list
• Product appears as evidence of the thesis, not as a feature announcement
• Ends on a strategic question or sharpened worldview, not a CTA

---

Anti-patterns

Anti-pattern	Why it fails	Fix
Inventing engineering facts	Destroys trust with the exact audience you're targeting; engineers will catch it	BLOCK and return to author for real material
Blending two frameworks	Reader loses the thread; the piece feels unfocused	Pick the dominant framework; relegate secondary elements to a sidebar or future piece
Generic pain framing	"Teams struggle with scaling" triggers nothing; reader doesn't recognize their own situation	Coin a specific term the reader would use in their own internal conversations
Bare metrics	"45ms latency" tells the reader nothing they can act on or compare	Always include: what was tested, how, why the number matters
Strawmanning alternatives	Engineers who evaluated the same options will catch it; destroys credibility for the whole piece	Give each alternative its strongest case before naming the limitation
Wrong turns absent	Reads as marketing, not engineering; reader cannot assess credibility	Include at least one failure, its symptom, and what it taught
Feature list without translation	Capability names mean nothing without the workflow they unlock	Always: capability → mechanism → specific workflow → measurable outcome
Forcing framework on short surface	A 300-word LinkedIn post with five H2 headings is not a framework — it's noise	Respect the surface. Under 600 words: practitioner voice only.
"Excited to announce" openers	Hollow enthusiasm; reader leaves immediately	Start with the news, the constraint, or the metric — not the emotion

---

Validation criteria

Before handing draft to pmm/content-review:

• All Pass 1 brief confirmation fields populated
• Draft reaches within 15% of target word count for the selected framework
• Editorial checklist completed; all items checked or explicitly noted as N/A with reason
• No banned hype patterns in author's voice (third-party quotes are exempt)
• At least one wrong turn visible in the draft
• Story closes with a specific production/scale metric or strategic question (depending on framework)

---

References & Sources

Tier 2 (operator templates — adapted, not authoritative):

• b2b-practitioner-voice (growth-skills v1.0, score 9/10): practitioner voice standard, five story arcs, context-before-code rule, show-the-struggle, metrics-with-methodology, advanced storytelling patterns (problem naming, multi-layer pain architecture, reframing move, feature-to-use-case translation, scale proof as closer, trusted-source proof chain)
• dev-infra-community-story (growth-skills v1.0, score 9/10): framework A/B/C structures, word targets, pre-submit checklist, terminology precision requirements, fair comparison arc rules

Cross-references (this repo):

• pmm/DOMAIN.md — canonical practitioner voice standard, five story arcs, metrics-with-methodology; do not duplicate; defer here
• pmm/voice-print/SKILL.md — produces the VOICE-PRINT.md this skill should write toward (run it first when a voice profile is wanted)
• pmm/ai-slop-audit/SKILL.md — de-slop pass on the draft this skill produces, before content-review
• pmm/content-review/SKILL.md — downstream quality gate; all drafts from this skill feed content-review before publication
• growth/newsletter-growth/SKILL.md — owns the newsletter as a growth loop (this skill drafts the long-form; newsletter-growth decides the loop)
• growth/short-form-social/SKILL.md — owns LinkedIn/X short-form (this skill is long-form; don't force a framework onto a post)
• growth/DOMAIN.md — CLG community content types and developer story frameworks (for community-facing pieces)