dx

---
name: dx
description: Audit, debug, or design a developer-experience surface — anything a developer installs, calls, or extends: API, SDK, CLI, setup and packaging, error messages, auth and API keys, config, IDE/editor integration, plugin contracts, telemetry. Existing surface: DX review, friction audit, 'is this error message OK', debugging a confusing integration failure, or a pre-ship edge-case risk pass. New surface: shape the public API, error envelope, auth model, config precedence, or plugin contract before it ships. Triggers: 'DX review', 'audit our API/SDK/CLI', 'design a new API/SDK/CLI', 'shape the public surface', 'what should we get right up front'. Do NOT use for docs as a reading surface (READMEs, changelogs, quickstarts, contributor docs, samples), for SDK/tool/error surfaces an agent consumes, or for end-user UX and visual UI.
license: MIT
---

# DX

Infer direction and surface from the request — never ask which mode:

- **Existing surface** → audit friction, debug a confusing failure, or run a pre-ship edge-case pass. Open with the first-impressions pass below, then load the matching sections of [`references/surfaces.md`](./references/surfaces.md).
- **New surface** → shape the contract before it ships. Load [`references/designing.md`](./references/designing.md) plus the matching sections of `surfaces.md`.

**Core principle: make the paved path obvious and failure states actionable.** If a competent developer must guess, hunt through source, copy a stale example, or debug avoidable setup, that is a finding. The cheapest fix is before the contract ships — every observable behavior of a shipped interface gets depended on.

## Invariants

- **Errors are UI.** Every error names the cause, the fix, and enough context to reproduce it; a bare "Invalid request" or "Unauthorized" is a finding wherever it appears. Redact secrets from every error, log, and verbose-output level.
- **First-impressions bar.** Open every audit or edge-pass with the 30-second first-impressions pass below. Time-to-first-success gates everything.
- **Concrete over abstract.** Every finding or design names the target developer (evaluator, first-time user, integrator, contributor, maintainer, operator, migration user), the named heuristic, and the concrete fix or paste-ready shape. Designs end with acceptance criteria checkable by reading the artifact or running a command.

## First-impressions pass

A 30-second binary pass — the call an evaluator makes before deciding whether to adopt at all. Run it before any deep-surface work, so the basics are never hidden behind a good deep score. Every item is yes / no / n/a, observable in under 30 seconds from the repo, registry page, or first-run output:

1. `README.md` exists with a one-line value prop in the first paragraph.
2. The install command is visible without scrolling past the README header.
3. The first code example pastes and runs with one substitution.
4. `--help` (CLI) or the primary import surface (SDK) produces useful output on first call.
5. `--version` (or the exported version field) returns a real version string, not `dev`.
6. A `LICENSE` file sits at the repo root.
7. A `CHANGELOG.md` (or equivalent release notes) has an entry for the latest version.
8. A fresh-machine install completes with a single command, ending in a verifiable success signal.
9. The error from the first reasonable wrong input names the cause and the fix.
10. The README links onward to deeper docs, examples, and contributing info.

Scoring: record yes / no / n/a per item — mark genuinely inapplicable items `n/a` with a one-word reason, never silently drop one. Report as `passed / applicable` with skips appended: `First impressions: 7 / 9 (1 skipped) — failed: 2 (install below the fold), 5 (--version prints "dev")`. Keep the denominator visible. **Verdict cap:** more than two applicable items failing caps the overall verdict — the surface cannot be reported healthy, however well the deep surface reads. Each failed item becomes a regular finding under its surface. All items n/a (rare) → omit the section and say why.

## Workflow

1. **Assess.** Existing or new? Which surface(s) — API, SDK, CLI, errors, auth, setup/packaging, config/logging, migration, IDE/plugins, perf/telemetry? State the inference and proceed; ask only when neither direction nor surface is inferable.
2. **Load** only the matching reference sections.
3. **Apply** the named heuristics; cite each one a finding or design choice rests on. For debugging, rank hypotheses before naming fixes.
4. **Emit** the audit findings, debug runbook, or design doc with rationale.

Run to completion; state assumptions inline. Stop after one emission — a second pass only if a failed first-impressions item was left without a finding; never a third.