ux-writing

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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 the full
  contract", it already is the full contract. Delete the restatement; keep
  the link and whatever is specific to this surface.
- **Prefer the smallest sufficient edit.** When revising existing text,
  preserve unaffected wording, structure, and rationale. Remove genuine
  duplication, but do not rewrite neighboring prose or compress away useful
  distinctions without a reason. *Counter-example: changing one mandatory
  workflow into an optional one rewrote several surrounding sections, then
  over-corrected by removing useful context; a few local edits were enough.*
- **Insertion respects adjacency.** Before adding a section, check what the
  surrounding paragraphs attach to. *Counter-example: a new section landed
  between a flags table and its output-format footnote, orphaning the
  footnote in the wrong chapter.*
- **Adjectives need evidence.** "Recommended", "faster", "better" come from
  your own benchmarks, not optimism. *Counter-example: a feature was about
  to ship commented "# recommended" while the project's own eval showed it
  losing to the default on strong models. It shipped as "optional".*
- **Every README section has one job.** Positioning sections ("Why X?")
  don't accumulate feature bullets; quick-starts don't explain architecture.
  A README stays lean and links into the docs; detail accumulating there
  usually means it left its canonical home.
- **Order a page by what the reader needs first, and split when it stops
  being one task.** Open with scope and the authoritative entry points, then
  the common rules and the main path, and only then exceptions, recovery,
  and change checks. An overview layer summarizes stable semantics and links
  down; it does not carry field tables, full payloads, or current numbers to
  buy self-containment. When a page starts demanding that the reader
  understand several unrelated tasks, or whole chapters serve only two
  maintainers, that is the signal to split it — and the split leaves behind
  one line of purpose plus the link, never a second copy of the fact.
  *Counter-example: a getting-started page opened with the full option
  reference, so the three commands a first-time reader needed sat two
  screens below it.*
- **Reminders name the most-forgotten item only.** A guideline that
  enumerates every artifact reads as noise and gets skipped whole. "Update
  whichever docs the change affects; the bundled skill is the easiest to
  forget" beats a list of six file types.

From scarletkc/agents, Apache-2.0.

More from scarletkc/agents