writing-tech-post

What this skill does

# Writing Engineering Posts

SOTA authoring loop for technical blog posts. The philosophy is **archetype-first** (pick the genre), **depth-second** (commit the abstraction ladder), **evidence-third** (every claim attaches to an artifact), **voice & disclosure fourth** (publisher register + ethics), **momentum last** (narrative spine, lede, closer). Inline content in this SKILL.md is a dispatcher; the contract lives in `references/`.

## Required Reading Router

Match the post's archetype (or the active phase) to the row. Read the listed files **in full before** producing the corresponding output. Inline content in this SKILL.md is a pointer, not a substitute.

| Task / Archetype                                                | MUST read                                                                                              |
| --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| Selecting an archetype (Phase 1, every post)                    | `references/archetypes-and-structure.md`                                                               |
| Planning depth / abstraction ladder (Phase 2, every post)       | `references/depth-and-abstraction.md`                                                                  |
| Writing an incident postmortem                                  | `references/postmortems.md` + `references/voice-and-disclosure.md`                                     |
| Writing an architecture migration narrative                     | `references/migrations.md` + `references/depth-and-abstraction.md`                                     |
| Writing a performance deep-dive                                 | `references/performance-deep-dive.md` + `references/evidence-diagrams-code.md`                         |
| Writing an AI/agent system post                                 | `references/ai-and-agents.md` + `references/evidence-diagrams-code.md`                                 |
| Writing a security or reliability post                          | `references/security-and-reliability.md` + `references/voice-and-disclosure.md`                        |
| Writing a tutorial or research-to-product translation           | `references/archetypes-and-structure.md` + `references/depth-and-abstraction.md`                       |
| Placing diagrams, charts, code, tables, ablations (Phase 3)     | `references/evidence-diagrams-code.md`                                                                 |
| Tuning to a publisher house voice (Phase 4)                     | `references/voice-and-disclosure.md` + `references/publisher-voice-matrix.md`                          |
| Tightening lede, headlines, transitions, closer (Phase 5)       | `references/narrative-and-pacing.md`                                                                   |
| Pre-publish gate (Phase 6)                                      | `references/pre-publish-checklist.md` + `references/anti-patterns.md`                                  |

## Reference Index

- `references/archetypes-and-structure.md` — Eight canonical archetypes (launch deep-dive, postmortem, migration, performance, tutorial, research-to-product translation, AI/agent, security/reliability) with their 9-column contract (opening / sequence / closing / length / byline / evidence / voice / hybrid partner / silent failure mode) plus the 9-question decision tree and hybrid-disclosure rules.
- `references/depth-and-abstraction.md` — Five-rung abstraction ladder (R1 user → R5 measurement) with three traversal patterns (staircase, yo-yo, spiral), the rung-whiplash diagnostic, the anchor-N rule, and per-archetype default depth profiles.
- `references/postmortems.md` — Canonical postmortem section sequence (Summary → Background → Incident → Timeline → Contributing factors → Mitigation → Action items), blameless register three rules, UTC-timeline + named-artifact obligations, failed-mitigation requirement.
- `references/migrations.md` — Five migration sub-types (rewrite, decomposition, stack replacement, pipeline replacement, component modernization, dual-stack, maturity-level), seven-panel canonical structure, empathetic strategic voice, "what we'd do differently" honesty, dated-status-snapshot closing.
- `references/performance-deep-dive.md` — Detective-arc structure (hypothesis → measurement → reveal → next bottleneck), distribution-shift evidence contract (percentile + sample size + window + environment), iterative bottleneck-peeling, partial-victory disclosure between fixes.
- `references/ai-and-agents.md` — Paper-link-first attribution, named-benchmark + ablation evidence contract, named-checker idiom (debugging-agent + leakage-checker + usage-checker), "AI handles the long tail" closing motif and its slop variant (bolted-on AI-future paragraphs).
- `references/security-and-reliability.md` — Threat-model opening, layered-defense walkthrough, coordinated-disclosure four-panel (threat-model → background → defense → mitigations), probabilistic register for adversary capabilities, CVE + upstream-commit citation contract.
- `references/evidence-diagrams-code.md` — Twelve-form evidence taxonomy (architecture diagram, sequence/flow, timeline, dashboard, distribution chart, flamegraph/profile, trace view, results table, code listing, config/manifest, ablation matrix, benchmark plot), captioning conventions (caption states the finding), `claim → artifact → reading` cadence rule, code-length thresholds (1–15 / 16–30 / >30).
- `references/voice-and-disclosure.md` — Blameless register, coordinated-disclosure four-panel, paper-link-first attribution, "what we'd do differently" honesty pattern, vendor-naming conventions, charity toward predecessor systems, disclaimer-paragraph genre signal.
- `references/narrative-and-pacing.md` — Five-lede taxonomy (result-first / mystery / stakes-first / 3-W summary / paper-link-first / shipping-status), H2-as-question-resolution discipline, story-shape catalogue (detective / migration / blameless / paper-link-first / tutorial arcs), closer multiple-choice gate, first-200 + last-200 callback-coupling test.
- `references/publisher-voice-matrix.md` — Cross-publisher matrix (Datadog, Vercel, GitHub, AWS, Meta, Cloudflare, Jane Street) by six surface features (byline weight, sentence length, vendor density, evidence reflex, opening register, closing register), plus banned moves per publisher.
- `references/anti-patterns.md` — Banned moves catalogue: buried lede, rung whiplash, evidence-free percent claims, blame-by-implication, code-without-context, depth-without-product-framing, paper-name-dropping, false-precision metrics, hedged ledes, exciting-announcement templates, coordinated-disclosure violations, AI-eval-as-anecdote, archetype-bait headlines, framework-without-instance, bolted-on AI-future close.
- `references/pre-publish-checklist.md` — Archetype-conditional checklist (postmortem-only / migration-only / performance-only / AI-only / security-only rows), disclosure-blocker list, lint-thresholds, publishable / hold-for-review / rework rubric.

## Bundled Path Rule

Resolve every bundled helper relative to the directory containing this `SKILL.md`. When the command below appears as `scripts/<name>`, treat the actual invocation as `<writing-tech-post-dir>/scripts/<name>` — expand `<writing-tech-post-dir>` to the absolute skill directory before running. Likewise expand `assets/<name>` and `references/<name>` to the bundled paths under the skill directory.

## Operating Loop (6 Phases)

Each phase ends in a STOP directive. The inline content in each phase is a gist tripwire — enough to detect violations during scanning — not the contract. The reference file holds the contract.

### Phase 1 — Archetype Selection & Audience Framing

1. Identify the artifact's purpose against the eight archetypes (launch deep-dive, incident postmortem, architecture migration, performance ca