devex-review— agent skill

When to invoke

Use when asked to "test the DX", "DX audit", "developer experience test", or "try the onboarding".

Proactively suggest after shipping a developer-facing feature.

Voice triggers (speech-to-text aliases): "dx audit", "test the developer experience", "try the onboarding", "developer experience test".

Preamble

eval "$(~/.vibestack/bin/vibe-slug 2>/dev/null)" 2>/dev/null || SLUG="unknown"
_LEARN_FILE="${VIBESTACK_HOME:-$HOME/.vibestack}/projects/${SLUG:-unknown}/learnings.jsonl"
if [ -f "$_LEARN_FILE" ]; then
  _LEARN_COUNT=$(wc -l < "$_LEARN_FILE" 2>/dev/null | tr -d ' ')
  echo "LEARNINGS: $_LEARN_COUNT entries loaded"
  if [ "$_LEARN_COUNT" -gt 5 ] 2>/dev/null; then
    ~/.vibestack/bin/vibe-learnings-search --limit 5 2>/dev/null || true
  fi
else
  echo "LEARNINGS: none yet"
fi

{{include lib/snippets/session-host.md}}

{{include lib/snippets/decision-brief.md}}

{{include lib/snippets/working-protocols.md}}

{{include lib/snippets/state-protocols.md}}

Step 0: Detect platform and base branch

First, detect the git hosting platform from the remote URL:

git remote get-url origin 2>/dev/null

• If the URL contains "github.com" → platform is GitHub
• If the URL contains "gitlab" → platform is GitLab
• Otherwise, check CLI availability:
• gh auth status 2>/dev/null succeeds → platform is GitHub (covers GitHub Enterprise)
• glab auth status 2>/dev/null succeeds → platform is GitLab (covers self-hosted)
• Neither → unknown (use git-native commands only)

Determine which branch this PR/MR targets, or the repo's default branch if no PR/MR exists. Use the result as "the base branch" in all subsequent steps.

If GitHub:

1. gh pr view --json baseRefName -q .baseRefName — if succeeds, use it
2. gh repo view --json defaultBranchRef -q .defaultBranchRef.name — if succeeds, use it

If GitLab:

1. glab mr view -F json 2>/dev/null and extract the target_branch field — if succeeds, use it
2. glab repo view -F json 2>/dev/null and extract the default_branch field — if succeeds, use it

Git-native fallback (if unknown platform, or CLI commands fail):

1. git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's|refs/remotes/origin/||'
2. If that fails: git rev-parse --verify origin/main 2>/dev/null → use main
3. If that fails: git rev-parse --verify origin/master 2>/dev/null → use master

If all fail, fall back to main.

Print the detected base branch name. In every subsequent git diff, git log, git fetch, git merge, and PR/MR creation command, substitute the detected branch name wherever the instructions say "the base branch" or <default>.

SETUP

# vibestack does not include a browse daemon.
echo "BROWSE_NOT_AVAILABLE"

If BROWSE_NOT_AVAILABLE: skip all $B commands and use text-only fallbacks (curl, open, direct HTTP checks).

DX First Principles

These are the laws. Every recommendation traces back to one of these.

1. Zero friction at T0. First five minutes decide everything. One click to start. Hello world without reading docs. No credit card. No demo call.
2. Incremental steps. Never force developers to understand the whole system before getting value from one part. Gentle ramp, not cliff.
3. Learn by doing. Playgrounds, sandboxes, copy-paste code that works in context. Reference docs are necessary but never sufficient.
4. Decide for me, let me override. Opinionated defaults are features. Escape hatches are requirements. Strong opinions, loosely held.
5. Fight uncertainty. Developers need: what to do next, whether it worked, how to fix it when it didn't. Every error = problem + cause + fix.
6. Show code in context. Hello world is a lie. Show real auth, real error handling, real deployment. Solve 100% of the problem.
7. Speed is a feature. Iteration speed is everything. Response times, build times, lines of code to accomplish a task, concepts to learn.
8. Create magical moments. What would feel like magic? Stripe's instant API response. Vercel's push-to-deploy. Find yours and make it the first thing developers experience.

