migrate-to-shoehorn

Overview of migrate-to-shoehorn skill

The migrate-to-shoehorn skill helps you refactor TypeScript test code away from brittle as assertions and toward @total-typescript/shoehorn. It is best for developers who already have tests full of as Type or as unknown as Type, especially where large object shapes make setup noisy and misleading.

What migrate-to-shoehorn is for

Use migrate-to-shoehorn when your real job is not “learn a library,” but clean up unsafe test fixtures without rewriting the whole test suite. The skill is centered on a narrow refactoring task:

• replace as Type with fromPartial()
• replace as unknown as Type with fromAny()
• reduce fake boilerplate for large input objects in tests

Who should install this skill

This migrate-to-shoehorn skill is a strong fit if you:

• maintain TypeScript tests with lots of casting
• want safer partial fixtures
• need help deciding which assertion pattern maps to which shoehorn helper
• want an agent to perform or guide a targeted refactor instead of giving generic TypeScript advice

What matters most before adoption

The biggest decision point is scope: this skill is explicitly about tests, not production code. That matters because shoehorn is useful when you intentionally want incomplete or even invalid data to drive test cases, but you still want clearer, more deliberate typing than raw assertions.

Why use migrate-to-shoehorn instead of a generic refactor prompt

A generic prompt may remove as mechanically and miss intent. migrate-to-shoehorn is more useful because it is tuned to the practical migration patterns developers actually hit:

• partial test inputs for large object types
• intentional bad data in negative tests
• reducing fake properties that are irrelevant to the test

That narrower focus usually means less guessing and fewer unsafe replacements.

How to Use migrate-to-shoehorn skill

Install context for migrate-to-shoehorn skill

To use the underlying library in your project, install:

npm i @total-typescript/shoehorn

If you are installing the skill into a skills-enabled environment, use your platform’s normal skill installation flow, then invoke migrate-to-shoehorn when working on test refactors.

Read this file first

Start with SKILL.md in the migrate-to-shoehorn folder. In this repository, that is the main source of truth and contains the migration patterns that drive the skill.

Suggested reading order:

1. migrate-to-shoehorn/SKILL.md
2. the test files you want to change
3. your local usages of as Type and as unknown as Type

What input the skill needs

The skill works best when you provide:

• the current test snippet
• the target function or component being called
• the relevant type name, if known
• whether the test data is meant to be valid or intentionally invalid
• whether you want a one-off fix or a repeatable migration pattern

Without that context, an agent can still suggest fromPartial() or fromAny(), but it may choose the wrong helper.

Core migration patterns to ask for

The practical migrate-to-shoehorn usage patterns are simple:

• as Type → usually fromPartial()
• as unknown as Type → usually fromAny()
• huge fake object where only a few fields matter → fromPartial()

This is the core value of the skill: it turns vague “clean up these test casts” requests into a consistent refactoring approach.

How to write a strong migrate-to-shoehorn prompt

A weak prompt:

Replace as with shoehorn.

A stronger prompt:

Use the migrate-to-shoehorn skill to refactor this test file. Replace plain as Request casts with fromPartial() where the object is just a partial fixture. Replace as unknown as Request with fromAny() only where the test intentionally passes invalid data. Keep the test behavior unchanged and add imports if needed.

That version gives the agent intent, boundaries, and a decision rule.

Example: partial fixture migration

Before:

getUser({ body: { id: "123" } } as Request);

After:

import { fromPartial } from "@total-typescript/shoehorn";

getUser(fromPartial({ body: { id: "123" } }));

Use this when the fixture is structurally incomplete but conceptually valid for the test.

Example: intentionally wrong data migration

Before:

getUser({ body: { id: 123 } } as unknown as Request);

After:

import { fromAny } from "@total-typescript/shoehorn";

getUser(fromAny({ body: { id: 123 } }));

Use this when the test is deliberately passing invalid data to exercise validation or failure paths.

Best workflow for larger refactors

