Writing and Documentation
researched 2026-05-25· 9 sources · 12 concepts · skill writing-expert
Reference for technical, business, and report writing. Deep treatments of every craft concept live in references/advanced-craft.md and the per-topic files in the Sub-skill routing table below. Load th
Writing Expert
- Reference for technical, business, and report writing. Deep treatments of every craft concept live in references/advanced-craft.md and the per-topic files in the Sub-skill routing table below. Load the matching reference when the user needs depth beyond the core rules in this skill. [source]
- Output is correct when: the delivered document (a) opens with the bottom line if BLUF applies, (b) contains zero Tier 1 terms, (c) matches the audience register in the Tone Calibration table, and (d) addresses the user's stated goal without adding unrequested content. Apply the Tier 1 ban list to your own prose as well as to the user's document. [source]
When to use this skill
- Activate when the user: [source]
- Asks to write, draft, or improve any prose document (report, summary, email, runbook, architecture doc, proposal, meeting minutes) [source]
- Needs help with document structure, tone, or formatting [source]
- Wants a status report, QBR, account review, executive summary, or post-mortem [source]
- Asks about writing frameworks (BLUF, Pyramid Principle, SCQA, STAR, Minto) [source]
- Wants to eliminate AI-sounding prose or improve human voice [source]
- Needs to calibrate tone for different audiences (executive vs developer vs customer) [source]
- Asks about data storytelling or dashboard-to-prose conversion [source]
- Wants markdown formatting guidance (headings, tables, lists, code blocks) [source]
- Has an ambiguous "make this better" request - triage by asking: audience, document type, and primary goal (clarity / tone / structure) [source]
When NOT to use this skill
- Route to a sibling hub instead when the user needs: [source]
- Software / product / engineering docs - API docs, runbooks, specs, PRDs, RFCs, design docs, commit messages, PR descriptions, changelogs, error messages, UI microcopy → technical-writing-craft [source]
- Executive / business / persuasion - one-pagers, OKRs, pitch decks, proposals, speeches, public speaking, founder letters, whitepapers, case studies → executive-comms [source]
- Marketing / PR / external comms - sales copy, press releases, crisis PR, newsletters, op-eds, launch narratives, audio scripts, NPS/support replies → content-and-marketing-writing [source]
- Career / academic / legal / formal - resumes, cover letters, job descriptions, performance reviews, academic/citation writing, legal-adjacent prose, policy, surveys → career-and-formal-writing [source]
- AI-voice cleanup of an existing draft → kill-the-ai-ism [source]
- Multi-pass structural/factual document critique (review loop, fact-check, ship-readiness) → writing-expert (references/document-critique.md) [source]
Sub-skill routing table
- This hub consolidates 18 prose-craft sub-skills plus a deep-craft reference as on-demand reference files. When a task matches a row, Read the listed references/<name>.md before deep answers - do not rely on this table alone for depth. [source]
Core Principles
- BLUF (Bottom Line Up Front) - Lead with the conclusion. Put the most important information in the first sentence. Supporting details follow in decreasing importance. [source]
- One idea per paragraph - Each paragraph makes exactly one point. The first sentence states it; the rest support it. [source]
- Active voice by default - "The team deployed the fix" not "The fix was deployed by the team." Passive voice only when the actor is unknown or irrelevant. [source]
- Concrete over abstract - "Latency increased from 50ms to 340ms" not "Performance degraded significantly." [source]
- No AI-isms - Apply the full Tier 1 ban list below. Chatbot tics (certainly, I hope this helps, Let's dive in) are Tier 3 tells - delete on sight. [source]
- Preserve facts - Never substitute, paraphrase, or fabricate numbers, names, dates, or technical claims from the input. If a claim is unclear, flag it rather than rewrite it. [source]
- Confirm before rewriting - Before editing any document over 100 words, ask at most one compound question: "Who is the audience, what's the primary goal (clarity / tone / structure / AI-ism removal), and is there a length target?" - unless all three are already stated. For from-scratch requests (no existing document), ask: topic, audience, and desired length before drafting. [source]
- Self-check before delivery - Scan every output for Tier 1 terms and Tier 3 chatbot tics before responding. Remove any found. Confirm the document opens with the bottom line if BLUF applies. Re-read the output against the user's stated goal to confirm it answers what was asked, not a related-but-different question. [source]
Executive Summary
Incident Post-Mortem
Technical Runbook
- Purpose (one sentence: when to use this) [source]
- Prerequisites (tools, access, permissions) [source]
- Steps (numbered, imperative mood, one action per step) [source]
- Verification (how to confirm each step worked) [source]
- Rollback (how to undo if things go wrong) [source]
- Troubleshooting (common failure modes + fixes) [source]
Status Report
Proposal / Business Case
Meeting Minutes
- Decisions made (numbered) → action items (owner + date) → open questions. Skip discussion recap - only decisions and actions matter. [source]
Unlisted Document Types
- For types not above (RCA letters, press releases, cover letters, change announcements), apply the closest template and note the adaptation: "Using Incident Post-Mortem structure for RCA letter - sections 3–5 map directly." [source]
Tier 2 — Flag in clusters (2+ in one section)
- harness, foster, resonate, ecosystem, journey, empower, unlock, drive (metaphorical), transform, innovative, dynamic, significant [source]
Tier 3 — Structural tells
- Em dashes used as sentence separators in prose (target: ≤1 per 500 words for AI-ism detection; the craft rule for polished human prose is ≤1 per 100 words - see Em-dash discipline in the craft section; structural use in headings and table separators is exempt) [source]
- Uniform paragraph/sentence lengths - vary between 1 and 5 sentences [source]
- Formulaic openings ("In the world of...", "When it comes to...", "In an era of...") [source]
- Hedge-stacking ("could potentially", "may eventually", "might arguably") [source]
- Generic conclusions ("In conclusion, X remains a Y") [source]
- Chatbot tics ("I hope this helps!", "Let me know if...", "Certainly!", "Let's dive in!") [source]
Context tolerance
- Tier 1 replacements are mandatory in all contexts. Tier 2 and Tier 3 strictness varies: [source]
Given/New contract (Williams)
- Every sentence's subject should carry old (given) information; its predicate should carry new information. Violations make text feel jumpy. [source]
- Bad: "Many companies use containers. Containers are the unit that..." [source]
- Good: "Many companies use containers. These containers package..." [source]
- Apply when: text feels choppy or each sentence opens a new topic. [source]
Topic-sentence-first vs buried-lede paragraphs
- A topic sentence at the start signals the point; a buried lede forces the reader to extract it. Default to topic-sentence-first for business and technical writing; buried-lede is acceptable in narrative writing for surprise. [source]
- Bad: 5-sentence paragraph where the actual claim is sentence 5. [source]
- Good: Sentence 1 makes the claim; sentences 2–5 support it. [source]
- Apply when: paragraphs feel like they bury the point. [source]
Verb-first sentences (kill nominalization)
- A nominalization turns a verb into a noun ("perform a calculation", "make a decision"). Replace with the verb form ("calculate", "decide"). [source]
- Bad: "We made the decision to perform an investigation." [source]
- Good: "We decided to investigate." [source]
- Apply when: scanning verbs and finding "perform", "conduct", "make", "do" + noun. [source]
So-what test
- Every paragraph should answer "so what?" - explicitly or implicitly. Read each paragraph and ask "so what?"; if there's no answer, cut. [source]
- Bad: "MongoDB uses a document model. Documents live in collections. Collections live in databases." (three facts, no point) [source]
- Good: "MongoDB's document model stores related data together, eliminating the joins that slow relational queries." [source]
- Apply when: a paragraph feels like throat-clearing or filler. [source]
Concession-counter-claim ("Yes, X. But Y.")
- Acknowledge the opposing view before stating yours. Shows consideration and disarms pushback. [source]
- Bad: "We should use X." (no acknowledgement of objections) [source]
- Good: "Yes, Y has lower latency. But Y costs 3x more, and our SLO is met with X." [source]
- Apply when: writing persuasive prose anticipating disagreement. [source]
Headlines vs subheads
- A headline tells the reader the conclusion; a subhead tells them the topic. Use headlines in business writing (claim-first), subheads in reference docs (topic-first). [source]
- Headline: "Renewal at risk: TechCorp's CSAT dropped 30 points in Q3" [source]
- Subhead: "TechCorp renewal status" [source]
- Apply when: writing scannable content. [source]
Front-matter conventions (TL;DR / abstract / exec summary)
- For full exec-summary structure see ## Document Type Templates → Executive Summary above. [source]
- TL;DR: ~1 paragraph, top of long documents, the conclusion. [source]
- Abstract: ~150–300 words, formal documents, summarizes methods and findings. [source]
- Executive summary: ~1 page, business documents, the decision context + ask. [source]
- Pick one; don't stack all three. [source]
Footnote / endnote / inline-citation styles
- Inline (parenthetical): "(Williams, 1990, p. 50)" - APA-style, common in academic writing. [source]
- Footnotes: numbered superscripts at the bottom of each page - common in legal/journalism. [source]
- Endnotes: numbered superscripts gathered at the end - common in books. [source]
- Markdown link references: [claim][1] with [1]: https://... - common in technical writing. [source]
- Pick one and hold it throughout the document. [source]
Em-dash / en-dash / hyphen discipline
- Hyphen (-): compound modifiers ("data-driven"), prefixes ("non-trivial"). [source]
- En-dash (–): ranges ("pages 5–10"), connections between equals ("New York–London flight"). [source]
- Em-dash (—): parenthetical asides - like this - or to set off a strong break. [source]
- AI-written prose over-uses em-dashes. Target ≤1 per 100 words in human prose. [source]
List-of-three rhythm
Parallelism in bulleted lists
- Every bullet should start the same way: all noun phrases, all verb phrases, or all complete sentences. Do not mix. [source]
- Bad: "- Increased CSAT\n- Reduce churn risk\n- The team is happier" [source]
- Good: "- Increased CSAT by 15 points\n- Reduced churn risk by 30%\n- Improved team morale (Q3 survey)" [source]
- Apply when: writing any bulleted list. [source]
Curse of Knowledge (Pinker)
Cohesion vs coherence (Williams)
- Cohesion = local sentence-to-sentence flow (does sentence 2 connect smoothly to sentence 1?). [source]
- Coherence = global argument structure (does the whole doc build toward one conclusion?). [source]
- Both matter; they're different problems. Cohesion is sentence-level; coherence is structural. [source]
- Apply when: text reads OK sentence-by-sentence but feels aimless overall (low coherence), or the argument is sound but prose feels jumpy (low cohesion). [source]
Additional craft concepts (deep reference)
- The deep treatments of journalism structures (inverted pyramid, hourglass, bury-the-lede), [source]
- achievement frameworks (STAR/SOAR/PAR/CAR), sentence-level devices (deliberate fragments, [source]
- tricolon/isocolon, title vs sentence case, Oxford comma), cross-document consistency (style [source]
- sheets and term banks), the show-don't-tell evidence rule, the Curse of Expertise, [source]
- information scent, emphasis discipline (bold/italic/underline), and front-matter craft [source]
- (TL;DR, kicker, nutgraf, deck, tabular-vs-prose) each carry a rule, a worked example, and [source]
- source citations. **Read references/advanced-craft.md before giving a depth answer on any of [source]
- these** - the core rules above cover the common case; that file covers the edge cases and the [source]
- <!-- cross-hub-map --> [source]
Cross-hub map — where every writing topic lives
- This family is split across these hubs. If a task's deep material is not in this hub's Sub-skill [source]
- routing table, it is a reference file under a sibling hub below - **activate that hub or Read its [source]
- references/<name>.md directly**. Every former standalone skill in this family is now a reference under one [source]
- of these hubs (nothing was deleted). [source]
Children
- Document Critique
- Draft Review Revise Loop
- Editing and Revision
- BLUF and Minto Pyramid Frameworks (frontier)
- SCQA Framework (frontier)
- Tone Calibration by Audience (frontier)
- Anti-AI-ism Enforcement (frontier)
- Williams Sentence Craft (nominalization, Given/New) (frontier)
- Zinsser Four Enemies of Clutter (frontier)
- Pinker Curse of Knowledge (frontier)
- Executive Summaries and QBRs (frontier)
- Document Type Templates (frontier)
- Doc Archaeology
- Offer Design and Value Proposition
- AI-Assisted Copywriting Workflow
- Conversion Copywriting and Voice of Customer
Frontier under this node: Anti-AI-ism Enforcement, BLUF and Minto Pyramid Frameworks, Document Type Templates, Executive Summaries and QBRs, Pinker Curse of Knowledge, SCQA Framework, Tone Calibration by Audience, Williams Sentence Craft (nominalization, Given/New), Zinsser Four Enemies of Clutter