Plan Devex Review

Plan DevEx Review

Use this skill to review the planned developer experience before implementation. It applies only to developer-facing surfaces such as APIs, CLIs, SDKs, MCP servers, plugins, integration docs, and getting-started flows.

Do Not Use

Do not use this for:

• Consumer web UX, landing-page design, or general product copy.
• Backend architecture with no developer-facing surface.
• Live onboarding tests after implementation; use devex-review for that.
• General engineering plan review; use planmode-engineer.

Core Rule

A developer-facing plan is not ready unless a new developer can understand the promise, reach a first useful result, recover from common errors, and know what to do next.

Target Gate

Before reviewing, identify the target:

• API plan or OpenAPI/schema change.
• CLI command, flag, config, or install plan.
• SDK package, import path, or example plan.
• MCP server, plugin, skill, or integration surface.
• Developer documentation or getting-started guide.

If the target is not developer-facing, say this skill does not apply and recommend the appropriate review skill.

Workflow

1. Define the developer persona.

   • First-time evaluator, integrating engineer, internal maintainer, partner developer, plugin author, or open-source contributor.

2. Map the planned journey.

   • Discover.
   • Install or authenticate.
   • Configure.
   • Run the first example.
   • Get the first useful result.
   • Debug the first failure.
   • Move to the second task.

3. Estimate TTHW.

   • Count commands, files, accounts, tokens, approvals, docs pages, and decisions.
   • Identify the first magical moment.
   • State the target TTHW and why it is realistic.

4. Review the interface contract.

   • Naming, command shape, endpoint shape, arguments, defaults, examples, errors, versioning, compatibility, and migration path.
   • Prefer explicit defaults and reversible setup.

5. Review failure design.

   • Missing credential.
   • Invalid config.
   • Permission denied.
   • Network/provider failure.
   • Version mismatch.
   • Rate limit or quota.
   • Example drift.

6. Produce a readiness verdict.

   • READY: the plan can proceed without DX decisions during implementation.
   • READY WITH RISKS: implementable, but friction or assumptions must be tracked.
   • NOT READY: developer-facing decisions are missing.

Review Dimensions

Output Contract

## Plan DevEx Review

### Target
Surface: API / CLI / SDK / MCP / plugin / docs / onboarding
Persona:

### Verdict
READY / READY WITH RISKS / NOT READY

### Journey Map
Discover -> Setup -> First Example -> First Useful Result -> First Failure -> Second Task

### TTHW Assessment
Current estimate:
Target:
Step count:
Main friction:

### Findings

#### PDX-001: <title>
Severity:
Evidence from plan:
Developer impact:
Recommendation:

### Required Plan Changes
- <required change>

### Deferred DX Improvements
- <deferred improvement>

### Implementation Checklist
- [ ] <implementation step>
- [ ] <implementation step>
- [ ] <implementation step>

### Handoff To Implementation
Files/docs likely affected:
Validation after implementation:

Quality Bar

• Keep the review scoped to developer experience, not general architecture.
• Mark missing examples, vague errors, and unclear setup as plan blockers when they affect first success.
• Do not accept "we will document later" for developer-facing changes that require docs to be usable.
• Prefer measurable outcomes: TTHW, steps, commands, pages, error recovery.