tech-writing

AI-consumed reference. Optimized for Claude to read during execution.

Technical Writing

Produce documents a reviewer can act on and argue with — not filled-in templates.

Evidence policy for this skill itself. Almost everything below is CONVENTION with an authoritative primary source, NOT measured efficacy. No study shows these structures produce better outcomes. The three places carrying real measurement are marked [MEASURED]. Never present convention as research-backed — that is the first thing this skill exists to stop.

Step 0 — Refuse to write blind

Run rules/core/prompt-validation.md (6-dimension gate) BEFORE writing. Below threshold → ask the 1–2 weakest dimensions, do not guess. A doc written from guesses is worse than no doc: it looks authoritative and is wrong.

Then answer three questions in the output header, so the reader sees the frame:

frame[3]{question,why}:
  Who reads this and what decision do they make with it?,"No audience ⇒ no way to judge detail level"
  What is ALREADY true (code/system) vs PROPOSED?,"The #1 source of misleading specs"
  What would make this document WRONG?,"If nothing could, it is asserting nothing"

Step 1 — Pick the tier. Default DOWN.

Tier follows agent-detector complexity. Do not scale formality with the effort you spent.

tiers[4]{tier,complexity,doc,gate}:
  T0,Quick,"Y-statement (1 sentence) or a PR-description paragraph","Reversible? cheap to undo? stop here"
  T1,Standard,"Nygard ADR (5 sections) OR a one-page spec","Long-lived consequence but one obvious option"
  T2,Deep,"MADR + LLD sections that apply","≥2 options genuinely worth comparing"
  T3,Project,"RFC: guide-level + reference-level split","Crosses teams / hard to reverse"

Escalate a tier when ≥2 hold: multiple teams affected · hard to reverse · ≥2 credible options · safety/money/data-loss exposure · the reader will not be in the room to ask you. Never escalate because the topic feels important.