The Seven DX Characteristics

Cognitive Patterns — How Great DX Leaders Think

Internalize these; don't enumerate them.

1. Chef-for-chefs — Your users build products for a living. The bar is higher because they notice everything.
2. First five minutes obsession — New dev arrives. Clock starts. Can they hello-world without docs, sales, or credit card?
3. Error message empathy — Every error is pain. Does it identify the problem, explain the cause, show the fix, link to docs?
4. Escape hatch awareness — Every default needs an override. No escape hatch = no trust = no adoption at scale.
5. Journey wholeness — DX is discover → evaluate → install → hello world → integrate → debug → upgrade → scale → migrate. Every gap = a lost dev.
6. Context switching cost — Every time a dev leaves your tool (docs, dashboard, error lookup), you lose them for 10-20 minutes.
7. Upgrade fear — Will this break my production app? Clear changelogs, migration guides, codemods, deprecation warnings. Upgrades should be boring.
8. SDK completeness — If devs write their own HTTP wrapper, you failed. If the SDK works in 4 of 5 languages, the fifth community hates you.
9. Pit of Success — "We want customers to simply fall into winning practices" (Rico Mariani). Make the right thing easy, the wrong thing hard.
10. Progressive disclosure — Simple case is production-ready, not a toy. Complex case uses the same API. SwiftUI: \Button("Save") { save() }\ → full customization, same API.

DX Scoring Rubric (0-10 calibration)

The gap method: For each score, explain what a 10 looks like for THIS product. Then fix toward 10.

TTHW Benchmarks (Time to Hello World)

Hall of Fame Reference

During each review pass, load the relevant section from: \~/.claude/skills/plan-devex-review/dx-hall-of-fame.md\

Read ONLY the section for the current pass (e.g., "## Pass 1" for Getting Started). Do NOT read the entire file at once. This keeps context focused.

Scope Declaration

Browse can test web-accessible surfaces: docs pages, API playgrounds, web dashboards, signup flows, interactive tutorials, error pages.

Browse CANNOT test: CLI install friction, terminal output quality, local environment setup, email verification flows, auth requiring real credentials, offline behavior, build times, IDE integration.

For untestable dimensions, use bash (for CLI --help, README, CHANGELOG) or mark as INFERRED from artifacts. Never guess. State your evidence source for every score.

Step 0: Target Discovery

1. Read CLAUDE.md for project URL, docs URL, CLI install command
2. Read README.md for getting started instructions
3. Read package.json or equivalent for install commands

If URLs are missing, AskUserQuestion: "What's the URL for the docs/product I should test?"

Boomerang Baseline

Check for prior /plan-devex-review scores:

eval "$(~/.vibestack/bin/vibe-slug 2>/dev/null)"
true # vibe-review-read 2>/dev/null | grep plan-devex-review || echo "NO_PRIOR_PLAN_REVIEW"

If prior scores exist, display them. These are your baseline for the boomerang comparison.

Step 1: Getting Started Audit

Navigate to the docs/landing page via browse. Screenshot it.

GETTING STARTED AUDIT
=====================
Step 1: [what dev does]          Time: [est]  Friction: [low/med/high]  Evidence: [screenshot/bash output]
Step 2: [what dev does]          Time: [est]  Friction: [low/med/high]  Evidence: [screenshot/bash output]
...
TOTAL: [N steps, M minutes]

Score 0-10. Load "## Pass 1" from dx-hall-of-fame.md for calibration.

Step 2: API/CLI/SDK Ergonomics Audit

Test what you can:

• CLI: Run --help via bash. Evaluate output quality, flag design, discoverability.
• API playground: Navigate via browse if one exists. Screenshot.
• Naming: Check consistency across the API surface.

Score 0-10. Load "## Pass 2" from dx-hall-of-fame.md for calibration.

Step 3: Error Message Audit

Trigger common error scenarios:

• Browse: Navigate to 404 pages, submit invalid forms, try unauthenticated access
• CLI: Run with missing args, invalid flags, bad input

Screenshot each error. Score against the Elm/Rust/Stripe three-tier model.

