write-tech-document

Files (1)

• SKILL.md

SKILL.md (first lines)

# Write Tech Document

Help readers understand the point, assess the evidence, and decide what to do. Apply these principles to the requested text while preserving its meaning, audience, language, and required format.

## Writing principles

- **Answer first.** Lead with the answer, finding, recommendation, or decision needed. For a direct question, start with yes, no, a number, or “I don't know” when appropriate, then add necessary context. Open-ended questions still need substantive answers. Do not promise a follow-up unless there is an agreed way to deliver it.
- **Keep sentences short.** Aim for fewer than 30 words per sentence. Split overloaded sentences, but retain qualifications needed for accuracy and natural flow. Replace padded phrases: “due to the fact that” becomes “because”; “totally lacked the ability to” becomes “could not.”
- **Prefer evidence to evaluation.** Replace unsupported adjectives and adverbs with relevant measurements or concrete observations. Keep descriptive words that carry factual meaning. For comparisons, retain the metric, units, baseline, period, and population when available. Distinguish measured results from forecasts and targets.
- **Make vague claims specific.** Scrutinize phrases such as “significantly better,” “nearly all,” “arguably the best,” and “will bring benefits.” State what changed, for whom, and by how much when supported. Distinguish relative percentages from percentage-point changes; explain basis points if used.
- **Use accessible language.** Prefer familiar words to jargon. Explain necessary technical terms, acronyms, and abbreviations on first use for the intended audience. If a term appears only once, its plain-language form usually suffices.
- **Pass the “so what?” test.** Connect facts to the reader's question, customer impact, business consequence, or requested decision. Remove details that do not help the reader understand or act. Do not invent an implication merely to supply one.

## Evidence boundaries

Precision must come from the supplied material or a verified source. Never invent a number, baseline, measurement definition, causal explanation, or commitment to improve the prose. Preserve citations and the limits of their claims.

If evidence is missing, use a narrower supported statement, identify the gap briefly, or use an explicit placeholder in a draft when useful. Ask for missing information only when it prevents a useful result. Do not turn correlation into causation or an estimate into a guarantee. Words such as “may,” “estimated,” and “likely” are appropriate when they express real uncertainty.

For example, if supplied measurements support it, replace “The application is much faster” with “Server response time fell from 10 milliseconds to 1 millisecond.” Preserve any supplied percentile and test conditions. Without measurements, do not borrow those example numbers; flag that the performance claim needs evidence.

## Deliver the requested result

For drafting or rewriting, return usable prose in the requested format. Add a short evidence-gap note only when necessary. For a review, identify consequential weaknesses and propose concrete edits. Do not impose a memo template, a change log, or an explanation of every edit unless requested.

From faridz974/skills, MIT.

More from faridz974/skills