monorepo-doctor — SKILL.md

Note

Generated from skills/monorepo-doctor/SKILL.md. Raw Markdown for agents: /skills/monorepo-doctor/SKILL.md.

Audit a JS/TS monorepo for five classes of problems that teams routinely miss, and produce an evidence-backed report.

Prerequisites: Node ≥ 22.5. The work dir is $W = $(node -p 'require("os").tmpdir()')/monorepo-doctor (see detection.md).

Rules

• Read-only. Never install dependencies, build, run tests, or edit project files. Allowed writes: monorepo-doctor-report.md, monorepo-doctor-report.json (default <tmpdir>/monorepo-doctor-reports, or a user-given dir) and $W.
• Allowed commands: the snippets in the reference files, npx --yes knip@6.41.0, npm_config_ignore_scripts=true npx --yes publint@0.3.25 (exact pinned versions — never unpinned or @latest; bump only after review), npm pack --dry-run --json --ignore-scripts, read-only git log, and npx nx / npx turbo only if detection reports them installed (graph / --dry=json / boundaries only — never real task runs, with read-only env vars from the references).
• Never abort a check. If a tool fails, mark the check partial or skipped with a reason and continue.
• Every finding needs evidence (config snippet, file:line, or command output). No evidence → no finding.
• Actionable only. Do not emit a finding when the honest fix is “keep it as-is” — a deliberate, idiomatic or correct pattern (e.g. cache: false on a migration task, lazy ORM references). Mention it in the check’s reason instead.
• One root cause, one finding. If two findings share the same fix, merge them.
• Use only the finding ids defined in the reference files.

Workflow

1. Detect — follow references/detection.md. Stop if NO_WORKSPACE.
2. Scan — follow references/scan.md.
3. Check — run all five unless the user asked for a subset (write {"status":"not-run","reason":"not requested","findings":[]} to $W/findings/<check>.json for the others):
   • references/boundaries.md — package split & public API
   • references/circular-deps.md — package and file cycles
   • references/caching.md — Nx / Turborepo cache correctness
   • references/ci-coverage.md — tests that silently don’t run in CI
   • references/prod-leakage.md — test code shipped to production The checks are independent; if you can run sub-agents, run them in parallel.
4. Report — follow references/report-format.md: validate each findings/<check>.json, render, then show the user where the reports were written, the summary line and the top 5 findings.
5. CI mode (only if asked, or when invoked non-interactively with a threshold) — run the exit-code snippet from report-format.md.

Tracking

Create a todo per phase/check and mark each done as its findings file is written.