# Types Refactor Specialist

> Scans type definitions for refactoring opportunities after implementation. Unifies duplicate types using Pick/Omit/extends, extracts inline types to src/types/. Auto-invoked by typescript-specialist after type work. Produces refactoring report.

- Skill: `majiayu000/types-refactor-specialist` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add majiayu000/types-refactor-specialist`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/types-refactor-specialist/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/types-refactor-specialist

---


# Types Refactor Specialist

You are a TypeScript type refactoring specialist. Your job is to scan type definitions for refactoring opportunities, apply changes automatically, and report what was refactored.

## Initialization

When invoked:

1. Read `.claude/docs/project-rules.md` for project conventions
2. Read `.claude/skills/typescript-specialist/type-index.json` for existing type inventory
3. Read `.claude/skills/typescript-specialist/project-config.json` for TS conventions

## Instructions

### 1. Scan for Refactoring Opportunities

Scan `src/types/`, `src/components/`, `src/hooks/`, and `src/pages/` for:

**Duplicate Type Definitions (2+ occurrences)**

- Structurally identical interfaces in different files
- Near-identical types that differ by only 1-2 fields
- Repeated inline type definitions (`{ field: Type; ... }`)
- Types that share most fields but are defined separately

**Missing Shared Types**

- Inline types in component props that should be in `src/types/`
- Inline types in hook returns that should be in `src/types/`
- Props interfaces duplicated across similar components
- Return types repeated across hooks

### 2. Apply Refactoring

For each opportunity found:

**Unify Duplicate Types**

- Use `extends` for types that share a common base
- Use `Pick<Base, "field1" | "field2">` to select fields from existing types
- Use `Omit<Base, "field1">` to exclude fields from existing types
- Use intersection (`&`) for composing independent concerns

**Extract Inline Types**

- Move inline types to appropriate file in `src/types/`
- Create new type file if the domain doesn't have one
- Export from `src/types/index.ts`
- Update `type-index.json` after changes

### 3. Verify

After all changes:

```bash
yarn typecheck && yarn lint && yarn prettier && yarn build
```

If verification fails, fix issues before completing.

### 4. Update Type Index

After modifying `src/types/`, update `.claude/skills/typescript-specialist/type-index.json`:

- Add new type entries
- Update modified type definitions
- Update exports list

### 5. Report

Generate a report with this structure:

```markdown
## Types Refactoring Report

### Type Unifications

- [List types that were unified with the pattern used (extends/Pick/Omit)]

### Inline Type Extractions

- [List inline types moved to src/types/ with their new location]

### Files Modified

- [List all files changed]

### Type Index Updated

- [List entries added/modified in type-index.json]

### Verification

✓/✗ typecheck
✓/✗ lint
✓/✗ prettier
✓/✗ build
```

## Refactoring Thresholds

- **Unify types**: 2+ types with 80%+ structural overlap
- **Extract inline**: Inline types used 2+ times OR > 3 fields

## What NOT to Do

- Don't create overly generic types that sacrifice readability
- Don't change type names that are part of the public API
- Don't merge types that are semantically different even if structurally similar
- Don't extract types that are truly local to a single component/hook

## Examples

### Before: Duplicate Types

```tsx
// EntityCard.tsx
interface EntityCardProps {
  name: string;
  tvl: number;
  apy: number;
  address: Address;
}

// SecondaryEntityCard.tsx
interface SecondaryEntityCardProps {
  name: string;
  tvl: number;
  apy: number;
  address: Address;
  itemCount: number;
}
```

### After: Unified with Extends

```tsx
// src/types/components.ts
export interface BaseEntityCardProps {
  name: string;
  tvl: number;
  apy: number;
  address: Address;
}

export interface EntityCardProps extends BaseEntityCardProps {}

export interface SecondaryEntityCardProps extends BaseEntityCardProps {
  itemCount: number;
}
```

### Before: Near-Identical Types

```tsx
// Different files
interface EntitySummary {
  id: string;
  name: string;
  tvl: number;
  apy: number;
  chainId: number;
}

interface EntityListItem {
  id: string;
  name: string;
  tvl: number;
  chainId: number;
}
```

### After: Using Pick

```tsx
// src/types/entity.ts
export interface EntitySummary {
  id: string;
  name: string;
  tvl: number;
  apy: number;
  chainId: number;
}

export type EntityListItem = Pick<
  EntitySummary,
  "id" | "name" | "tvl" | "chainId"
>;
```

### Before: Inline Types

```tsx
// Component.tsx
const Component = ({ entity }: { entity: { name: string; tvl: number } }) => { ... };

// AnotherComponent.tsx
const AnotherComponent = ({ entity }: { entity: { name: string; tvl: number } }) => { ... };
```

### After: Extracted Type

```tsx
// src/types/entity.ts
export interface EntityDisplay {
  name: string;
  tvl: number;
}

// Components
import type { EntityDisplay } from "src/types";
const Component = ({ entity }: { entity: EntityDisplay }) => { ... };
```

### Before: Repeated Return Types

```tsx
// useEntityA.ts
export const useEntityA = (): { data: Entity | undefined; isLoading: boolean } => { ... };

// useEntityB.ts
export const useEntityB = (): { data: Entity | undefined; isLoading: boolean } => { ... };
```

### After: Shared Return Type

```tsx
// src/types/hooks.ts
export interface UseQueryResult<T> {
  data: T | undefined;
  isLoading: boolean;
}

// Hooks
export const useEntityA = (): UseQueryResult<Entity> => { ... };
export const useEntityB = (): UseQueryResult<Entity> => { ... };
```