# Technical Writing: Ambiguous Instructions
Use for passages where a reader must perform an action or distinguish system states: installation steps, operating instructions, error text, tool descriptions, and wording-only edits to agent instructions. In a mixed README or article, apply this reference only to those passages. Keep the language reference and the author's voice elsewhere.
The target is one recoverable meaning, not the shortest sentence. The Core Stance and Hard Rules in `SKILL.md` still apply. A clear instruction needs no rewrite. Reviewing or rewriting an instruction never authorizes executing it, changing tool behavior, or redesigning a prompt's authority and workflow.
## Ambiguity Catalog
Use the rows that explain a real misreading. These are semantic checks, not word bans or a checklist to apply to every sentence.
| Smell | Decision boundary | Example |
|---|---|---|
| Name drift | Use the established name for the same entity or action within its scope. Preserve different names for different concepts, and exact UI labels, API identifiers, flags, paths, and placeholders. Similar verbs do not prove identical actions. | If both names refer to one object, replace "Select the workspace. Delete the project." with "Select the workspace. Delete the workspace." Leave "Check the address. Confirm delivery." alone: those actions differ. Keep `cancel`, `timeout`, and `fail` distinct when the system does. |
| Missing actor or referent | Name the actor or object when two are plausible. Passive voice stays when the actor is irrelevant or unknown; never invent an actor to make a sentence active. | "After the worker notifies the scheduler, it retries" requires evidence about which component retries. Ask or flag the ambiguity if the source does not resolve it. A subjectless boundary reads as a product guarantee: "Renders only trusted local HTML" promises a check the tool may not perform, while "Render only HTML you trust" states the reader's obligation. |
| Buried condition or negation | Attach each condition, exception, and prohibition to its action. Preserve whether the condition is sufficient or necessary, and whether a limit is inclusive. Do not move a qualifier across actions it does not govern. | "Restart only if validation passes" cannot become "If validation passes, restart": the first makes passing necessary, while the second directs a restart whenever validation passes. |
| Flattened logic | Preserve all/any, and/or, not/except, and the scope of each list item. Splitting a sentence must not turn alternatives into mandatory sequential steps. Resolve what an "otherwise" branch tests: permission to attempt an action and successful completion are different conditions. | "Requires an owner or an editor with approval" is ambiguous about whether owners need approval. Resolve that fact before creating a permissions list. "If automatic recovery does not succeed, notify the operator" cannot become "If automatic recovery is disabled, notify the operator": enabled recovery can fail too. |
| Lost sequence or dependency | Separate actions when this makes their order clear, keeping the prerequisite or completion condition attached. A compact, unambiguous action pair can stay together. Number only genuine sequences; do not manufacture order for alternatives. | "After the upload completes, delete the local copy" must retain "completes". "Start the upload. Delete the local copy" permits deletion too early. |
| Compressed grammar or noun stack | Restore the relation between nouns and keep sentence parts needed to interpret them. Short UI labels and established technical terms are not defective sentences. | "worker task cancellation policy" needs context: a policy for cancelling worker tasks is different from a policy used by workers to cancel tasks. Do not pick the smoother interpretation without evidence. |
| Changed obligation or state | Keep requirement, permission, capability, confidence, and time distinct. Removing nominalization is useful only when those meanings survive. An instruction addressed to an agent does not make a recommendation mandatory. | "The client must perform validation" can become "The client must validate." Preserve "You should inspect the report" and "The request may have failed": "Inspect the report" increases obligation, while "The request failed" increases certainty. Keep completed work distinct from queued or started work. |
| Remedy without evidence | Separate the observed error from its possible cause and proposed next action. A wording-only rewrite does not add a remedy or requirement, even a reasonable one. When substantive additions are requested, ground them in the source or implementation and distinguish them from preserved text. | "Connection timed out" does not establish invalid credentials. Do not rewrite it as "Your password is wrong. Sign in again." "The export can be incomplete" does not itself instruct a retry or an integrity check. |
## Controlled-English Spillover
STE-inspired clarity is useful here; a universal controlled-English grammar is not. Keep natural tenses, phrasal verbs such as `sign in`, domain vocabulary, and sentence rhythm when they carry the correct meaning. There are no fixed sentence, paragraph, or noun-count caps. English word limits do not transfer to Chinese. Existing project punctuation conventions still apply.
Terminology consistency is scoped to the document and its product model, not a global one-word-one-meaning dictionary. Define an unfamiliar term only when the audience needs it and the source establishes its meaning; do not append a glossary to every output. Prefer the real interface term over an easier synonym that users cannot find on screen. For UI navigation paths, follow the breadcrumb rule in [write-product-localization.md](write-product-localization.md).
## Meaning Check
Compare the edited passage with its source at the decisions a reader can make: who acts on what, under which conditions, in which order, with which permission or obligation, and with what stated result. Preserve values, units, ranges, exceptions, uncertainty, and literal interface strings wherever present. If either version allows an action or interpretation that the other excludes, resolve the difference before delivery. Do not add missing facts merely to fill these categories: "supports multiple providers" does not imply "keeps all data on your device", and a warning is not an unstated recovery procedure.
Punctuation and pattern checks cover only their implemented syntax; a clean result does not establish meaning preservation. A synonym match or long sentence is a reason to read the context, not an editing command. When evaluating this mode, pair a flawed passage with a nearby correct one under the same request and runtime, then inspect the actual output for both corrected ambiguity and forbidden changes. Include no-edit cases such as "Select Sign in", distinct actions with similar verbs, a clear long sentence, and the author's own finished draft. Evaluate permissions and failure branches using concrete situations, including an allowed action that does not succeed; keyword retention alone cannot prove that those situations still produce the same instructions.
For an unresolved ambiguity, a review names the competing readings; a rewrite asks a focused question or preserves and flags the affected phrase. Do not silently choose the interpretation that makes the text easiest to edit. Follow `SKILL.md` for the requested output shape and author-draft change lists; do not append a rule score or compliance report by default.
## Sources and Boundary
This is an original adaptation informed by [asd-ste100-skill's writing-rule summary](https://github.com/danyuchn/asd-ste100-skill/blob/master/references/writing-rules.md) and its [scope and preservation guidance](https://github.com/danyuchn/asd-ste100-skill/blob/master/SKILL.md). It uses selected clarity principles, not that project's strict or STE-flavored modes. Waza does not reproduce the approved dictionary or certify ASD-STE100 compliance.
When explicitly asked to assess compliance with a writing standard, consult its primary text at the applicable version and identify that version in the assessment. Report the requirements actually checked and any coverage gaps. Partial checks support only partial conclusions; missing source text or evidence rules out a claim of overall compliance. For STE, use the [official ASD-STE100 source](https://www.asd-ste100.org/). The [STEMG white paper on STE and AI](https://www.asd-ste100.org/assets/files/WhitePaper-ASD-STE100_and_AI.pdf) discusses the limits of AI-assisted technical writing and review.