/ux-writing

name: ux-writing
description: "Judgment rules for user-facing text and docs: CLI and diagnostic output, error and help text, README and docs structure, code comments, titles, and generated reports, decks, or exports. Use when writing or changing any user-visible string, when adding or restructuring docs or deciding which page owns a fact, when a page is about to record a version, a deployment state, or a value the code already owns, when a comment, title, or artifact could carry the reasoning or an abandoned option behind the change, when a behavior change needs its copy sites swept, or when reviewing a diff that touches copy or docs."
license: Apache-2.0
metadata:
  author: scarletkc
  source: https://github.com/scarletkc/agents
  summary: "Review user-facing copy and documentation for clarity, consistency, facts that do not go stale, and no leftover intermediate state."

UX Writing & Docs

User-visible text is product behavior and carries the same quality bar as code. Every rule below is distilled from a real defect caught in review, and keeps its counter-example because the reasoning is the point. When in doubt, re-read the output as the user who just hit the problem.

Status output & diagnostics

• **Report effective values, not stored ones.** A status display answers

"what will happen when I run this", so resolve values exactly the way the runtime does, including environment variables and layered config. *Counter-example: a config viewer printed "API key set: no" while an env var held the key the next run would actually use.*

• **Diagnostics must stay truthful under failure.** When one config layer

fails to load, fall back to the most complete state that still loads, never to blank defaults. A diagnostic that misreports is worse than one that aborts. *Counter-example: a broken project-level config made a doctor command check blank defaults and report a missing API key that was in fact configured; the fake failure buried the real one.*

• **Show deltas, not dumps.** A health/diagnostic command lists what

deviates and who set it; the exhaustive listing belongs to the dedicated inspect command. Don't make one command duplicate another's job. *Counter-example: a doctor check printed fifteen "field: origin" lines, most of them saying "global". One line naming the two real overrides replaced the block.*

• **Annotate at the granularity of the claim.** If one sub-part of a

composite value has a different source or state, say it on the sub-part; don't relabel the whole. *Counter-example: an env-injected API key relabeled an entire endpoint block "(environment)" although its URL and model came from a file. The fix was "key from env", with the block label unchanged.*

• **Re-read neighboring labels after adding metadata.** New suffixes collide

with existing value labels. *Counter-example: "Embedding dimensions: default (default)", fixed by renaming the value "auto".*

• **Machine-readable output is a contract.** Porcelain/TSV/JSON output never

gains decoration, notices, or annotations; informational text goes to stderr or the human-format path. Absence is part of the contract, so write the negative test (`"(project)" not in stdout`).

• **Never truncate the payload.** Paths, IDs, and URLs in diagnostics must

survive narrow terminals un-ellipsized (disable auto-wrap/crop for those lines); a truncated path cannot be copied into the next command.

Error messages

Every error answers three questions: what happened, where, and what to do now. The strongest pattern: name the offending file or input, list the rejected fields, list the allowed fields, and say where the rejected setting belongs instead. Fail loudly rather than degrade silently; when catching an exception purely to suppress a traceback, keep the message intact.

Documentation

• **Each document has one responsibility, and it decides what belongs.** A

page is a durable contract, a proposal, an investigation, a TODO, a dated work order, or a runbook — one of them, not several. Naming that first is what makes a canonical home decidable: a fact lives on the page whose job it is, and every other surface reaches it through a single specific link instead of a partial retelling on each page that happens to touch it. When two pages both claim to be the detailed spec, the broader responsibility keeps the shared rules and the narrower keeps only what its own surface adds. *Counter-example: an implementation plan stayed the de-facto spec after shipping, so the rules lived half there and half in the architecture doc; folding the stable rules into the contract and leaving the sequence in git history left one page to trust.*

• **Rationale is a genre of its own.** A how-to answers what to run, a

reference answers what exists, and why-it-was-built-this-way belongs to a design record, an ADR, or the pull request that decided it. Answering the design question inside a usage page pushes the steps the reader came for below the fold, and the argument is also the part that rots first: the implementation moves on and only the guide still defends the old choice. An explanation produced because someone asked once belongs in that answer, not in a permanent page. *Counter-example: a setup guide spent its second paragraph on why this queue was chosen over two others; the queue was replaced a release later and the paragraph outlived it.*

• **One canonical home per fact.** Details that change together (field

lists, precedence chains, supported values) live in exactly one document; every other mention links to it. Legitimate copies: artifacts distributed standalone (a bundled skill file that ships without the repo), and genuinely surface-specific nuance. *Counter-example: a seven-field allowlist pasted into five docs.*

• **Restating and linking is a bug, not thoroughness.** If a section

duplicates the canonical content and then ends with "see X for th