diff --git a/README.md b/README.md index ae77dc8..ae6634a 100644 --- a/README.md +++ b/README.md @@ -10,6 +10,9 @@ directory with a `SKILL.md` file that describes when the skill should be loaded - `mentor`: switches an agent into learning-first mentoring mode for developing engineers. - `claude-usage-report`: reports Claude Code usage & cost from local session transcripts. (For per-account attribution across multiple accounts, install as a plugin instead — [see below](#installing-claude-usage-report-skill-vs-plugin).) +- `precise-technical-writing`: picks a writing mode per artifact for durable technical text — docs, code + comments, PR descriptions, runbooks, handoff notes — and holds claim strength steady while tightening wording. + Procedural text follows controlled English modeled on [ASD-STE100](https://www.asd-ste100.org/). ## Install diff --git a/skills/precise-technical-writing/SKILL.md b/skills/precise-technical-writing/SKILL.md new file mode 100644 index 0000000..9e72fae --- /dev/null +++ b/skills/precise-technical-writing/SKILL.md @@ -0,0 +1,137 @@ +--- +name: precise-technical-writing +description: Use when writing or refining durable technical text — docs, code comments, PR descriptions, issue bodies, runbooks, handoff notes, agent instructions — or when another skill needs a final wording pass. Applies implicitly to durable artifacts. +metadata: + author: Scott Pfister (scott.pfister@7factor.io) +--- + +# Precise Technical Writing + +Write for precision: an engineer or agent reading this later must not have to guess what it meant. + +## Gears + +Control is a dial, not a switch. The four gears are one style at four compression ratios, ordered from most prose to least. + +| Gear | Name | Prose | Shift here when | +| ---- | ------------- | ----------- | -------------------- | +| 1 | `narrative` | Most | Exploration matters | +| 2 | `engineering` | Default | — | +| 3 | `controlled` | Little | Precision matters | +| 4 | `reference` | Almost none | Later lookup matters | + +Start in gear 2. Shift to 3 or 4 when precision or lookup matters. Drop to gear 1 only when exploration, persuasion, or live disagreement matters. + +Shift per section, not only per document. An ADR runs gear 3 for the decision, gear 2 for the rationale, gear 1 for the discussion. + +In conversation, keep the reply natural and apply the gear's spirit. Full refinement is for durable text. + +## Choosing a gear + +Classify intent first, artifact second. + +| Intent | Gear | +| --------------------------------------------------------------- | ---- | +| `instruct` — tell someone what to do | 3 | +| `specify` — state requirements, contracts, invariants, criteria | 3 | +| `look-up` — help someone find a fact later | 4 | +| `explain` — help someone understand | 2 | +| `justify` — give rationale, tradeoffs, or risk | 2 | +| `respond` — answer a person, in review or collaboration | 2 | +| `explore` — think through unknowns or options | 1 | + +When intent is mixed or unclear, fall back to the artifact: + +| Artifact | Gear | Shift for | +| ------------------------------------------------ | ------------------ | -------------------------------------- | +| Code comment | 3 | 2 for rationale | +| API doc, runbook, procedure, acceptance criteria | 3 | 2 for background | +| Agent skill, project instructions | 3 | 4 for lookup tables, 2 for context | +| PR description | 2 | 3 for testing, rollout, reviewer steps | +| Review reply | 2 | 3 for exact commitments | +| Explainer, design summary, issue body | 2 | — | +| Architecture index, module summary, repo guide | 4 | 2 for short context | +| Handoff note | 4 | 3 for next steps and commands | +| ADR | 3 for the decision | 2 for rationale, 1 for discussion | +| Brainstorm, strategy, RFC discussion | 1 | — | + +## Gear rules + +Each gear adds only what is listed here. + +### 1 `narrative` + +- Preserve uncertainty and disagreement. +- Say why each option was accepted or rejected. +- Leave tradeoffs as tradeoffs. +- Label facts, opinions, and recommendations separately. + +### 2 `engineering` + +- Give each paragraph one purpose. +- Cut filler, hedging, and marketing language. +- Name the assumptions and the limits. +- Split summary, detail, risk, and verification when the reader needs them apart. + +### 3 `controlled` + +Controlled English modeled on ASD-STE100, with software vocabulary in place of the approved word list. ASD-STE100 exists to remove ambiguity for readers who are not native English speakers. Write for that reader. + +- Use active voice and an explicit subject. +- Put one action or one claim in each sentence. +- State the condition before the action. +- Keep sentences under about 20 words. +- Use the same term for the same concept every time. +- Use concrete verbs in place of abstract nouns. +- Use ordered lists for procedures. +- Name each error state the source describes, and its consequence. +- Keep precise software terms. A clear sentence beats rule compliance. + +### 4 `reference` + +Built for an agent to retrieve first and a human to read second. + +- Use stable headings and field names. +- Put facts under predictable labels, where a reader finds them without reading prose. +- Give explicit names, paths, commands, owners, states, and links. +- Use these fields where the source supports them, and omit the rest: Purpose, Responsibilities, Inputs, Outputs, Dependencies, Invariants, Failure Modes, Open Questions. +- Always include a `Sources` field listing the paths the facts came from. A reference doc describes something it is not connected to, so the reader needs the path to re-check it. Without one, the doc drifts and nobody can tell. Where the source gives no paths, say that instead. + +## Claim safety + +Tightening the wording must not tighten the certainty. This rule outranks concision. + +- Carry each claim across at its original strength. +- Label assumptions as assumptions and unknowns as unknowns. +- Cite the source path, command, or evidence for each claim in durable text. +- Say a claim is unverified, or ask to verify it, rather than writing around it. +- Add nothing the source did not contain: no internal detail, no commitment, no date. +- Leave a field, step, or heading empty when the source does not support it. Write + `Unknown:` and stop. An empty field costs a reader nothing; an invented one costs + them a wrong decision. + +Use labels where the distinction carries weight: `Fact:` `Assumption:` `Unknown:` + +This rule also outranks every structural rule below it. A gear that asks for a field, +an error state, or a recovery path is asking you to look for one, never to supply one. + +Done when every claim in the output traces to a claim in the input at equal or weaker strength. + +## Refining text that already exists + +A rewrite keys off the prose it reads, so vocabulary changes and weak structure survives. Rebuild instead: + +1. Extract the claims, steps, and open questions as a bare list. +2. Pick the gear from that list, not from the old prose. +3. Write from the list. +4. Check the claim-safety criterion against the original. + +## Embedded use contract + +Other skills reach this skill with: + +> Before finalizing durable technical writing, apply `precise-technical-writing`: pick a gear, write from claims, hold claim strength steady, and structure for later retrieval. + +## Drift + +A gear holds for a few turns, then slips. Where a repo needs the style enforced instead of requested, gate on a prose linter such as [Vale](https://vale.sh) at pre-commit or `PostToolUse`. The skill sets the target; the gate holds it.