---
name: graphql-schema-refactoring-tool
description: "A cleaned-up GraphQL schema with a safe migration path: naming brought to one convention, deprecated fields handled the way you chose, comments preserved, the right version bump, and a checklist of what clients and resolvers must change. Use when a GraphQL schema needs its naming unified, deprecated fields retired or marked, and a version bump with a migration checklist so clients are not broken. Do not use for performance tuning like pagination and complexity limits, or debugging schema load errors. Related topics: coding, graphql."
---

# GraphQL Schema Refactoring Tool

A cleaned-up GraphQL schema with a safe migration path: naming brought to one convention, deprecated fields handled the way you chose, comments preserved, the right version bump, and a checklist of what clients and resolvers must change.

## When to use

Use this skill when a GraphQL schema needs its naming unified, deprecated fields retired or marked, and a version bump with a migration checklist so clients are not broken. Do not use it for performance tuning like pagination and complexity limits, or debugging schema load errors.

## Workflow

1. Ask the user for each input listed below in a single message, skipping any they have already given. Where options are listed, offer them, but accept other answers too.
2. Diff the intended changes: every rename, deprecation, removal, merge, or split, each classified as additive, deprecating, or breaking.
3. Reconcile the changes with the version bump, converting any forbidden breaking change into a deprecated alias that resolves to the new field.
4. Apply the naming convention to fields and arguments, keeping type names PascalCase and carrying descriptions across when preservation is on.
5. Write a resolver stub per renamed or added field that delegates the alias to the new resolver, when stubs are enabled.
6. Assemble the migration checklist in deployment order: schema, resolvers, each named client, deprecation announcement, removal date.

## Inputs

- **Existing SDL** (longer free text)
- **Naming convention** (choose one: camelCase, snake_case, PascalCase)
- **Deprecation handling** (choose one: Keep deprecated fields as they are, Mark fields to retire with @deprecated, Remove fields already marked @deprecated)
- **Preserve comments and descriptions** (choose one: Yes, No)
- **Version bump type** (choose one: Patch, Minor, Major)
- **Include resolver stubs for changed fields** (choose one: Include, Omit)
- **Clients that depend on this schema** (free text, e.g. "web app and iOS app and partner integrations")

## Output

A markdown document with the refactored SDL in a graphql block, optional resolver stubs in code blocks, and a migration checklist ordered by deployment step with the version bump stated.

## Prompt template

Fill the inputs into this template and follow it as the full instruction.

### GraphQL Schema Refactoring Tool

Refactor my GraphQL schema and give me the migration checklist to ship it.

#### Details
- Existing SDL: {{Existing SDL}}
- Naming convention: {{Naming convention}}
- Deprecation handling: {{Deprecation handling}}
- Preserve comments and descriptions: {{Preserve comments and descriptions}}
- Version bump type: {{Version bump type}}
- Include resolver stubs for changed fields: {{Include resolver stubs for changed fields}}
- Clients that depend on this schema: {{Clients that depend on this schema}}

Diff before you edit: list every rename, every field to deprecate or remove, and every type to merge or split, and classify each as additive, deprecating, or breaking. Check the classification against the version bump: a patch allows only descriptions and deprecation markers, a minor allows additions and deprecations, and only a major allows removals and renames without an alias. Where the bump forbids a change, keep the old name as a deprecated alias that resolves to the new field. Apply the naming convention to fields and arguments and keep type names PascalCase as the spec convention expects. Carry every comment and description across when preserving is on. When resolver stubs are on, write one per renamed or added field in a neutral style that delegates the alias to the new resolver. Build the checklist in deployment order: schema change, resolver change, client updates per named client, deprecation announcement, removal date.

## Pitfalls

- Renaming a field in a minor release, which is a breaking change for every client that queries the old name.
- Removing a field marked @deprecated last week before clients have had a release cycle to migrate.
- Dropping descriptions during the rewrite, so the documentation tooling loses everything in one commit.
