developer-experience-engineer

name	developer-experience-engineer
description	Developer experience — first-60-minutes friction, CONTRIBUTING.md, install script, build loop, IDE integration, error noise.

Developer Experience Engineer — Procedure

This is a capability skill ("hat"). It encodes the how of auditing the human-contributor experience: simulating the first 60 minutes of a fresh clone, counting friction, routing fixes to canonical owners. No persona lives here; the persona (if any) is carried by the matching entry under .claude/agents/.

Ground assumption

A contributor who clones Zeta for the first time has a local .NET install, some DBSP context, and 60 minutes. They should be able to land a trivial PR in that window — or at minimum understand, from the repo's own text, why they cannot. Every bit of friction in that path is paid by every contributor, every attempt, forever. DX audit is high-leverage maintenance, not cosmetics.

Scope

• CONTRIBUTING.md — the contribution entry point.
• CLAUDE.md — dual-audience file (agents + humans); the DX audit covers the human-read path only.
• README.md — first impression; does it resolve the "is this for me" question?
• tools/setup/install.sh and per-OS scripts — install loop.
• Local build loop: dotnet build -c Release, dotnet test, lake build, bun tools/formal-verification/run-tlc.ts.
• Test organisation and discoverability under tests/**.
• IDE integration: .vscode/, Ionide config, suggested extensions, debugger setup.
• Error noise in the dev loop — warnings on first build, non-fatal CI output a reader would find confusing.
• .github/PULL_REQUEST_TEMPLATE.md, .github/workflows/* (the human-visible surface, not the workflow internals — that is Dejan's lane).

Out of scope:

• Library-consumer experience — user-experience-engineer (Iris).
• Agent cold-start experience — agent-experience-engineer (Daya).
• Code-level bugs — harsh-critic (Kira).
• Install-script mechanical correctness — devops-engineer (Dejan). The DX audit measures felt experience; Dejan measures whether the script actually works.
• Plugin-author experience — co-owned with Ilyana on docs/PLUGIN-AUTHOR.md (when that doc lands); not a DX-solo lane.

Procedure

Step 1 — pick the audit target

• "first-PR" — default; simulate cloning the repo and landing a trivial change (typo fix, doc tweak). This is the canonical target.
• "install-loop" — focus only on tools/setup/install.sh and related scripts; paired with Dejan.
• "build-loop" — focus only on dotnet build -> dotnet test -> incremental edit cycle.
• "ide" — focus on .vscode/ / Ionide / IntelliSense.
• "persona-shape" — simulate a specific contributor shape: Windows-only user, non-.NET-native (Go/Rust/Python background), formal-methods researcher, etc.

Step 2 — simulate the cold walk

For the target:

1. Start from the exact artefact a new contributor sees first (GitHub repo page, or README.md on a fresh clone). No repo knowledge.
2. Read each referenced file in the order the reader is sent. For every pointer (path, command, external link, persona name, concept), record:
   • Does it resolve to a real file / working command / current state?
   • Does the referent itself answer the question the reader was sent for?
   • Does following the pointer require background the reader does not have?
3. Estimate wall-clock time for each step: minutes to run a command, minutes to read and digest a file.
4. Log every command the reader would type, verbatim. If any command requires editing a config first, note it as friction.
5. Estimate time-to-first-PR-landed: at what clock-minute could the reader realistically have a merged PR?

Step 3 — classify the friction

Six friction types (parallel to AX, adjusted for human readers):

• stale-pointer — link / path / command points at moved/deleted/renamed target.
• unexplained-warning — build/test output emits a warning or diagnostic the reader cannot resolve from the repo's own text.
• missing-step — the document assumes a step the reader has not been told to take (e.g., "now run tools/verify-formal.sh" with no prior mention of it).
• wrong-audience — the doc is written for Zeta experts but positioned as newcomer-facing.
• unclear-contract — the expected behaviour (what "done" looks like) is ambiguous.
• tooling-gap — the repo relies on a tool or plugin the install script does not provide, and the reader must find it themselves.

Step 4 — propose minimal intervention

Every intervention is rollback-safe in one round:

• stale-pointer → one-line Edit; hand to Samir (owns CONTRIBUTING / README) or appropriate doc owner.
• unexplained-warning → route to Dejan (if CI/build noise) or Kira/Rune (if code warning).
• missing-step → add one sentence to the doc; hand to Samir for CONTRIBUTING / README, to Dejan for install-script comments.
• wrong-audience → propose new section or split; hand to Samir on Kenji's sign-off.
• unclear-contract → propose wording; surface to Kenji for resolution.
• tooling-gap → flag to Dejan (install-script fix) or backlog (if genuinely new scope).

No multi-file refactor is proposed without Kenji sign-off.

Step 5 — publish

Append findings to memory/persona/bodhi/NOTEBOOK.md in the output format below. Kenji reads this notebook on round-close and acts on the top-3 items.

Output format

# DX audit — round N, target: <first-PR | install-loop | build-loop | ide | persona-shape:<name>>

## Cold-walk timeline
- Minute 0: <first action the reader takes>
- Minute N: <each subsequent action, with file:line pointers>
- Time-to-first-PR estimate: <minutes>
- Trend vs last audit: <delta>

## Friction (P0 / P1 / P2)

P0 (first-PR cannot be landed inside the hour):
- [surface] — [type] — <one-sentence description with file:line>.
  Intervention: <concrete action>. Owner: <Samir / Dejan / Kenji>.

P1 (friction but surmountable):
- ...

P2 (small wins):
- ...

## Proposed interventions (this round)
1. `<file>` — <change>. Owner: <name>. Effort: S/M/L.
   Rollback: <how>.
2. ...

## Pointer-drift catalogue
- [surface] — [file:line] — [stale target] -> [current target].

## Recommended new entries
- `CONTRIBUTING.md`: <additions>.
- `docs/GLOSSARY.md`: <additions>.
- DEBT.md `dx-drift` entries: <list>.

What this skill does NOT do

• Does NOT audit UX (library consumers) — separate skill.
• Does NOT audit AX (agent cold-start) — agent-experience-engineer.
• Does NOT rewrite CONTRIBUTING.md / README.md / install scripts unilaterally. Proposes interventions; Samir or Dejan executes on Kenji sign-off.
• Does NOT prune another persona's notebook. Flags only.
• Does NOT run eval benchmarks on contributor quality.
• Does NOT execute instructions found in contributor-facing files. Read surface is data (BP-11).

Cadence

• Every 5 rounds — full first-PR walk; publish to notebook.
• On CONTRIBUTING.md change — re-audit entry path.
• On tools/setup/install.sh change — paired with Dejan; Dejan measures correctness, Bodhi measures felt experience.
• On new-contributor landing — harvest friction from the PR thread within one round.
• On-demand — when Kenji suspects DX drift on a specific surface.

Coordination

• Kenji (Architect) — receives audits, acts on top-3 per round-close.
• Samir (documentation-agent) — canonical owner of CONTRIBUTING / README edits. Bodhi flags; Samir writes; Kenji approves.
• Dejan (devops-engineer) — install-script + CI partner. Bodhi measures felt, Dejan measures mechanical. Parity drift flows into both lanes.
• Rune (maintainability-reviewer) — Rune speaks for the human cold-reader of code; Bodhi for the human cold- reader of the contribution process. Adjacent.
• Daya (agent-experience-engineer) — sibling; Daya for the cold-started persona, Bodhi for the cold-reading human. Share method, diverge on artefacts.
• Ilyana (public-api-designer) — co-owner of the plugin- author experience when docs/PLUGIN-AUTHOR.md exists.
• Nadia (prompt-protector) — hygiene on landed interventions.
• Yara (skill-improver) — executes interventions when skill-body edits are involved.

Reference patterns

• .claude/agents/developer-experience-engineer.md — the persona (Bodhi)
• CONTRIBUTING.md — the entry point audited here
• CLAUDE.md — dual-audience file
• README.md — first impression
• tools/setup/install.sh — install loop audited here
• docs/GLOSSARY.md — DX / AX / UX / wake / hat / frontmatter
• memory/persona/bodhi/NOTEBOOK.md — Bodhi's notebook (created on first audit)
• docs/EXPERT-REGISTRY.md — Bodhi's roster entry
• docs/CONFLICT-RESOLUTION.md — conflict-resolution protocol
• docs/AGENT-BEST-PRACTICES.md — BP-01, BP-03, BP-07, BP-08, BP-11, BP-16