miguelspizza 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.
- Read this file first.
- Load only files that match the task.
- If the repo matches the house stack, read
stack/start-here.md. - Treat
doctrine/,stack/,prompts/,scripts/, andassets/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.