monorepo-doctor

---
name: monorepo-doctor
description: Deeply audits a monorepo (especially Turborepo-based ones) that has grown organically and now feels out of hand — build pipeline, package boundaries, code duplication across apps, CI/CD, quality gates, config sharing, env/secret hygiene, performance, and docs — then produces a phased migration plan to bring it to an enterprise-grade setup. Use this whenever the user says a monorepo has "grown out of hand," asks for a monorepo health check, audit, or "state of the repo" review, wants to know if their Turborepo setup follows best practices, or asks for a plan to refactor/clean up/modernize/consolidate a monorepo. This is analysis-and-planning only — it produces an ANALYSIS.md and a MIGRATION_PLAN.md and does not execute changes; for day-to-day turbo.json/pipeline/caching configuration questions on a repo that isn't in crisis, defer to the turborepo skill instead.
license: MIT
---

# Monorepo Doctor

A monorepo that started clean drifts: packages get duplicated instead of shared, configs get copy-pasted instead of extended, CI grows ad hoc, and nobody remembers why. This skill does two things, in order, and does not skip ahead: **diagnose first, prescribe second.** Don't start proposing fixes while still exploring the repo — the value of the migration plan depends on the analysis being complete and evidence-based, not a first impression.

Treat this like a real audit: every finding needs a concrete pointer (a file path, a grep hit, a count) — not "the config setup seems inconsistent" but "apps/web and apps/admin each define their own tsconfig.json with no `extends`, diverging on strictness."

## Step 1: Deep analysis

Work through `references/checklist.md` dimension by dimension. It has concrete things to grep for, files to open, and commands to run for each of the ten dimensions:

1. Build & task pipeline (turbo.json, `dependsOn`, task graph shape)
2. Package boundaries & dependency graph (workspace structure, internal package protocol, circular deps)
3. Extraction correctness — is cross-cutting logic (database access, UI primitives, auth, config, utils) actually pulled into shared packages, or copy-pasted / reimplemented per app
4. App structure (apps/ vs packages/ separation, ownership clarity)
5. CI/CD (what runs, whether it's affected-aware, whether remote caching is wired into CI)
6. Quality gates (lint/typecheck/test/format — shared, enforced, and actually run before merge)
7. Config sharing & extension (tsconfig, eslint, tailwind, prettier — extended from a base package vs duplicated)
8. Env variable handling (how env vars flow to apps/packages, validation, `.env.example` hygiene, secret leakage risk)
9. Repo-level performance (cache hit rates, unnecessarily broad `dependsOn`, package granularity, build/CI times — this is about repo structure, not runtime performance of the apps themselves)
10. Documentation & AI tooling conventions (per-package READMEs, architecture docs, and whether there's a clear, followed convention for AI agent instructions — CLAUDE.md, `.cursor/rules`, agent skills, etc.)

Don't treat the checklist as a form to fill mechanically — some dimensions may be genuinely fine in a given repo, and that's a real finding too ("CI is solid, skip it"), not something to pad with manufactured issues.

Gather evidence with real commands, not assumptions. Run `scripts/gather-evidence.sh <repo-path>` first — it covers the deterministic checks shared across most dimensions (repo shape, workspace/config duplication, CI presence, extraction-correctness greps, env handling, docs/AI conventions) in one pass. For anything dimension-specific it doesn't cover, or a tool it doesn't handle (Nx, Bazel, etc.), use the commands called out inline in `references/checklist.md` for that dimension.

Adapt to the actual package manager (npm/yarn/pnpm/bun workspaces) and repo layout you find — don't force a pnpm-specific check on a yarn workspaces repo.

If the repo has cache/build data available (`.turbo/`, CI logs, or the user can run `turbo run build --dry=json`), use it to ground the performance dimension in actual numbers rather than guesses about cache hit rate.

## Step 2: Write ANALYSIS.md

Use the structure in `references/analysis-template.md`. Every finding must cite the evidence that produced it (a path, a count, a snippet) — a reader should be able to verify each claim in under a minute. Severity is about actual cost (build time, onboarding friction, bug risk from drift) not dimension coverage — it's fine for some dimensions to have zero findings.

Show this to the user before moving to Step 3. If the repo is large, offer to focus the plan on the 2-3 dimensions causing the most pain rather than trying to fix everything at once.

## Step 3: Write MIGRATION_PLAN.md

Only after the analysis is confirmed (or the user explicitly says to proceed). Use `references/migration-plan-template.md`. The plan must:

- Map directly back to ANALYSIS.md findings — every phase should reference which finding(s) it resolves, so the user can trace prescription back to diagnosis.
- Be phased and sequenced by dependency, not by dimension. E.g. "extract shared tsconfig" typically has to land before "enforce strict mode repo-wide" — don't propose them as independent parallel phases if one blocks the other.
- Front-load the changes that are cheap and de-risk everything after (shared configs, a CI baseline) before proposing bigger structural moves (extracting a new package, splitting an app).
- Call out anything genuinely risky (splitting a package apps depend on heavily, changing the workspace tool) with the specific risk and a mitigation, not just a warning label.
- Stop at planning. This skill does not execute the migration — if the user wants to start implementing, that's a distinct, explicit next step (e.g. via `/make-plan` and `/do` on a specific phase, or just asking directly). Say so plainly rather than starting to edit files.

## Notes

- This skill is diagnostic and prescriptive, not a build-config reference. For "how do I write a turbo.json task for X" or "why is my cache missing" on a repo that isn't in a full audit, point to the **turborepo** skill instead.
- If the repo isn't actually a Turborepo (Nx, Lerna, bare workspaces, Bazel, etc.), the ten dimensions still apply — just adapt the tool-specific evidence-gathering commands (e.g. `nx.json` and `nx graph` instead of `turbo.json`).
- Keep the two output files separate. Users come back to re-run just the analysis after a few phases land, and a combined file makes that awkward to diff against.