Score 0-10. Load "## Pass 3" from dx-hall-of-fame.md for calibration.

Step 4: Documentation Audit

Navigate the docs structure via browse:

• Check search functionality (try 3 common queries)
• Verify code examples are copy-paste-complete
• Check language switcher behavior
• Check information architecture (can you find what you need in <2 min?)

Screenshot key findings. Score 0-10. Load "## Pass 4" from dx-hall-of-fame.md.

Step 5: Upgrade Path Audit

Read via bash:

• CHANGELOG quality (clear? user-facing? migration notes?)
• Migration guides (exist? step-by-step?)
• Deprecation warnings in code (grep for deprecated/obsolete)

Score 0-10. Evidence: INFERRED from files. Load "## Pass 5" from dx-hall-of-fame.md.

Step 6: Developer Environment Audit

Read via bash:

• README setup instructions (steps? prerequisites? platform coverage?)
• CI/CD configuration (exists? documented?)
• TypeScript types (if applicable)
• Test utilities / fixtures

Score 0-10. Evidence: INFERRED from files. Load "## Pass 6" from dx-hall-of-fame.md.

Step 7: Community & Ecosystem Audit

Browse:

• Community links (GitHub Discussions, Discord, Stack Overflow)
• GitHub issues (response time, templates, labels)
• Contributing guide

Score 0-10. Evidence: TESTED where web-accessible, INFERRED otherwise.

Step 8: DX Measurement Audit

Check for feedback mechanisms:

• Bug report templates
• NPS or feedback widgets
• Analytics on docs

Score 0-10. Evidence: INFERRED from files/pages.

DX Scorecard with Evidence

+====================================================================+
|              DX LIVE AUDIT — SCORECARD                              |
+====================================================================+
| Dimension            | Score  | Evidence | Method   |
|----------------------|--------|----------|----------|
| Getting Started      | __/10  | [screenshots] | TESTED   |
| API/CLI/SDK          | __/10  | [screenshots] | PARTIAL  |
| Error Messages       | __/10  | [screenshots] | PARTIAL  |
| Documentation        | __/10  | [screenshots] | TESTED   |
| Upgrade Path         | __/10  | [file refs]   | INFERRED |
| Dev Environment      | __/10  | [file refs]   | INFERRED |
| Community            | __/10  | [screenshots] | TESTED   |
| DX Measurement       | __/10  | [file refs]   | INFERRED |
+--------------------------------------------------------------------+
| TTHW (measured)      | __ min | [step count]  | TESTED   |
| Overall DX           | __/10  |               |          |
+====================================================================+

Boomerang Comparison

If /plan-devex-review scores exist from the baseline check:

PLAN vs REALITY
================
| Dimension        | Plan Score | Live Score | Delta | Alert |
|------------------|-----------|-----------|-------|-------|
| Getting Started  | __/10     | __/10     | __    | ⚠/✓   |
| API/CLI/SDK      | __/10     | __/10     | __    | ⚠/✓   |
| Error Messages   | __/10     | __/10     | __    | ⚠/✓   |
| Documentation    | __/10     | __/10     | __    | ⚠/✓   |
| Upgrade Path     | __/10     | __/10     | __    | ⚠/✓   |
| Dev Environment  | __/10     | __/10     | __    | ⚠/✓   |
| Community        | __/10     | __/10     | __    | ⚠/✓   |
| DX Measurement   | __/10     | __/10     | __    | ⚠/✓   |
| TTHW             | __ min    | __ min    | __ min| ⚠/✓   |

Flag any dimension where live score < plan score - 2 (reality fell short of plan).

Review Log

PLAN MODE EXCEPTION — ALWAYS RUN:

true # vibe-review-log '{"skill":"devex-review","timestamp":"TIMESTAMP","status":"STATUS","overall_score":N,"product_type":"TYPE","tthw_measured":"TTHW","dimensions_tested":N,"dimensions_inferred":N,"boomerang":"YES_OR_NO","commit":"COMMIT"}'

{{include lib/snippets/review-readiness-dashboard.md}}

Plan File Review Report

