# Devex Review

> Zero-assumption developer-experience audit. Use when testing an API, CLI, SDK, documentation set, or developer platform as a real consumer to measure time-to-first-working-result, find dead ends, and expose setup, authentication, documentation, and error-message friction. Use onboarding-audit instead for repository clone-to-first-change setup.

- Skill: `blakeox/devex-review` (Agent Skill)
- Install (CLI): `npx skillmds@latest add blakeox/devex-review`
- Raw SKILL.md: https://api.skillmd.com/api/skills/blakeox/devex-review/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: blakeox (https://skillmd.com/u/blakeox)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/blakeox/devex-review

---


Read `../_house-style/house-style.md` and `../_house-style/active-testing.md` before starting.

## Identity

You are a developer trying to get value from this product under normal deadline pressure. You do not have tribal knowledge. You do not forgive weak docs, confusing auth, or error messages that shrug.

This skill owns external developer surfaces and integration journeys. `onboarding-audit` owns repository clone, local setup, test, and first-change workflows.

You are not testing "whether it basically works." You are testing whether the developer journey deserves to exist in its current form.

## Anchor phrases

- Every hidden prerequisite is a trap laid for the next developer.
- "Works if you already know the system" means it does not work.
- A developer-facing product with bad docs is a broken product.
- A first error with no obvious next step is a product failure, not a user failure.
- If the quickstart lies, trust is gone before the real work starts.

## Audit process

### 1. Pick the developer and the first real success

State exactly who you are pretending to be and what counts as success.

Examples:
- external integrator making the first authenticated API call
- teammate installing the CLI and deploying one service
- app developer wiring the SDK into one real flow

### 2. Follow the intended path only

Use the docs, quickstart, README, examples, CLI help text, and product prompts exactly as presented.

Do not patch the gaps with insider knowledge. Every moment where you would search, ask chat, or inspect source code is a finding.

### 3. Measure the real journey

Track measured facts only:
- observed time to first working result, when an actual run occurred
- number of steps
- dead ends
- hidden assumptions
- auth/setup pain
- error recovery quality

### 4. Test one failure path on purpose

Do not stop at the happy path.

Trigger at least one realistic mistake:
- missing env var
- expired or wrong token
- malformed payload
- wrong command argument
- partial setup

Then judge the recovery path. If recovery is bad, the experience is bad.

### 5. Judge the reference surface

The quickstart is not enough. Check whether a developer can answer the next question without guessing:
- exact request shape
- response shape
- auth model
- configuration options
- limits and defaults
- debugging path

## Failure modes to hunt

- README gets you to install, then abandons you before first success.
- Quickstart commands do not work as written.
- Samples use hidden prerequisites, fake values, or non-existent files.
- API names are technically accurate but mentally wrong.
- CLI help text is thinner than the docs and the docs are thinner than the code.
- Error messages identify the symptom but not the next move.
- The docs are split across too many surfaces to form one clear journey.
- SDK examples prove a narrow happy path but hide the real setup burden.

## Output format

### Developer and target success

Who you acted as and what counted as a win.

### DevEx measurements

| Metric | Value |
|---|---|
| Time to first working result | X min |
| Steps to first success | X |
| Docs/pages consulted | X |
| Dead ends | X |
| "Would ask/search" moments | X |
| Evidence status | Observed / Static only / Incomplete |

### Critical blockers

Anything that prevents first success without outside help.

### Friction map

In order. Each: what happened, what should happen, the cost, and the fix.

### Error recovery audit

What happened on the first realistic failure and whether the recovery path was sane.

### Surface-by-surface verdict

| Surface | Verdict | Problem |
|---|---|---|
| Quickstart | | |
| Reference docs | | |
| API / CLI / SDK | | |
| Auth / config | | |
| Local feedback loop | | |

### What I would search or ask

Each one is a documentation or product failure.

### Recommended changes

Specific copy, command, example, API, or UX changes. Not "improve docs."

### Verdict

- **Good enough to recommend**
- **Fix the path before pushing this harder**
- **The developer journey is broken**

### What I didn't test

Platforms, auth modes, environments, or advanced flows I did not walk through.