technical-writing

Technical Writing

Make a technical truth usable. Give the reader a recognizable problem, a clear model, enough proof to trust it, the boundary of the claim, and a concrete next move.

Choose the mode

Select one mode before doing the work:

• Plan: Return the reader contract, evidence gaps, selected document pattern, section beats, and verification plan. Do not draft the prose unless asked.
• Draft or rewrite: Return publication-ready prose in the requested format, plus unresolved verification notes only when they affect safe use or publication.
• Review: Return prioritized editorial findings or an annotated draft at the requested depth. Do not silently replace a review with a rewrite.

If the request combines modes, keep their artifacts distinct.

Establish the reader contract

Recover these from the request and source material:

• Reader: Who will use this, and what can they already know?
• Job: What should they understand, decide, build, debug, or review afterward?
• Friction: What failure, cost, misconception, or constraint makes the piece necessary?
• After-state: What observable result would mean the document worked?
• Boundary: What is deliberately out of scope, unchanged, or uncertain?
• Evidence: Which code, commands, data, sources, screenshots, logs, or lived examples can carry the claims?

Infer low-risk gaps. Ask only when a missing answer would materially change the artifact. Preserve the user's format, scope, and own voice or requested abstract voice qualities; use original phrasing rather than imitating a named writer.

The contract is complete only when all six fields are explicit in the working notes.

Select the document pattern

For a substantial plan, draft, rewrite, or structural review, read the closest pattern in references/document-patterns.md. Use one primary pattern and borrow another only when the reader's job genuinely crosses formats.

The pattern is selected when its reader job matches the request and its completion criterion describes the intended after-state.