maintainable-typescript

Maintainable TypeScript

Use this skill when the project needs maintainability doctrine, not just local code changes.

Load Order

Do not read the whole skill directory by default.

1. Read this file first.
2. Load only files that match the task.
3. If the repo matches the house stack, read stack/start-here.md.
4. Treat doctrine/, stack/, prompts/, scripts/, and assets/tooling-templates/ as references, not required context.

Companion Skills

Use the fallow skill for Fallow config, commands, JSON output, fixes, CI gates, and result interpretation. If missing:

npx skills add https://github.com/fallow-rs/fallow/tree/main/npm/fallow/skills/fallow --skill fallow

Task Router

• Backbone: maintainability-equals-correctness, resolve-uncertainty-into-contracts, ssot-or-die, integration-first-testing, external-boundary-mocks-only, assert-observable-outcomes
• Cleanup/refactor: clean-up-what-you-touch, delete-obsolete-code, no-backwards-compat-shims, delete-fake-layers, edit-real-owners, build-deep-modules-not-shallow-abstractions, cleanup-module-rewrite, review-structural-slop
• Packages/boundaries: structure-typescript-apps-around-feature-owners, monorepo-package-boundaries, treat-critical-code-like-a-library, naming-is-navigation, no-re-exports, no-barrel-exports
• Stack/API/types: stack-overview, design-openapi-for-inference, errors-are-schema, document-fields-in-derived-zod-schemas, use-canonical-named-types, jsdoc-with-first-party-sources, no-magic-values, use-branded-scalar-types
• Testing/frontend/tooling: contract-gate-synthetic-fixtures, test-ai-apps-by-artifacts-not-prose, no-type-casts, boundaries-validate-internals-trust, do-not-synchronize-state-with-useeffect, use-the-design-system-not-ad-hoc-tailwind, test-react-apps-in-real-browsers, maintainability-tooling
• Editing this skill: read the files you touch, then run the bundled verification scripts.

Audit workflow

For cleanup or review:

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

• Structure is expensive; preserve contracts, tests, and invariants.
• Prefer deletion over shims, real owners over fake layers, and stable subsystem files over helper forests.
• Resolve uncertainty into contracts, not adapters, defaults, optionals, spreads, or catches.
• Prefer derived types/schemas, durable integration tests, external-boundary mocks only, and assertions on observable outcomes.
• Prefer Fallow for dead code, duplication, dependency hygiene, health, cycles, and dependency boundaries.
• Leave the codebase more coherent now.