/ergonomics

name: ergonomics
description: "Audit CLI, API, MCP or SDK discovery, first use and error recovery. Use when: designing an agent-facing tool or investigating misuse, including one command."
practices:
- ai-assisted-dev
- design-by-contract
- twelve-factor-app
- pragmatic-programmer
hexagonal_role: driven-adapter
consumes:
- repo-context
- interface-design
produces:
- ergonomics-findings
context_rel:
- kind: supplier-to
  with: implement
- kind: partnership
  with: doc
skill_api_version: 1
user-invocable: true
metadata:
  graph_root: true
  tier: product
  dependencies: []
  capabilities: [audit_interface_ergonomics, review_interface_design, exercise_tool_surface, check_error_contract]
  effects: [run_target_in_disposable_environment]
  canonical_status: canonical
  disposition: keep_specialist
output_contract: 'located findings with literal reproduction, agent consequence and smallest fix, plus exercised and not-exercised scope; no score or verdict'

Ergonomics

Judge a tool surface from the position of its most literal consumer, an AI agent: a CLI, HTTP API, MCP or agent tool, SDK or library, or a proposed design for one. A human developer is the second consumer and is usually served by the same fixes. Neighbours: threats are [Security](../security/SKILL.md); help text and READMEs are [Doc](../doc/SKILL.md); lasting proof is [Test](../test/SKILL.md); applying fixes is [Implement](../implement/SKILL.md); acceptance is [Validate](../validate/SKILL.md).

The literal reader

An agent sees only text, exit codes and structured output. It has no screen, no colour cue and often no terminal or open stdin. It copies the printed next step and runs it as written. It cannot ask what a message meant. When something fails it retries, and a retry after a mutation that may already have happened is where a vague error costs the most. Read every help page, output and error as that reader would, and ask what it does next.

Select the mode

• **Plan mode** reads a proposed interface: design doc, spec, draft help text

or PR description. A failure path the design introduces without saying what the caller sees is a finding, not an unknown; so is a user action it adds with no agent path and no stated reason.

• **Live mode** exercises a built surface under [Authority](#authority).

Unexercised commands are gaps, never passes.

• Use both when a design makes claims about an existing surface. If no surface

is named, ask once which surface and which mode, and wait.

What to examine

**Coverage.** When the product also has a human interface, each valuable domain action there (create, change, approve, send, export, recover) has an agent-callable equivalent. The agent reads the same records, state and terms the person sees and acts on those same objects, not a separate agent copy. Consent, CAPTCHA, password entry, terms acceptance and approval steps the product keeps human on purpose stay human-only. Rank a missing path by the value of the action it blocks; preference screens rarely matter.

**Discovery.** Help lists every command, flag, argument, default and required input. Each common task has a runnable example, and the examples run. One concept keeps one word and one flag everywhere. Short help points to deeper help instead of printing everything. A health command names what is missing and how to fix it, and keeps "not installed" apart from "ran and failed". The observable outcome is first success from a clean environment: the steps from install to the first correct result, and every point where the reader guessed.

**Sign-in.** An agent can start sign-in without holding the secret: a non-interactive login prints an approval URL and short code for a human to confirm, or the tool reads a credential from the caller's environment or keychain. A status command then confirms sign-in without printing the token. A login that takes the secret only as a flag, a prompt or text the agent must relay is a finding.

**Output.** A documented machine-readable mode keeps stable field names and the same facts as the human output. Data goes to stdout and diagnostics to stderr, so machine output parses unmixed. Exit 0 means success only; distinct non-zero codes separate failures the caller would handle differently. With no terminal the tool never waits on a prompt, pager or spinner: it fails fast and names the non-interactive flag. API and MCP failures use the surface's own error signal. List, search and log output is bounded by default, since an agent carries every line for the rest of its session; it says when it cut results and names the flag, filter or cursor that returns the next page or the full set.

**Errors.** Check every failure against the [error contract](references/error-contract.md):

1. what failed, with the actual offending value, path or id; 2. why, including the underlying cause rather than a swallowed one; 3. the exact safe next command, flag or edit on the first or last line, or exactly what a human must supply when no safe automatic fix exists; 4. whether retrying is safe, and which side effects already happened; 5. after a mutation with an unknown outcome, how to check it before retrying; 6. a stable code that survives rewording, with a place to look it up; 7. the version, config in effect and env var names (never values) that matter; 8. no secret, token or credential-bearing URL, nested causes included; 9. the surface's failure channel, with the same fields in machine mode.

A usage error rejected before any work needs items 1, 3, 6, 8 and 9. A next step that skips a confirmation or safety check, or replays text from untrusted output as a command, is itself a finding.

**Mutations.** A dry run previews the change. Repeating a command reaches the same end state or says it was already done. A destructive action asks first; its non-interactive override is an explicit flag, never the default, and the refusal names it. A partial failure says what completed.

Live exercise

1. Inventory