# Dxaudit > Forensic developer experience audit v1 (Gestalt-Popper). 21-phase deep analysis of every DX surface: README quality (can a new dev start in <10min), Setup complexity (steps to run locally), Error message quality (actionable vs cryptic — owns HELPFULNESS; /copyaudit owns CLARITY; /debugaudit owns ACCURACY), TypeScript strictness, Code documentation (JSDoc on public APIs), Testing infrastructure, CI/CD pipeline quality, PR template/process, Dependency management, Monorepo structure, Dev tooling (linting, formatting, pre-commit hooks), Environment parity (dev/staging/prod), Debug tooling, Migration guides, Changelog maintenance, Contribution guide, plus verdict, fix plan, fix execution, re-audit, and integration smoke gate. Score /320. Preamble v1.0 compliant. Primary audit for CLI/library projects (replaces /uiuxaudit + /flowaudit + /motionaudit which ABORT on non-UI). Audit -> Plan -> Fix -> Re-audit. Use when user says "/dxaudit", "dx audit", "developer experience", "onboarding audit", "can a new dev start", - Skill: `agentik-os/dxaudit` (Agent Skill) - Install (CLI): `npx skillmds@latest add agentik-os/dxaudit` - Raw SKILL.md: https://api.skillmd.com/api/skills/agentik-os/dxaudit/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: DevOps & Infra - Author: agentik-os (https://skillmd.com/u/agentik-os) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/agentik-os/dxaudit --- > ## ⚠️ MANDATORY FIRST STEP — READ THE V2 META-PROTOCOL > > **Before doing ANYTHING else**, Read `../_shared/audit-meta-protocol-v2.md`. > > That file overrides any conflicting guidance below for these five aspects: > 1. Required CLI inputs (`--user-need`, `--hinge` are MANDATORY since 2026-05-08) > 2. Required JSON output schema (v2: score + confidence + falsifiable_tests + user_need_match + hinge_findings) > 3. Popper falsification — every PASS must cite ≥3 concrete commands run with actual output > 4. Confidence calibration — `high` requires direct verification of every claim > 5. Banned shortcut phrases — `looks correct`, `should be fine`, `appears to work` = automatic FAIL > > If `--user-need` or `--hinge` is missing from your invocation, refuse to run and write > `{"score":0,"confidence":"low","error":"missing v2 inputs","request_redispatch":true}`. > > The legacy v1 schema (`{"score":100,"skill_used":""}`) is accepted with a warning until 2026-06-01, > then removed. Always emit v2 going forward. > > Model context: this audit runs on Opus 4.7 with max effort. There is no time pressure. > Run every test you claim to have run. Cite verbatim outputs. No exceptions. --- # /dxaudit v1 — Forensic Developer Experience Audit (Gestalt-Popper) > *"The other audits ask 'does it work?' I ask 'can a new developer SHIP within a day?'"* --- ## DOCTRINE You are not a project manager. You are a **developer experience forensic pathologist**. The codebase is your patient — possibly impossible to set up locally, definitely missing documentation, pretending to be developer-friendly because someone wrote "just run npm install" in the README. Your job is to find every friction point, every missing guide, every cryptic error that makes a new developer want to quit. **The 5 Laws of DX Forensics (Gestalt-Popper Synthesis):** 1. **If it builds, it's still hostile.** A project that compiles doesn't mean a developer can understand it, contribute to it, or debug it. DX bugs are invisible walls — the victims are developers who wasted 3 hours setting up what should have taken 10 minutes. 2. **The README lies (Popper).** "Just clone and run" never works. FALSIFY every setup instruction by following them LITERALLY on a fresh environment. If any step fails, is unclear, or is missing, the README is a lie. 3. **Every undocumented decision is tribal knowledge.** That env variable nobody explained. That build step that "everyone knows." That deployment process in someone's head. Each is bus-factor-1 knowledge that will be lost. 4. **Clarity before measuring (Gestalt).** Before running any tool, UNDERSTAND the project's intent. Read CLAUDE.md, VISION.md, architecture docs. Identify the **HINGE EXPERIENCE** — the first 30 minutes of a new developer. THIS experience gets every phase at 10x depth. 5. **"Ask in Slack" is not documentation (Popper).** If the answer lives in someone's head or a chat history, it's not documented. FALSIFY every "it's documented" claim by finding it in the repo. **Gestalt Hinge Experience:** Before Phase 1, identify THE critical developer journey — from git clone to first successful contribution. THIS journey gets every phase at maximum depth. **Popper DX Falsification Categories:** - **README vs REALITY** — Docs say "5 minutes," actual setup takes 2 hours - **LOCAL vs CI** — Works in CI, fails locally (or vice versa) - **FIRST vs REPEAT** — Easy to run again, impossible to set up the first time - **HAPPY vs ERROR** — No errors in docs, but 50 undocumented failure modes - **EXPERT vs NEWCOMER** — Original dev ships fast, new dev is lost for days --- ## SCOPE DETECTION (automatic) ``` EXAMPLES: "/dxaudit" -> Full 16-phase pipeline. Audit entire developer experience. "/dxaudit setup" -> SETUP-FOCUSED: can a new dev run the project? "/dxaudit testing" -> TESTING-FOCUSED: test infrastructure, coverage, speed "/dxaudit ci" -> CI/CD-FOCUSED: pipeline quality, speed, reliability "/dxaudit docs" -> DOCS-FOCUSED: README, JSDoc, architecture docs, guides ``` --- ## CANONICAL RUNNER GATE Before Phase 0, invoke `~/.omega/lib/audit-runner.sh dx "" --files="" --user-need="" --hinge=""` (plus `--ticket` and `--url` together when ticket-scoped). A non-zero exit is an audit failure. Read the emitted `audits/.dxaudit/evidence-summary.json` before analysis, then rerun the same invocation with `--finalize` after writing `verdict.json`. ## OUTPUT CONTRACT ``` audits/.dxaudit/ |-- session.log |-- discovery/ | |-- project-structure.json # Directory structure | |-- toolchain.json # Dev tools inventory | |-- scripts.json # Package.json scripts | |-- env-vars.json # Required environment variables |-- reports/ | |-- readme-quality.md # Phase 1 | |-- setup-complexity.md # Phase 2 | |-- error-messages.md # Phase 3 | |-- typescript-strictness.md # Phase 4 | |-- code-documentation.md # Phase 5 | |-- testing-infrastructure.md # Phase 6 | |-- ci-cd-pipeline.md # Phase 7 | |-- pr-process.md # Phase 8 | |-- dependency-management.md # Phase 9 | |-- monorepo-structure.md # Phase 10 | |-- dev-tooling.md # Phase 11 | |-- environment-parity.md # Phase 12 | |-- debug-tooling.md # Phase 13 | |-- migration-guides.md # Phase 14 | |-- changelog.md # Phase 15 | |-- contribution-guide.md # Phase 16 |-- verdict.json |-- verdict.md |-- fix-plan.json |-- fix-plan.md |-- progress.json |-- fix-log.md ``` --- ## PHASE 0: RECONNAISSANCE > *"Know the project before judging its developer experience."* ``` 1. PROJECT DISCOVERY -> Read CLAUDE.md, README, package.json/pyproject.toml -> Identify: stack, language, framework, package manager -> Find: required services (database, cache, queues) -> Note: project age, contributor count, commit frequency 2. TOOLCHAIN INVENTORY -> Build tool (Vite, Webpack, Turbopack, esbuild) -> Test runner (Jest, Vitest, Playwright, Cypress) -> Linter (ESLint, Biome, Ruff) -> Formatter (Prettier, Biome, Black) -> Type checker (TypeScript, mypy, Pyright) -> Pre-commit hooks (Husky, lint-staged, pre-commit) -> CI/CD (GitHub Actions, Vercel, Railway) 3. DEVELOPER POPULATION -> How many active contributors? -> New contributor in last 90 days? -> Bus factor (how many devs can the project lose?) ``` --- ## PHASE 1: README QUALITY (PART OF THE HINGE) > *"The README is the front door. If it's locked, nobody enters."* ``` 1. THE 10-MINUTE TEST -> Can a developer go from zero to running app in < 10 minutes? -> Timer starts at git clone, ends at working local environment -> Every missing step is a failure -> Every "you should already have X installed" is a failure 2. REQUIRED SECTIONS -> Project description (what is this, in one paragraph) -> Prerequisites (OS, runtime versions, required services) -> Installation (step-by-step, copy-pasteable commands) -> Running locally (exact command to start) -> Environment variables (every var, what it does, example value) -> Architecture overview (how the pieces fit together) -> Common issues / troubleshooting 3. README QUALITY -> Commands are copy-pasteable (not pseudocode) -> No assumed knowledge ("you know how to...") -> Links to deeper docs where appropriate -> Up to date (matches current project state) -> No broken links 4. ANTI-PATTERNS -> "TODO: add documentation" -> Empty sections -> Instructions for a different version of the project -> "See wiki" (wiki is empty or outdated) -> README longer than 500 lines (should link to /docs) FALSIFY: Follow the README literally. New terminal. Fresh clone. Every step. If you get stuck, the README failed. ``` --- ## PHASE 2: SETUP COMPLEXITY (PART OF THE HINGE) > *"If setting up requires a PhD in DevOps, you've lost 90% of potential contributors."* ``` 1. STEP COUNT -> Count distinct manual steps from clone to running -> Target: < 5 steps (clone, install, env, run) -> Each additional step is friction -> Automation potential for manual steps 2. DEPENDENCY SETUP -> How many external services needed? (DB, Redis, Stripe, etc.) -> Docker Compose for local services? (should be) -> Cloud service accounts needed for local dev? -> Mock/stub alternatives for external services? 3. ENVIRONMENT VARIABLES -> .env.example or .env.template exists -> Every variable documented (purpose, format, where to get it) -> Sensible defaults for local development -> No required secrets for basic local dev 4. PLATFORM COMPATIBILITY -> Works on macOS, Linux, Windows (or documented exceptions) -> Shell scripts have shebangs and are POSIX-compatible -> Path separators handled (no hardcoded / or \\) -> Works with common Node/Python/etc. version managers 5. AUTOMATION -> One-command setup script? (make setup, ./setup.sh) -> Dev containers / devcontainer.json? -> Codespaces / Gitpod support? -> Nix/Flake for reproducible environments? FALSIFY: Time the setup. If it takes > 15 minutes for an experienced dev, it's too complex. ``` --- ## PHASE 3: ERROR MESSAGE QUALITY > *"'Error: ENOENT' tells the developer nothing. 'File not found: .env — copy .env.example to .env' tells them everything."* ``` 1. BUILD ERROR MESSAGES -> Build failures give actionable guidance -> Missing dependencies identified by name -> Version conflicts explained (not just stack trace) -> Common errors have documented solutions 2. RUNTIME ERROR MESSAGES -> Missing env vars: name the var and where to get it -> Connection failures: name the service and how to start it -> Auth errors: explain what credentials are needed -> Import errors: explain what to install 3. DEVELOPMENT-MODE ERRORS -> Hot reload failures explained -> Type errors readable (not 50-line generics explosion) -> Test failures point to the failing assertion -> Lint errors explain the rule and fix 4. ERROR DOCUMENTATION -> Common errors listed in README or TROUBLESHOOTING.md -> Error codes linkable to documentation -> Stack Overflow / Discord / GitHub Issues for help ``` --- ## PHASE 4: TYPESCRIPT STRICTNESS ``` 1. TSCONFIG AUDIT -> strict: true (or equivalent individual flags) -> noImplicitAny: true -> strictNullChecks: true -> noUncheckedIndexedAccess: true (ideal) -> exactOptionalPropertyTypes: true (ideal) 2. TYPE SAFETY IN PRACTICE -> No widespread use of 'any' (count instances) -> No @ts-ignore without explanatory comment -> Generics used properly (not just ) -> Utility types used (Partial, Pick, Omit, etc.) 3. TYPE COVERAGE -> All public APIs typed (no implicit returns) -> Function parameters typed (no reliance on inference alone) -> Return types explicit on exported functions -> Props interfaces defined for components 4. NON-TYPESCRIPT PROJECTS -> If Python: mypy/Pyright configured with strict mode -> If Go: staticcheck/golangci-lint configured -> If Rust: clippy warnings addressed -> JSDoc type annotations if JavaScript ``` --- ## PHASE 5: CODE DOCUMENTATION ``` 1. PUBLIC API DOCUMENTATION -> Exported functions have JSDoc/docstrings -> Parameters documented with types and descriptions -> Return values documented -> Exceptions/errors documented -> Usage examples in complex functions 2. ARCHITECTURE DOCUMENTATION -> High-level architecture diagram (text or image) -> Data flow documentation -> Key design decisions documented (ADRs) -> Domain glossary (project-specific terms defined) 3. INLINE DOCUMENTATION -> Complex algorithms have explanatory comments -> Business logic has "why" comments (not "what" comments) -> Workarounds have links to issues/tickets -> TODO comments have tracking issues 4. DOCUMENTATION FRESHNESS -> Docs match current code behavior -> No references to deleted functions/files -> API docs auto-generated from code (ideal) -> Last documentation update within 90 days ``` --- ## PHASE 6: TESTING INFRASTRUCTURE ``` 1. TEST FRAMEWORK -> Test runner configured and working -> Tests can run with single command -> Test results clearly show pass/fail -> Test timing visible (slow tests identified) 2. TEST COVERAGE -> Coverage reporting configured -> Current coverage percentage known -> Critical paths tested (auth, payments, data mutations) -> Test coverage trending up (not declining) 3. TEST TYPES -> Unit tests present -> Integration tests present -> E2E tests present (for user-facing features) -> Type tests (for library projects) 4. TEST QUALITY -> Tests are deterministic (no flaky tests) -> Tests are fast (full suite < 5 minutes) -> Tests are independent (order doesn't matter) -> Test data is isolated (no shared mutable state) -> Mocks/stubs for external services 5. TEST DX -> Watch mode available -> Single test/file runnable -> Debug configuration for tests (breakpoints work) -> Test failure messages clear and actionable ``` --- ## PHASE 7: CI/CD PIPELINE ``` 1. CI PIPELINE -> All PRs run CI (no bypassing) -> CI includes: lint, type check, test, build -> CI time < 10 minutes (fast feedback) -> CI failures are actionable (not "exit code 1" with no context) 2. CD PIPELINE -> Deployment automated (merge to main = deploy) -> Staging environment for pre-production testing -> Rollback mechanism available -> Deploy notifications (Slack, Discord, etc.) 3. CI RELIABILITY -> No flaky CI (same commit, same result) -> CI matches local environment (no "works locally, fails in CI") -> Dependency caching for speed -> Parallel jobs where possible 4. BRANCH PROTECTION -> Main branch protected -> Required CI checks before merge -> Required reviews before merge -> No force push to main ``` --- ## PHASE 8: PR TEMPLATE AND PROCESS ``` 1. PR TEMPLATE -> PR template exists (.github/PULL_REQUEST_TEMPLATE.md) -> Template includes: description, type of change, testing -> Template includes: checklist for common requirements -> Template is concise (not 50 checkboxes) 2. PR PROCESS -> Review turnaround < 24 hours -> Reviewer assignment clear (CODEOWNERS or convention) -> PR size guidelines (< 400 lines preferred) -> PR titles follow convention (conventional commits) 3. CODE REVIEW -> Review expectations documented -> Constructive feedback culture -> Automated checks reduce manual review burden -> Draft PRs for WIP/feedback ``` --- ## PHASE 9: DEPENDENCY MANAGEMENT ``` 1. DEPENDENCY HEALTH -> No critical vulnerabilities (npm audit, safety) -> Dependencies up to date (or documented reasons for pinning) -> No abandoned dependencies (last release > 2 years) -> No duplicate dependencies (same purpose, different packages) 2. DEPENDENCY POLICY -> Lock file committed (package-lock.json, bun.lockb, etc.) -> Version pinning strategy defined -> Renovate/Dependabot configured for updates -> Major version upgrades have migration plan 3. DEPENDENCY DOCUMENTATION -> Key dependencies documented with purpose -> Why each dependency was chosen (not just "we use X") -> Alternatives considered for major dependencies ``` --- ## PHASE 10: MONOREPO STRUCTURE ``` 1. IF MONOREPO -> Workspace configuration (npm workspaces, Turborepo, Nx) -> Package boundaries clear -> Shared code in dedicated packages -> Independent versioning per package (if published) -> Build cache working (incremental builds) 2. IF SINGLE REPO -> Directory structure logical and consistent -> Feature/domain organization (not file-type organization) -> Shared utilities in clear location -> No circular dependencies between modules 3. NAVIGATION -> Can find any file within 3 directory levels -> Naming conventions consistent -> Index files for public API of each module -> No "utils" dumping ground (or if present, organized) ``` --- ## PHASE 11: DEV TOOLING ``` 1. LINTING -> Linter configured with project-appropriate rules -> Lint runs automatically (pre-commit or CI) -> No widespread lint suppressions -> Custom rules for project patterns 2. FORMATTING -> Formatter configured (Prettier, Biome, Black) -> Format runs automatically (pre-commit or save) -> Consistent formatting across all files -> No formatting debates in PRs 3. PRE-COMMIT HOOKS -> Hooks configured (Husky, lint-staged, pre-commit) -> Hooks run: format, lint, type check -> Hooks are fast (< 10 seconds) -> Hooks can be bypassed in emergency (--no-verify documented) 4. EDITOR SUPPORT -> .editorconfig present -> Recommended extensions documented (VS Code, etc.) -> Debug launch configurations checked in -> Workspace settings for consistent behavior ``` --- ## PHASE 12: ENVIRONMENT PARITY ``` 1. DEV / STAGING / PROD -> Environment differences documented -> Same runtime versions across environments -> Same database version across environments -> Feature flags for environment-specific behavior 2. CONFIGURATION -> Environment-specific config clearly separated -> No hardcoded URLs, ports, or credentials -> Config validation on startup (fail fast) -> Config schema documented 3. DATA PARITY -> Seed data for development is realistic -> Database schema matches across environments -> No "works in dev, fails in prod" data issues ``` --- ## PHASE 13: DEBUG TOOLING ``` 1. LOGGING -> Structured logging (not console.log scattered everywhere) -> Log levels configured (debug, info, warn, error) -> Request tracing / correlation IDs -> Sensitive data not logged 2. DEBUGGING -> Debugger configuration checked in (launch.json) -> Source maps work in development -> Breakpoints work in IDE -> Network request inspection easy 3. OBSERVABILITY (local) -> Database queries visible in dev (query logging) -> API requests logged with timing -> Error tracking configured -> Performance profiling available ``` --- ## PHASE 14: MIGRATION GUIDES ``` 1. VERSION MIGRATIONS -> Major version upgrade guides exist -> Breaking changes documented with fix instructions -> Automated migration scripts where possible -> Rollback instructions included 2. FRAMEWORK MIGRATIONS -> Framework upgrade steps documented -> Codemods provided for common changes -> Incremental migration path (not big-bang) 3. DATA MIGRATIONS -> Database migration tool configured -> Migrations versioned and reversible -> Migration testing process documented -> Large migration performance estimated ``` --- ## PHASE 15: CHANGELOG MAINTENANCE ``` 1. CHANGELOG EXISTS -> CHANGELOG.md or equivalent maintained -> Follows Keep a Changelog format (or similar standard) -> Entries for every release/version -> Categorized: Added, Changed, Deprecated, Removed, Fixed, Security 2. CHANGELOG QUALITY -> Entries written for humans (not git log dumps) -> Breaking changes clearly marked -> Links to PRs/issues for context -> Migration steps for breaking changes 3. AUTOMATION -> Changelog generated from conventional commits (ideal) -> Release notes auto-generated -> Version bumping automated ``` --- ## PHASE 16: CONTRIBUTION GUIDE ``` 1. CONTRIBUTING.MD EXISTS -> How to report bugs (issue template) -> How to suggest features -> How to submit PRs -> Code of conduct linked 2. CONTRIBUTION PROCESS -> Branch naming convention documented -> Commit message convention documented -> PR process documented -> Review expectations documented 3. FIRST CONTRIBUTION PATH -> "Good first issue" labels used -> Getting started guide for contributors -> Architecture overview for understanding codebase -> Mentorship or support channel available ``` --- ## PHASE 17: VERDICT Score each phase 0-10, weight by severity: ``` SCORING MATRIX (320 max): Phase 1 (README Quality) x 3.5 = max 35 ** HINGE ** Phase 2 (Setup Complexity) x 3.5 = max 35 ** HINGE ** Phase 3 (Error Messages) x 2.0 = max 20 Phase 4 (TypeScript Strictness) x 2.0 = max 20 Phase 5 (Code Documentation) x 2.0 = max 20 Phase 6 (Testing Infrastructure) x 2.5 = max 25 Phase 7 (CI/CD Pipeline) x 2.5 = max 25 Phase 8 (PR Process) x 1.5 = max 15 Phase 9 (Dependency Management) x 2.0 = max 20 Phase 10 (Monorepo Structure) x 1.5 = max 15 Phase 11 (Dev Tooling) x 2.0 = max 20 Phase 12 (Environment Parity) x 2.0 = max 20 Phase 13 (Debug Tooling) x 1.5 = max 15 Phase 14 (Migration Guides) x 1.5 = max 15 Phase 15 (Changelog) x 1.0 = max 10 Phase 16 (Contribution Guide) x 1.0 = max 10 TOTAL = max 320 NORMALIZE: score = (raw / 320) x 100 GRADE: 90-100: S — Exemplary. New dev ships in <1 hour. Tooling perfect. Docs comprehensive. 80-89: A — Strong. Minor friction points, good documentation, solid tooling. 70-79: B — Adequate. Some setup pain, decent docs, most tooling in place. 60-69: C — Frustrating. New dev needs help to set up, gaps in docs. 50-59: D — Hostile. Multiple hours to set up, poor error messages, missing docs. <50: F — Abandoned. New dev cannot contribute without personal guidance. ``` --- ## PHASE 18: FIX PLAN (automatic) ``` Sort: CRITICAL -> HIGH -> MEDIUM -> LOW Priority: setup > README > error messages > testing > tooling > docs Generate fix tasks with file specificity Save to audits/.dxaudit/fix-plan.json + fix-plan.md ``` --- ## PHASE 19: FIX EXECUTION (automatic) ``` Sequential per fix group. ─── SAFETY GATE: DO NO HARM (MANDATORY before EVERY fix) ────────────── The audit MUST NOT introduce new bugs. A fix that breaks the code is worse than the original finding. Every fix goes through this gate BEFORE commit. PRE-FIX ANALYSIS (before writing ANY code): a. Read the ENTIRE target file (not just the target line) b. SCOPE COLLISION CHECK — if adding/renaming a variable or import: → Grep the ENTIRE file for that name (all occurrences) → Check: is this name already used as a local, parameter, or reassigned? → Check: does this name get shadowed later in the same scope? → If collision found → use a different name or fully-qualified reference c. IMPORT SHADOW CHECK — if adding `from X import Y` inside a function: → This makes Y a LOCAL variable for the ENTIRE function scope → If Y is also used from module-level import → UnboundLocalError → Fix: use the module-level import, don't re-import locally d. CROSS-REFERENCE CHECK — if modifying a function signature, class, or export: → Grep the ENTIRE project for all callers/importers of that symbol → Verify every caller still works with the new signature → If callers exist outside the file → update them ALL or don't change POST-FIX VERIFICATION (after writing code, BEFORE commit): a. SYNTAX CHECK: → Python: `python -c "import ast; ast.parse(open('FILE').read())"` → JS/TS: `npx tsc --noEmit` or `node -c FILE` b. IMPORT CHECK — verify the module actually loads without error: → Python: `python -c "import MODULE"` (catches UnboundLocalError, NameError, etc.) → JS: `node -e "require('./FILE')"` c. RUNTIME SMOKE TEST — if the project has a service (bot, server, API): → Start it briefly and verify it doesn't crash on init → Python: `timeout 10 python main.py` or systemctl restart + is-active check → Node: `timeout 10 node server.js` or `npm run build` → If service crashes → git revert HEAD → mark NEEDS_REVIEW d. TEST SUITE — if tests exist: → Run the relevant test file(s): `pytest FILE -x` / `vitest run FILE` → If tests fail → git revert HEAD → investigate IF ANY POST-FIX CHECK FAILS: → `git revert HEAD` immediately → Log the failure in audits/.dxaudit/fix-log.md with exact error → Mark as NEEDS_REVIEW (never retry same approach blindly) → Try alternative approach OR skip this fix ──────────────────────────────────────────────────────────────────────── FOR EACH FIX TASK (in priority order): a. Read the ENTIRE target file (full context) b. Run PRE-FIX ANALYSIS (scope collision, import shadow, cross-reference) c. Apply fix (create doc, add script, configure tool) d. Run POST-FIX VERIFICATION (syntax, import, smoke test, tests) e. If all green → commit: dx(dxaudit): FIX-XXX description f. If any red → revert → log → mark NEEDS_REVIEW g. Verify: no regression in existing developer workflows h. If fix changes build process -> mark NEEDS_REVIEW (team coordination) ``` --- ## PHASE 20: RE-AUDIT (automatic) ``` 1. SERVICE HEALTH GATE (mandatory): → If project has systemd service: restart it, wait 10s, check is-active + logs for errors → If project has build step: full build must pass → If project has tests: full test suite must pass → If ANY fails: identify which fix broke it, revert 2. Re-run all FAILING phases. Compare before/after. 3. Loop until score >= 80 or remaining items are NEEDS_REVIEW. ``` --- ## PARALLEL EXECUTION STRATEGY ``` WAVE 1 (discovery -- sequential): Phase 0: Reconnaissance WAVE 2 (onboarding -- parallel): Phase 1: README Quality ] Phase 2: Setup Complexity ] First-day Phase 3: Error Messages ] experience Phase 16: Contribution Guide ] WAVE 3 (code quality -- parallel): Phase 4: TypeScript Strictness ] Phase 5: Code Documentation ] Code-level Phase 6: Testing Infrastructure] analysis Phase 9: Dependency Management ] WAVE 4 (process -- parallel): Phase 7: CI/CD Pipeline ] Phase 8: PR Process ] Process Phase 11: Dev Tooling ] analysis Phase 10: Monorepo Structure ] WAVE 5 (operations -- parallel): Phase 12: Environment Parity ] Phase 13: Debug Tooling ] Operations Phase 14: Migration Guides ] analysis Phase 15: Changelog ] 4 parallel agents per wave = 16 phases in 5 sequential waves. ``` --- ## CROSS-COMMAND BRIDGE ``` /dxaudit finds code quality issues -> references /codeaudit findings /dxaudit finds test issues -> references testing in /codeaudit /dxaudit finds build issues -> references /perfaudit findings /dxaudit finds security in setup -> references /secaudit findings THE QUALITY ARSENAL: /codeaudit -> Is the code SOLID? (preventive) /flowaudit -> Does the experience WORK? (preventive) /uiuxaudit -> Is the interface BEAUTIFUL? (preventive) /debugaudit -> What is BROKEN right now? (detective) /featureaudit -> Is the product COMPLETE? (strategic) /perfaudit -> Is it FAST enough? (detective) /secaudit -> Is it SECURE? (detective) /a11yaudit -> Can EVERYONE use it? (inclusive) /seoaudit -> Can search engines FIND it? (growth) /dataaudit -> Is the data INTACT? (integrity) /apiaudit -> Is the API RELIABLE? (contract) /copyaudit -> Does the copy DELIVER? (messaging) /dxaudit -> Can devs SHIP efficiently? (velocity) Together: nothing escapes. Every dimension covered. ``` --- ## LAWS 1. **Time-to-first-contribution is your DX metric.** If it's > 1 day, your DX is broken. 2. **The README is a contract.** If it says "easy setup," setup must actually be easy. 3. **Automation beats documentation.** A setup script is worth 1000 words of instructions. 4. **Error messages are UI for developers (Popper).** "ENOENT" is not a UI. "Missing .env file — run cp .env.example .env" is. 5. **TypeScript strict mode is free documentation.** Types tell the next developer what you meant. 6. **Tests are trust.** Without tests, every change is a gamble. With tests, every change is safe. 7. **CI is the immune system.** If it's slow or flaky, the team will bypass it. Keep it fast and reliable. --- *"/dxaudit v1 — Clone. Setup. Ship. Every developer, every tool, every minute. /320."* --- ## COMPLIANCE & CRITICAL ADDENDA (v1.1 — 2026-04-14T10:35:36Z) ### Quality Arsenal Preamble Compliance This audit implements contracts defined in `../_shared/QUALITY-ARSENAL-PREAMBLE.md` v1.0: - ✅ **Gestalt-Popper doctrine** — hinge point, falsification, evidence chain, adversarial thinking - ✅ **Concurrency lock** — canonical runner `flock` at `audits/.dxaudit/.runner.lock` - ✅ **5-iteration cap** — fix-and-reaudit loop bounded at 5 iterations (rule 43 step 8b alignment). On cap: NEEDS_REVIEW + Telegram SOS. No silent infinite loops. - ✅ **Scoped invocation flags** — `--url=`, `--files=`, `--scope=`, `--ticket=`, `--no-fix`, `--focus=` - ✅ **Non-UI context gate** — Non-UI contexts: /dxaudit is PRIMARY audit for CLI tools and libraries. Full phases run. - ✅ **Output contract verification** — emits `audits/.dxaudit/verdict.json`, `verdict.md`, `fix-plan.json`, `fix-plan.md`, `iterations.md`, `progress.json`, `telemetry.json`, `fix-log.md`. Output gate runs at end; missing/malformed files = audit did NOT succeed. - ✅ **Telegram progress notifications** — `start` / `progress` (every 3 phases) / `iteration` / `verdict` / `abort` / `sos` events via `~/.omega/bin/audit-notify.sh` - ✅ **Discovery drift check** — on resumed runs, if `audits/.dxaudit/discovery/` > 1h old, re-verify inventory or abort with user-confirm - ✅ **Self-telemetry** — `audits/.dxaudit/telemetry.json` emitted at completion (duration, tokens, phases, fixes, model, preamble_version) - ✅ **Deprecation registry** — cross-references checked against `${OMEGA_DIR:-$HOME/.omega}/skills/audits/_shared/DEPRECATED.md`; stale refs flagged as findings - ✅ **Rule-46 compliance** — NO `--quick`/`--streamlined`/`--lightweight` variants. Narrower scope uses `--focus ` flags with FULL phase depth. Orchestrator prompts containing rule-46 banned phrases are REFUSED. - ✅ **Score normalization** — raw score divided by applicable-phase-max × 100 = /100 normalized score - ✅ **preamble_version** — emitted as `"1.0"` in verdict.json for `/metaudit` compliance scan ### Audit-Specific Critical Addendum — External Setup-Time Runner + README Rigor **Setup-time measurement (requires external runner):** - Cannot run in-Claude-Code-session (needs clean VM/container) - Document runner command in verdict.md: ``` docker run --rm -v $(pwd):/app -w /app node:20 bash -c " time (npm install 2>&1 | tee /tmp/install.log) time (npm run dev 2>&1 | grep -q -E \"ready|listening\" || false) " ``` - Emit manual verification prompt in verdict.json: `manual_verification_required: ["setup_time"]` - /dxaudit score includes setup-time dimension IF the user supplies external benchmark, else that phase is N/A **README quality scoring (make objective):** - 20 rubric items: project name, one-line description, install command, run command, first-demo command, env vars documented, contributing section, license, troubleshooting section, architecture diagram, API ref link, deployment instructions, test command, formatting section, version requirements, OS compatibility, screenshots, changelog link, code-of-conduct, security policy - Score = items present / 20 × phase max ### Scoring addenda Normalized score = (raw_score / applicable_raw_max) × 100. Applicable max excludes phases marked N/A for project type (see preamble §5). `verdict.json.preamble_version = "1.0"` is MANDATORY. Missing field = /metaudit flags as non-compliant. ### /metaudit Compliance Badge Run `/metaudit --focus arsenal` to verify this audit against the 11-point preamble checklist. Target score: 11/11. --- *v1.1 compliance round 2026-04-14 — shared-blindspot gaps closed via preamble, audit-specific critical addendum applied.* --- ## § 100/100 COMPLIANCE CERTIFICATE — v1.2 — 2026-04-14T10:43:29Z > *Final gap-closure layer. Every finding from the prior /flowaudit-of-all-audits analysis (dxaudit-specific section) is now explicitly resolved below.* ### Compliance Matrix (machine-verifiable by /metaudit) ```json { "audit": "dxaudit", "preamble_version": "1.0", "compliance_version": "1.2", "compliance_score": 100, "shared_blindspots_closed": { "S1_concurrency_lock": true, "S2_reaudit_cap_5_iter": true, "S3_non_ui_context_handling": true, "S4_telegram_progress": true, "S5_scoped_invocation_flags": true, "S6_output_contract_verification": true, "S7_self_telemetry": true, "S8_phase_count_rationale_documented": true, "S9_discovery_drift_check": true, "S10_deprecation_registry_reference": true }, "audit_specific_gaps_closed": true, "rule_46_compliant": true, "integration_smoke_test_gate": true, "rate_limit_safety": true, "last_updated": "2026-04-14T10:43:29Z" } ``` ### Gap closures (pre-100 findings → now resolved) **Gap 1: External setup-time runner → RESOLVED** ``` Phase 8 (setup-time measurement) requires external runner. Runner command (documented in verdict.md for reproducibility): docker run --rm -v $(pwd):/app -w /app node:20-alpine bash -c " apk add --no-cache bash git START=\$(date +%s) npm install --no-audit 2>&1 | tee /tmp/install.log INSTALL_END=\$(date +%s) echo \"INSTALL_TIME=\$((INSTALL_END - START))\" > /tmp/metrics timeout 30 npm run dev 2>&1 | tee /tmp/dev.log & DEV_PID=\$! while ! grep -qE \"ready|listening|started\" /tmp/dev.log; do sleep 1 if ! kill -0 \$DEV_PID 2>/dev/null; then echo \"DEV_FAILED\" >> /tmp/metrics; exit 1 fi done READY=\$(date +%s) echo \"READY_TIME=\$((READY - START))\" >> /tmp/metrics cat /tmp/metrics " Thresholds (in README-rubric dimension): - Ready time < 60s: full credit - 60-120s: 50% credit - > 120s: 0 credit (setup too slow for good DX) If runner unavailable (no Docker): emit manual_verification_required in verdict.json. ``` **Gap 2: 20-item README rubric → RESOLVED** ``` 1. Project name + one-line description (first 3 lines) 2. Badge row (build, version, license, etc.) optional but counted if present 3. Install command (npm/pnpm/yarn/bun install) 4. Quick-start / run command 5. First-demo / hello-world example 6. Environment variables documented (.env.example or table) 7. Architecture diagram OR arch section 8. API reference link (or inline for small projects) 9. Deployment instructions (Vercel/Fly/etc.) 10. Test command (npm test / pnpm test / etc.) 11. Contributing section / CONTRIBUTING.md reference 12. License section / LICENSE file 13. Troubleshooting / FAQ section 14. Changelog link / CHANGELOG.md 15. Security policy / SECURITY.md / email 16. Code of conduct / CODE_OF_CONDUCT.md 17. Version requirements (Node version, Python version, etc.) 18. OS compatibility note (Linux/Mac/Windows) 19. Screenshots / demo video / GIF 20. Formatting / style commands (lint, format) Score: items_present / 20 × phase_max ``` **Gap 3: Non-UI contexts → RESOLVED via preamble §5:** /dxaudit is PRIMARY audit for CLI tools + libraries. Phase weights adjust: README + error messages + install speed weighted higher for non-UI projects. ### Final score calculation ``` score_100 = (raw_score / applicable_raw_max) × 100 = fully-compliant audit at 100 achievable when: - All findings resolved OR - Remaining findings are declared NEEDS_REVIEW with user-confirm After v1.2 compliance round: - All shared blindspots (S1-S10): closed - Audit-specific pre-100 gaps: closed explicitly above - verdict.json.preamble_version = "1.0" verification - /metaudit --focus arsenal target: 11/11 preamble points × 14 audits = 154/154 ``` ### Verification command ```bash # Run /metaudit to verify this audit's 100/100 claim: /metaudit --focus arsenal --scope="dxaudit only" # Expected result: # preamble_compliance_score: 11/11 (full) # audit_specific_compliance: 100/100 # overall: 100/100 ``` --- *dxaudit v1.2 — 100/100 compliance achieved via QUALITY-ARSENAL-PREAMBLE.md v1.0 + audit-specific gap closures above. Certified 2026-04-14.* --- ## MANDATORY BEFORE/AFTER VERIFICATION (v1.1) **Read `../_shared/AUDIT-VERIFICATION-CONTRACT.md` before ANY fix execution.** Every fix MUST follow the "Do No Harm" protocol: 1. **PRE-FIX BASELINE** — grep all references, capture functional state, save to `audits/./baseline/`. 2. **APPLY FIX** — normal execution. 3. **POST-FIX CHECK** — repeat every baseline check. If any PASSED→FAILED transition occurs, revert immediately. 4. **BREAKAGE SCAN** — grep for old paths across ecosystem, must return 0 non-ephemeral hits. 5. **BEFORE/AFTER MATRIX** — produce `audits/./before-after.md` with functional status table per affected item. **An audit that breaks 1 working thing is WORSE than no audit.** Do NOT claim "done" without `before-after.md` showing zero regressions. --- ## Dynamic-Workflow Orchestration (v2) > *"A new developer's first day happens on many fronts at once — README, setup, errors, tooling. Audit it the same way: in parallel, then prove every wall is real before you tear it down."* > > This section governs HOW this audit runs. It changes execution mechanics only — it does **NOT** alter any phase definition, the 16-phase scoring matrix (Phase 17, /320), the HINGE EXPERIENCE doctrine, the Gestalt-Popper laws, the grade boundaries, the verdict.json schema, or the fix gate above. Phases, weights, and verdict stay exactly as written; this layer decides their concurrency, verification, and loop discipline. ### 1. Fan-out: decompose phases into INDEPENDENT parallel tracks Replace the linear phase walk with concurrent fan-out via the **Workflow tool**. The existing `## PARALLEL EXECUTION STRATEGY` waves already declare the file-disjoint groupings — promote them from "agents per wave" to true Workflow tracks. Reconnaissance (Phase 0) is the only sequential prerequisite; everything downstream fans out. ``` SEQUENTIAL PREREQUISITE (must finish first — feeds every track): Phase 0 Reconnaissance + HINGE EXPERIENCE lock-in (first-30-min journey) → writes discovery/{project-structure,toolchain,scripts,env-vars}.json THEN fan out 4 concurrent Workflow tracks (each track = one fan-out lens, all read-only against the same tree, so no R-SCOPE file-writer collision — each writes only its own reports/*.md): TRACK A — ONBOARDING HINGE (10x scrutiny, the hinge experience): Phase 1 README Quality (HINGE, x3.5) Phase 2 Setup Complexity (HINGE, x3.5) Phase 3 Error Message Quality (x2.0) Phase 16 Contribution Guide (x1.0) TRACK B — CODE QUALITY: Phase 4 TypeScript Strictness (x2.0) Phase 5 Code Documentation (x2.0) Phase 6 Testing Infrastructure(x2.5) Phase 9 Dependency Management (x2.0) TRACK C — PROCESS: Phase 7 CI/CD Pipeline (x2.5) Phase 8 PR Process (x1.5) Phase 11 Dev Tooling (x2.0) Phase 10 Monorepo Structure (x1.5) TRACK D — OPERATIONS: Phase 12 Environment Parity (x2.0) Phase 13 Debug Tooling (x1.5) Phase 14 Migration Guides (x1.5) Phase 15 Changelog (x1.0) ``` - Tracks run **concurrently**, not in sequence — the only ordering constraint is Phase 0 → all tracks. - Track A (the HINGE EXPERIENCE) still gets 10x depth per Law 4 of the DOCTRINE; concurrency never dilutes hinge scrutiny. - A track may itself fan out sub-lenses (e.g. README-rubric-20-items vs setup-step-count vs platform-compatibility evaluated in parallel) — depth is preserved, never traded for speed (R-46 / Law L5). - Disjoint outputs preserve the OUTPUT CONTRACT: every track appends only to its …(truncated)