dx-first

DX First

Treat the development experience as a product surface of the repository. Optimize for three outcomes:

1. Reduce cognitive load — make the next useful action findable and the common path understandable.
2. Shorten feedback loops — give developers fast, trustworthy signals at the smallest useful scope.
3. Protect flow — remove waiting, context switching, avoidable choices, and surprising recovery work.

This is a human-developer experience skill. Properties that help coding agents are useful when they also make the repository clearer and safer for people.

Select a mode

• DX Audit — inspect and test the repository, then report prioritized friction. Remain read-only except for safe, ignored artifacts needed for testing.
• DX Improve — perform a focused audit, implement the smallest coherent set of fixes, update affected documentation, and rerun the journeys.
• DX Review / Guard — evaluate a feature, plan, pull request, refactor, or tooling change for workflow regressions. Do not edit unless implementation was requested.

If the request is ambiguous, use Audit for questions and Improve only when the user explicitly asks to fix or implement something.

Operating workflow

Follow this pipeline; do not replace it with a checklist of missing tools:

inspect → classify → trace → test → find friction → prioritize → improve → verify → simplify

1. Inspect. Read references/repo-inspection.md. Map the repository's structure, instructions, manifests, runtime and package-manager declarations, task entrypoints, tests, CI, documentation, and environment configuration. Inspect enough implementation to verify important claims; do not read the entire codebase blindly.
2. Classify. Identify the repository type, ecosystem, runtime, package manager, monorepo boundaries, setup path, development process, validation strategy, release shape, and any developer-facing API, CLI, SDK, or tool. Evaluate only surfaces that apply.
3. Trace. Start with the first contribution loop: clone → setup → run → change → validate. Then trace relevant daily tasks such as a targeted test, full validation, debugging, generated artifacts, migrations, CI reproduction, or release preparation.
4. Test. Execute supported paths when safe and practical. Prefer the real command, help output, invalid-input behavior, targeted check, or setup step over assumptions from file presence. Record step counts or timings only when actually observed.
5. Find friction. Read references/friction-catalog.md as needed. Record concrete symptoms, not vague quality judgments. Distinguish TESTED (executed or observed), VERIFIED (confirmed statically), and INFERRED (reasonable but unexecuted).
6. Prioritize. Order work approximately by developer impact × frequency × confidence ÷ implementation and maintenance cost. Fix blockers and repeated inner-loop friction before polish. Treat intentional tradeoffs as context, not automatic findings.
7. Improve. Prefer removal, simplification, clearer existing commands, and ecosystem-native mechanisms. Add a dependency, wrapper, task runner, hook, container, service, or configuration layer only when it removes evidenced friction and its maintenance cost is justified.
8. Verify. Rerun the affected journey and relevant repository checks. Compare the observed path before and after; do not claim an improvement from a file edit alone.
9. Simplify. Remove stale instructions, duplicate paths, temporary helpers, and complexity introduced during the fix. Read references/quality-checklist.md before finishing.