technical-writing

---
name: technical-writing
description: >-
  Write or revise durable technical prose such as READMEs, reports, findings,
  runbooks, design notes, and pull-request descriptions. Do not use for ordinary
  chat replies or code-only changes.
---

# Technical Writing

## Contents

- Source and audience
- Style
- Structure and claims
- Review

## Source and audience

- Write for the document's audience and decision. Use the requested format, the repository's
  terminology, and applicable templates. Base claims on the relevant source of truth.
- Verify facts that can change. Use absolute dates in durable prose and link to the narrowest
  authoritative source with short, descriptive link text.
- Describe the artifact as it exists now. Do not narrate discarded approaches or include history
  unless the audience needs it to understand a current decision.

## Style

- Lead with the consequence, result, or decision. Use plain, factual language, complete sentences,
  precise technical terms, and specific verbs.
- Prefer the everyday word when it preserves the meaning. Keep necessary domain terms instead of
  replacing them with approximate synonyms.
- Avoid comparative reframing such as “not just X, but Y,” mirrored sentence contrasts, default
  triads, sentence fragments, throat-clearing openings, hollow emphasis, and conclusions that only
  repeat the body.
- Avoid press-release filler, including “delve,” “underscore,” “bolster,” “foster,”
  “harness,” “leverage,” “utilize,” “pivotal,” “crucial,”
  “robust,” “seamless,” “intricate,” “meticulous,” “nuanced,”
  “multifaceted,” “holistic,” “testament,”
  “showcase,” “landscape,” “realm,” and “pave the way.”
- Do not use em dashes or `Bold term:` explanation lists. Use headings and lists only when they make
  the document easier to scan.
- Unpack dense noun stacks, prefer verbs to noun forms of verbs, and expand shorthand unless the
  audience routinely uses it. Keep modifiers and pronouns attached to unambiguous subjects.

## Structure and claims

- Use forward chronology for procedures and narratives. Keep prerequisites before the actions that
  depend on them and place warnings immediately before the risky step.
- State scope and limitations directly. Distinguish observed results, sourced facts, inferences,
  assumptions, and recommendations.
- Make every impact claim proportional to the evidence. A bug fix is a bug fix; do not label it
  critical, broad, or comprehensive without evidence.
- In a pull-request description, explain the resulting diff, its reason, and validation. Do not
  describe code or checks that are absent.

## Review

Before finishing, check facts, claims, links and paths, prerequisites, and project terminology. Run
applicable link, render, or documentation-build checks.