---
name: audit-devx
description: Use when the user says "audit our dev setup" / "setup time, build time, paper cuts" / "DX audit" — reads README + CONTRIBUTING + Makefile + package.json scripts + docker-compose + .env.example + CI config via the connected code host, estimates setup time from discrete steps, checks CI history for build time, and surfaces the top 5 paper cuts (missing env vars, flaky scripts, bad error messages, outdated commands) with suggested fixes. Draft only; never pushes fixes.
---

# Audit DevX

## When to use

- User: "audit our local dev setup" / "DX audit" / "how long does
  setup take" / "what are our paper cuts".
- Natural cadence: quarterly, or after a stack change.

## Steps

1. **Read engineering context.** Open
   `../head-of-engineering/engineering-context.md`. If missing or
   empty, stop and tell the user:
   > "I need the engineering context doc before I can audit DX — it
   > tells me team shape and the quality bar. Run the Head of
   > Engineering's `define-engineering-context` first."

2. **Read config.** `config/doc-audience.md` (DX audits shift in
   emphasis if the audience is "new engineers joining" vs "developers
   building against the API").

3. **Resolve the repo + fetch setup files.** Run `composio search
   code-hosting` and fetch from the default branch:
   - `README.md` (Quickstart / Install section)
   - `CONTRIBUTING.md`
   - `Makefile`
   - `package.json` (scripts section), `pnpm-workspace.yaml`
   - `pyproject.toml`, `requirements.txt`, `poetry.lock`
   - `go.mod`, `go.sum`
   - `Cargo.toml`, `Cargo.lock`
   - `docker-compose.yml`, `Dockerfile`
   - `.env.example` (and note any `.env*.example` variants)
   - `.nvmrc`, `.python-version`, `.tool-versions`
   - CI config: `.github/workflows/*.yml`, `.gitlab-ci.yml`,
     `.circleci/config.yml`, `bitbucket-pipelines.yml`
   - `scripts/`, `bin/` directories (list + read any `setup.sh` /
     `dev.sh`)
   - Note missing files as signals (e.g. no `.env.example` = P0 paper
     cut).

4. **Estimate setup time from discrete steps.** Walk the README's
   Quickstart / Install section (or CONTRIBUTING's "Getting started"
   if richer). For each step, estimate minutes based on:
   - 0.5 min — a single command that's a couple seconds to run.
   - 2 min — a command that downloads / compiles (`npm install`,
     `pip install -r`, `go mod download`).
   - 5 min — a service boot (docker-compose up with a DB pulling
     images for the first time).
   - 10 min — anything that requires external signup or manual
     browser-side work.
   - UNKNOWN — for any step where I can't estimate (e.g. "contact
     the team for credentials").
   Add them up. State the assumption behind each bucket. Flag any
   step that blocks on a human (e.g. "ask for AWS creds") — those
   are P0 paper cuts.

5. **Check build time from CI.** Via `composio search code-hosting`,
   fetch the last 5-10 CI runs on the default branch. Compute:
   - Median total wall-clock time.
   - Slowest job name + its median time.
   - Any job > 10 min on a small-team codebase (P1 flag).
   If CI history isn't accessible, mark UNKNOWN and suggest the user
   share a screenshot or paste logs.

6. **Identify top-5 paper cuts.** Score by how often a new hire or
   returning dev would hit each. Sources to scan:
   - **`.env.example`** — every var documented? Any mentioned in
     README / code but not in `.env.example`? Any `.env.example`
     values that look like they shouldn't be defaults (e.g. real
     API keys)?
   - **README Quickstart** — does every command in it still exist in
     `package.json` / `Makefile`? (Stale commands are a top paper
     cut.)
   - **Scripts / Makefile** — any script that does
     `echo "TODO: implement"` or `exit 1`? Any `make dev` that
     doesn't work without extra setup the README doesn't mention?
   - **Error messages** — any `throw new Error("wat")` or
     `print("nope")` patterns in setup scripts?
   - **Prerequisites** — Node / Python / Rust / Go versions pinned
     in `.tool-versions` vs not? OS / arch assumptions (e.g.
     docker-compose pulling an amd64-only image on an M-series Mac)?
   - **Docs drift** — does CONTRIBUTING.md reference tooling the
     Makefile removed?

   For each paper cut, structure:
   - **What:** one-line description.
   - **Where:** file + line (cite).
   - **Impact:** how often a new dev hits it (P0 blocks setup, P1
     wastes an hour, P2 mildly annoying).
   - **Fix:** concrete diff or change.

7. **Write** to `devx-audits/{YYYY-MM-DD}.md` atomically. Structure:

   ```markdown
   # DevX Audit — {YYYY-MM-DD}

   **Audited:** {ISO date}
   **Repo:** {owner}/{repo} — branch `{default-branch}`

   ---

   ## Metrics

   | Metric | Value | Notes |
   |---|---|---|
   | Setup time (estimated) | **{N} minutes** | {step count + assumption} |
   | Full CI build (median of last 10) | **{M} minutes** | slowest job: `{name}` ({time}) |
   | README → runnable (cold clone) | **{steps}** | {count of discrete commands} |

   ## Setup walk-through

   | Step | Command | Est. time | Source | Notes |
   |---|---|---|---|---|
   | 1 | `git clone ...` | 0.5 min | — | — |
   | 2 | `pnpm install` | 2 min | README L12 | — |
   | 3 | `cp .env.example .env` | 0.5 min | README L15 | 2 vars undocumented (see P0-a) |
   | ... | ... | ... | ... | ... |

   ## Top 5 paper cuts

   ### P0-a — {title}
   - **Where:** `.env.example:8`
   - **Impact:** New dev sees app crash on startup with cryptic
     `TypeError: undefined is not a function` — wastes ~20 min.
   - **Fix:**
     ```diff
     + DATABASE_URL=postgres://localhost:5432/dev
     + REDIS_URL=redis://localhost:6379
     ```

   ### P0-b — {title}
   ...

   ### P1-a — {title}
   ...

   ---

   ## Suggested next moves

   1. Fix P0-a and P0-b this week — unblocks new dev setup.
   2. Address P1-a in the next sprint.
   3. P2 items can wait or be closed as wont-fix.
   ```

8. **Append to `outputs.json`** (`type: "devx-audit"`,
   `title: "DevX audit — {YYYY-MM-DD}"`, `summary: "Setup {N} min,
   CI {M} min, {K} paper cuts (top: {P0-a title})"`,
   `path: "devx-audits/{YYYY-MM-DD}.md"`, `status: "draft"`,
   timestamps). Read-merge-write atomically.

9. **Summarize to user** — one paragraph: setup time, build time,
   the top-3 paper cuts with impact, and the path. End with: "Fix
   what hurts most first. I never push these fixes — diffs are
   suggestions you commit."

## Hard nos

- **Never guess at setup steps.** Every command cited to a real file
  + line. Unverified steps → UNKNOWN.
- Never push fixes directly — suggestions are drafts.
- Never audit without reading `engineering-context.md` first.

## Outputs

- `devx-audits/{YYYY-MM-DD}.md`
- Appends to `outputs.json` with `{ id, type: "devx-audit", title,
  summary, path, status: "draft", createdAt, updatedAt }`.