| name | maintainable-typescript |
| description | Guides maintainability-first cleanup, refactoring, and review in strict TypeScript repos and monorepos. Use when improving code health, deleting dead code, reducing duplication, or enforcing boundaries. |
Maintainable TypeScript
Use this skill when the project needs maintainability doctrine, not just local code changes.
Layout
doctrine/ contains the portable rules and supporting guidance that should hold across strict TypeScript repos.stack/ contains stack-specific doctrine for the opinionated Vite+ / Drizzle / oRPC / Cloudflare setup.prompts/ contains reusable prompt text for cleanup and review tasks when you need to steer another model away from wrapper-heavy refactors.scripts/ contains runnable TypeScript-repo audit helpers for dead code, duplicate code, and import-boundary problems in the current project.assets/tooling-templates/ contains copyable config templates for target repos.
Reading order
Do not read the whole skill directory by default.
- Read this file first.
- Decide whether the task needs only portable rules or the full house stack.
- Load only the doctrine files relevant to the task.
- Treat the rest of the skill as reference material, not required context.
Default portable backbone:
If the repo matches the house stack, read stack/start-here.md before any stack-specific files.
Task Router
Use the smallest relevant set.
Cleanup, deletion, and refactor
Package boundaries and shared runtime code
API, schemas, and OpenAPI
Types, constants, and documentation
Testing and high-risk logic
Frontend and React state
Toolchain, dependencies, and database workflow
Full doctrine review or editing this skill itself
- read all of
doctrine/
- read all of
stack/
- use the bundled verification scripts before finishing
Audit workflow
When the task is cleanup or review, resolve the skill directory first and then run:
skill_dir="<path-to-this-skill>"
bash "$skill_dir/scripts/audit-typescript-repo.sh" .
Treat audit output as signal, not authority. Check real usage before deleting API surface or collapsing a pattern.
If the target repo is Vite+, use vp for the normal toolchain entrypoint: vp lint, vp test, vp fmt, vp pack, vp add, and vp dlx.
Defaults
- Code is cheap. Structure is expensive.
- Preserve contracts, tests, and invariants, not stale decomposition.
- Prefer deletion over shims.
- Prefer stable subsystem files over one-helper-per-file trees.
- Prefer derived types and schemas over handwritten duplicates.
- Prefer durable tests that attach regressions to real product boundaries.
- Prefer slice integration tests over internally mocked unit tests.
- Prefer mocking only external systems you do not control.
- Prefer contract-gated synthetic fixtures over handwritten unchecked JSON.
- Prefer assertions on rendered output, HTTP behavior, persisted state, and published artifacts over helper call order.
- Prefer mature tooling for dead code, duplication, and dependency boundaries over manual inspection.
- Prefer making the codebase more coherent now over promising to clean it up later.
