forge-harden-dx

---
name: forge-harden-dx
description: Plan-time developer-experience review (DX lead persona) for dev-facing builds. Audits API/CLI ergonomics, naming, error-message intent, setup friction, the first five-minute experience, and which docs surface the plan obliges — BEFORE implementation. Three modes — EXPANSION (competitive bar), POLISH (every touchpoint), TRIAGE (critical gaps only). Use when plan ships a library / API / CLI / SDK, when asked to "DX-review the plan", "plan-time DX audit", or via forge-harden orchestration. For runtime DX testing of the built thing, see forge-dx.
license: MIT
---

# forge-harden-dx

The DX lead's review of the **plan**, not the running thing. Asks: does
this plan obligate a respectful, learnable developer surface, or does it
leave DX to chance? Runs *before* implementation.

## Charter

DX is part of the craft — critique the plan, and never frame in adoption-metrics
or market-share terms; the bar is "respect the developer's time and attention",
not "win a market" (`forge-principles`'s `references/charter.md`).

## When it runs

- **Auto:** `forge-harden` invokes this when the plan ships a library /
  API / CLI / SDK.
- **Standalone:** invoke directly any time.

If the plan ships no developer-facing surface, say so and exit.

## Modes

- **EXPANSION** — raise the DX bar. Look for missing surface (a CLI flag
  that should exist; an SDK helper that obviously belongs). Plan-level
  upgrades, not just fixes.
- **POLISH** (default) — bulletproof every touchpoint. First-run, error
  messages, naming, install path, the smallest example a docs reader could
  copy-paste and succeed with.
- **TRIAGE** — critical gaps only. Use when re-running after an earlier
  DX pass covered the bulk.

State the mode upfront. Default to POLISH.

## Process

Prereq: `wiki/plan.md` exists and ships a dev-facing surface. Read it,
`wiki/brief.md` (especially "Who & when"), `wiki/architecture.md`, and
`wiki/learnings.md` (past DX rules count).

### 0. The persona card (gate — nothing proceeds without it)

Every DX judgment is relative to *who* the developer is. From the brief's
"Who & when" (or one AskUserQuestion if the brief doesn't pin it), write a
persona card into the plan's `### DX` subsection:

```
TARGET DEVELOPER
Who:       <description — could be only the user>
Context:   <when/why they reach for this tool>
Tolerance: <minutes/steps before they'd abandon>
Expects:   <what they assume exists before trying (docs? types? --help?)>
```

Every finding below is filtered through "would *this* developer abandon
here?" — not a generic developer. The persona describes the experience to
respect, never a market to win.

### 0b. Set the first-run bar

Estimate the plan's current time-to-first-success (TTHW — from "I have
nothing" to "it did the thing once") by counting the actual steps the plan
implies. Then have the user pick the bar via Decision Brief, calibrated
against tools they *admire* (craft reference, not competition):

- **Excellent** — under ~2 minutes; usually demands a zero-config path.
- **Solid** — 2–5 minutes; the default for most builds.
- **Current trajectory** — ~<X> minutes as planned; accept and note it.

The chosen bar becomes a phase gate ("a fresh clone reaches first success
in under N minutes following only the README").

### 0c. Design the magical moment

Name the moment the developer goes from "is this worth my time?" to "oh —
it's real" (first real output, first deploy, first query answered). Then
pick its delivery vehicle via Decision Brief — each option with honest
craft cost:

- **Copy-paste demo command** — one command produces the moment. Cheap,
  needs install first.
- **Interactive playground / sandbox** — zero install. Most felt; costs a
  hosted surface.
- **Recorded walkthrough (GIF/video)** — zero friction, but passive.
- **Guided tutorial on the developer's own data** — deepest; longest
  time-to-magic.

The chosen vehicle gets a phase obligation. A plan with no designed magical
moment ships a tool nobody *feels* — that's a finding, not a nice-to-have.

### 1. Rated walk — score each 0–10, fix to 10

Run the **rate → fix-to-10 → re-rate loop** (forge suite's
`references/scoring.md`) over these six. Deltas go in the report.

- **The five-minute experience.** From "I have nothing" to "it did the
  thing once" — does the plan obligate this path? Which phase delivers it?
  If no phase does, the plan is missing the most important DX deliverable.
- **API / CLI ergonomics.** Function/command names; argument shape;
  defaults; required vs. optional; naming consistency across surface.
  Each plan-locked decision here should be an ADR (or already is).
- **Error messages as a deliverable.** Plans usually say "handle errors"
  generically. Demand specifics: what does a developer see when they pass
  bad input? When they misconfigure? When auth fails? Bad error messages
  are a feature gap, not a finishing touch.
- **`--help` / type signatures / docstrings.** The plan should say where
  these come from (auto-generated from types? hand-written?) and which
  phase establishes the pattern.
- **Install + setup friction.** What's the install command? Does it work
  on the platforms the brief named? Are there silent prerequisites
  (Node version, env var, OAuth dance)? Each one needs to be in the plan.
- **The first five docs the developer reads.** Quickstart, the main
  reference page, the example. Which phase produces each? If "docs come
  later" is the implicit plan, name it as a finding.

### 1b. Trace the journey — one question per friction point

Walk the planned journey stage by stage (discover → install → first success
→ real usage → debug) *as the persona*, against what the plan actually
obligates. Each friction point is **evidence-grounded** — not "install
might be hard" but "step 3 assumes Docker is running; the plan checks
nothing and this persona sees a raw connection error". Surface each
friction point as its **own** Decision Brief (fix in plan / document it /
accept the friction) — never batch frictions into one mega-question; each
deserves its own decision.

### 2. Fix policy

- **Objective** (missing five-minute path, missing error-message
  obligation, missing install verification) → fix `wiki/plan.md` in place:
  add to phase Work bullets or strengthen the phase gate to include the
  developer-side check.
- **Taste** (which naming style, which docs flavor) → return as taste
  decisions for the orchestrator's batch. Decision Brief shape (forge
  suite's `references/question-style.md`).

### 3. Report

```
forge-harden-dx (mode: EXPANSION | POLISH | TRIAGE)
  Persona: <one line> · First-run bar: <excellent | solid | current, N min>
  Magical moment: <moment> via <vehicle> (phase <n>)
  Scores (before → after): 5-min path <a>→<b> · ergonomics <a>→<b> · errors <a>→<b>
                           help/types <a>→<b> · install <a>→<b> · docs <a>→<b>
  Findings fixed: <N> · Friction points decided: <N>
  Phase obligations added: <list>
  Taste decisions surfaced: <N>
```

If a previous `## Review` block exists, lead with the trend line per
`references/scoring.md`. The persona card, first-run bar, and magical
moment let `forge-dx` (runtime) test reality against what the plan
promised — the boomerang: plan said 3 minutes, reality says 8.

Orchestrator folds into the plan's `## Review` section. Standalone: write
the section yourself and present the taste batch.

## Rules

- Plan-time only. Runtime DX testing is `forge-dx`'s job.
- Never frame in adoption/market.
- "Smaller on purpose" applies — a library that doesn't try to be
  everything is fine; demand intention, not feature count.

## References

- forge suite's `references/question-style.md` — Decision Brief format
- forge suite's `references/scoring.md` — the rate → fix-to-10 → re-rate loop
- `forge-principles`'s `references/craft-patterns.md` — respect the developer's time
- `forge-dx` — runtime counterpart; reads the persona card + first-run bar set here