After displaying the Review Readiness Dashboard in conversation output, also update the plan file itself so review status is visible to anyone reading the plan.

Detect the plan file

1. Check if there is an active plan file in this conversation (the host provides plan file

paths in system messages — look for plan file references in the conversation context).

1. If not found, skip this section silently — not every review runs in plan mode.

Generate the report

Read the review log output you already have from the Review Readiness Dashboard step above. Parse each JSONL entry. Each skill logs different fields:

• plan-ceo-review: \status\, \unresolved\, \critical_gaps\, \mode\, \scope_proposed\, \scope_accepted\, \scope_deferred\, \commit\

→ Findings: "{scope_proposed} proposals, {scope_accepted} accepted, {scope_deferred} deferred" → If scope fields are 0 or missing (HOLD/REDUCTION mode): "mode: {mode}, {critical_gaps} critical gaps"

• plan-eng-review: \status\, \unresolved\, \critical_gaps\, \issues_found\, \mode\, \commit\

→ Findings: "{issues_found} issues, {critical_gaps} critical gaps"

• plan-design-review: \status\, \initial_score\, \overall_score\, \unresolved\, \decisions_made\, \commit\

→ Findings: "score: {initial_score}/10 → {overall_score}/10, {decisions_made} decisions"

• plan-devex-review: \status\, \initial_score\, \overall_score\, \product_type\, \tthw_current\, \tthw_target\, \mode\, \persona\, \competitive_tier\, \unresolved\, \commit\

→ Findings: "score: {initial_score}/10 → {overall_score}/10, TTHW: {tthw_current} → {tthw_target}"

• devex-review: \status\, \overall_score\, \product_type\, \tthw_measured\, \dimensions_tested\, \dimensions_inferred\, \boomerang\, \commit\

→ Findings: "score: {overall_score}/10, TTHW: {tthw_measured}, {dimensions_tested} tested/{dimensions_inferred} inferred"

• codex-review: \status\, \gate\, \findings\, \findings_fixed\

→ Findings: "{findings} findings, {findings_fixed}/{findings} fixed"

All fields needed for the Findings column are now present in the JSONL entries. For the review you just completed, you may use richer details from your own Completion Summary. For prior reviews, use the JSONL fields directly — they contain all required data.

Produce this markdown table:

\\\`markdown

VIBESTACK REVIEW REPORT

\\\`

Below the table, add these lines:

• VERDICT: (always present, first) list reviews that are CLEAR (e.g., "CEO + ENG CLEARED — ready to implement").

If Eng Review is not CLEAR and not skipped globally, append "eng review required".

• CODEX: (only if codex-review ran) — one-line summary of codex fixes
• CROSS-MODEL: (only if both Claude and Codex reviews exist) — overlap analysis

{{include lib/snippets/unresolved-decisions-status.md}}

Write to the plan file

PLAN MODE EXCEPTION — ALWAYS RUN: This writes to the plan file, which is the one file you are allowed to edit in plan mode. The plan file review report is part of the plan's living status.

• Search the plan file for a \## VIBESTACK REVIEW REPORT\ section anywhere in the file

(not just at the end — content may have been added after it).

• If found, replace it entirely using the Edit tool. Match from \## VIBESTACK REVIEW REPORT\

through either the next \## \ heading or end of file, whichever comes first. This ensures content added after the report section is preserved, not eaten. If the Edit fails (e.g., concurrent edit changed the content), re-read the plan file and retry once.

• If no such section exists, append it to the end of the plan file.
• Always place it as the very last section in the plan file. If it was found mid-file,

move it: delete the old location and append at the end.

{{include lib/snippets/capture-learnings.md}}

Next Steps

After the audit, recommend:

• Fix the gaps found (specific, actionable fixes)
• Re-run /devex-review after fixes to verify improvement
• If boomerang showed significant gaps, re-run /plan-devex-review on the next feature plan

Formatting Rules

• NUMBER issues (1, 2, 3...) and LETTERS for options (A, B, C...).
• Rate every dimension with evidence source.
• Screenshots are the gold standard. File references are acceptable. Guesses are not.

{{include lib/snippets/exit-plan-mode-gate.md}}