# Polylith Migrate Convert Type Checker

> [Internal sub-skill of `polylith-migrate-orchestrator` (optional, runs only when opted in during `polylith-migrate-discover`). Do not load directly — load `polylith-migrate-orchestrator` first.] Align the project's type checker with the **workspace's** configured tool (whatever it is — mypy, pyright, ty, etc.). Removes project-specific config and consolidates settings into the workspace root.

- Skill: `davidvujic/polylith-migrate-convert-type-checker` (Agent Skill)
- Install (CLI): `npx skillmds@latest add davidvujic/polylith-migrate-convert-type-checker`
- Raw SKILL.md: https://api.skillmd.com/api/skills/davidvujic/polylith-migrate-convert-type-checker/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: davidvujic (https://skillmd.com/u/davidvujic)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/davidvujic/polylith-migrate-convert-type-checker

---


# Skill: polylith-migrate-convert-type-checker

## Goal
Align the project with the **workspace's** type checker. This skill is **not** opinionated about ty — it reads the workspace's configured tool from the root `pyproject.toml` and aligns the project to that.

## When to Skip
Skip this step if the project's `TYPE_CHECKER` in `migration/<PROJECT>/state.md` already matches the workspace's type-checking tool.

## Inputs
From `migration/<PROJECT>/state.md`:
- `PROJECT_DIR`
- `TYPE_CHECKER`
- `RUN_TEST_CMD` (optional: `RUN_LINT_CMD`, `RUN_TYPECHECK_CMD`)

> All inputs from `state.md` are assumed to satisfy the validation rules in `polylith-migrate-discover` (`### Validation rules`). Validate before proceeding.

## Steps

### 0. Identify the workspace's tool
Open the **workspace root** `pyproject.toml` and identify the configured type checker using the same detection table as `polylith-migrate-discover` (`[tool.mypy]` or `mypy.ini` → mypy, `[tool.pyright]` or `pyrightconfig.json` → pyright, `[tool.ty]` → ty). Record what you found — every step below refers to "the workspace's type checker" and means **this** tool, not necessarily ty.

If the workspace has no type checker configured at all, stop and ask the user how to proceed (introduce one? skip type-check alignment? abort the conversion?).

### 1. Remove Old Configs and Dependencies
- Remove the following sections from `pyproject.toml`:
  - `[tool.mypy]`, `[[tool.mypy.overrides]]`, `[mypy-*]`, `[tool.pyright]`, `[tool.pytype]`
- Remove standalone config files: `mypy.ini`, `.mypy.ini`, `pyrightconfig.json`.
- Remove old type checker dependencies from `pyproject.toml`:
  - `mypy`, `mypy-extensions`, `types-*` stub packages, `pyright`, `pytype`, `sqlalchemy-stubs`, `django-stubs`.

### 2. Clean Up Type Ignore Comments
- Remove `# type: ignore[<mypy-code>]` comments that reference mypy-specific error codes.
- Leave comments that suppress real issues and document them in `state.md`.

### 3. Adopt Workspace Type-Checking Config
- The workspace root `pyproject.toml` may define the type-checking configuration. The project inherits this config.
- Add project-specific overrides if needed.

### 4. Run the Workspace's Type-Checking Tool
- Run the workspace's type-checking tool to assess errors:
  - **Same or fewer errors**: No action needed.
  - **New errors**: Ask the user whether to fix, suppress, or adjust the config.
  - **Missing stub errors**: Silence with per-module ignores in the workspace's type-checking config.

### 5. Update `state.md`
- Set `TYPE_CHECKER` to the workspace's type-checking tool.
- Update `RUN_TYPECHECK_CMD` to use the workspace's type-checking command.

## Verify
- The workspace's type-checking tool runs cleanly (or remaining errors are user-approved).
- `RUN_TEST_CMD` succeeds.
- If set, `RUN_LINT_CMD` succeeds.

## Common failure modes

| Symptom | Likely cause | Remediation |
|---------|--------------|-------------|
| The workspace's checker surfaces type errors the old checker didn't | Stricter type rules expose real bugs that were always there. | Fix the bugs now where cheap (small handful). For systemic gaps, suppress per-module in the workspace's checker config and document the debt in `state.md`. Do **not** blanket-ignore at file scope. |
| Stub packages (`types-*`, `django-stubs`, `sqlalchemy-stubs`) were required by the old checker but the new one bundles its own | Dependency carryover. | Remove the stub packages from `pyproject.toml`. Re-run the workspace's checker to confirm it picks up its own stubs. |
| `# type: ignore[<old-code>]` comments still reference the old checker's error codes | Step 2 missed some. | Strip the `[<code>]` bracket. If the suppression is still needed, leave a bare `# type: ignore` **with a comment explaining why**; otherwise remove the suppression entirely. |

## Done When
- No old type checker config files remain.
- Old type checker dependencies are removed from `pyproject.toml`.
- Stale `# type: ignore` comments referencing tool-specific codes are removed (or documented if intentionally kept).
- `TYPE_CHECKER` in `migration/<PROJECT>/state.md` matches the workspace's type-checking tool.
- The workspace's type-checking tool runs cleanly or known issues are documented in `state.md`.
- Tests pass via the workspace's tooling.

## Commit

After verification passes, commit this phase to the migration branch:

```bash
git add -A && git commit -m "migrate(<PROJECT>): phase optional — convert-type-checker"
```

Substitute `<PROJECT>` from `state.md`. This is an **optional** skill off the numbered main line, so the commit uses the literal `phase optional` label (no `<N>`). Do not proceed without a clean commit — the per-phase commit is the rollback point for the next phase's failure-mode tables.