For a repo-wide migrate-to-shoehorn guide, do not batch-rewrite everything blindly. A safer workflow is:

1. search test files for as and as unknown as
2. classify casts into partial-valid vs intentionally-invalid
3. migrate one test folder first
4. run tests and typecheck
5. standardize import style and helper choice
6. then scale to the rest of the suite

This avoids mixing legitimate negative-test casts with ordinary fixture cleanup.

Practical tips that improve output quality

Ask the agent to preserve these details:

• existing test names and assertions
• semantic intent of invalid-input tests
• minimal fixture shape rather than fully expanded fake objects
• import de-duplication if multiple helpers are used

Also state clearly if you want the skill to prefer the smallest fixture possible. That usually produces the cleanest shoehorn refactor.

When migrate-to-shoehorn is the wrong tool

Do not use migrate-to-shoehorn for Refactoring if your real issue is production type safety, domain modeling, or API contract correctness. This skill is not meant to “fix” types everywhere. It is a focused test-refactoring aid.

migrate-to-shoehorn skill FAQ

Is migrate-to-shoehorn only for tests?

Yes. That is the most important boundary. The skill is designed around test ergonomics and test intent, not production typing patterns.

Do I need shoehorn if my tests already pass?

Not necessarily. Install migrate-to-shoehorn if your current tests are hard to read, full of noisy fake objects, or depend on unsafe casts that hide intent. If your test setup is already clean, the migration may not be worth it.

What is the difference between fromPartial and fromAny?

fromPartial() fits incomplete but otherwise sensible fixture data.
fromAny() fits intentionally invalid data, where the test should bypass stricter typing to simulate bad runtime input.

That distinction is one of the main reasons to use the skill instead of a broad “remove assertions” prompt.

Is migrate-to-shoehorn beginner-friendly?

Yes, if you already understand basic TypeScript tests. The skill’s scope is small, and the migration rules are easy to follow. The main beginner risk is overusing shoehorn outside tests.

Can I use this skill for a whole repository migration?

Yes, but only if you review category by category. The biggest failure mode in large migrations is treating all casts as equivalent. Some are partial fixtures; some are intentionally broken payloads; some may belong to production code and should not be migrated with this pattern.

Is this better than ordinary prompting?

Usually, yes, when the task is specifically “migrate test assertions to shoehorn.” Ordinary prompts may know the library, but migrate-to-shoehorn usage is better when you want consistent mapping from old cast style to the correct helper.

How to Improve migrate-to-shoehorn skill

Give the agent the test intent, not just the code

The fastest way to improve migrate-to-shoehorn results is to say whether each test is checking:

• happy-path behavior with partial setup
• validation failure with intentionally wrong input
• edge cases that need only a few fields

That single bit of context often determines fromPartial() vs fromAny().

Mark files as test-only up front

If a file mixes helper code and production code, say so. The skill is much safer when you explicitly tell the agent:

Only apply migrate-to-shoehorn changes inside test files and test fixtures.

This prevents accidental spread into non-test paths.

Ask for a cast inventory before changes

For messy suites, start with:

Using the migrate-to-shoehorn skill, classify each cast in this file as fromPartial, fromAny, or leave unchanged, then explain why.

That review-first step catches edge cases before the actual rewrite.

Provide nearby types when inference is unclear

If the snippet alone does not show the expected type, include the function signature or relevant type definition. Stronger type context leads to better import choices and fewer awkward rewrites.

Watch for these common failure modes

Common problems during migrate-to-shoehorn install and adoption are:

• using shoehorn in production code
• converting intentionally invalid data to fromPartial()
• expanding fixture objects instead of simplifying them
• changing test meaning while “cleaning up” types

These are not library issues; they are prompt and review issues.

Iterate on the first output

After the first pass, ask for a second refinement such as:

• minimize each fixture to only required test fields
• consolidate imports
• explain any remaining casts that should stay
• separate valid partial data from invalid test data

That turns a basic migration into a cleaner long-term testing pattern.