Auth Migration Guide Prompt Template

This prompt is designed for platform and security engineering teams who need to produce a step-by-step migration guide when transitioning between authentication systems. Use it when you are moving from API keys to OAuth 2.0, from opaque session tokens to JWTs, or between any two distinct auth schemes. The prompt forces the model to structure the guide around a strict before/after comparison, enumerate every breaking change, and provide explicit rollback procedures. It is not a general-purpose documentation writer. It assumes you have already decided on the target architecture and can supply concrete endpoint details, token formats, and error mappings. The output is a draft for human review, not a publishable final document.

Before using this prompt, gather the specific artifacts the model needs: the current auth scheme specification, the target auth scheme specification, a list of every affected endpoint, the exact token format changes, and the error code mappings from old to new. Without these concrete inputs, the model will generate plausible but incorrect migration steps. The prompt includes placeholders for [CURRENT_AUTH_SPEC], [TARGET_AUTH_SPEC], [AFFECTED_ENDPOINTS], [TOKEN_FORMAT_CHANGE], and [ERROR_MAPPING]. Fill every placeholder with real data. If you cannot fill a placeholder, you are not ready to use this prompt. The model will produce a structured guide with sections for overview, breaking changes, before/after code samples, client impact assessment, rollback procedures, and a migration checklist.

Do not use this prompt when you are still deciding between auth architectures, when you lack endpoint-level detail, or when you need a general security explainer. The prompt is also unsuitable for generating end-user-facing login instructions or marketing copy about auth improvements. After the model produces a draft, a security engineer must review every code sample for correctness, verify that no hardcoded secrets appear in examples, and confirm that the rollback procedure actually restores the previous state without data loss. Run the output through the companion Auth Documentation Completeness Audit prompt to catch missing error codes, stale references, or contradictory instructions before publication.

This prompt template is designed to produce a complete, actionable migration guide for transitioning between authentication systems. It forces the model to structure the output around concrete code changes, a detailed breaking change catalog, and explicit rollback steps—moving beyond vague advice to implementation-ready documentation. Use this template when you have a defined source and target auth system and need a guide that downstream engineering teams can execute against.

codeCopy
You are a senior platform security engineer writing an internal migration guide for engineering teams. Your task is to produce a complete, step-by-step migration document that moves a service from [SOURCE_AUTH_SYSTEM] to [TARGET_AUTH_SYSTEM].

The migration guide must be structured as follows:

## 1. Executive Summary
- One paragraph explaining the business and security rationale for this migration.
- State the [MIGRATION_DEADLINE] and any hard cut-off dates.

## 2. Breaking Changes Catalog
- Enumerate every breaking change in a table with columns: Change, Impact, Mitigation Required, and Affected Clients.
- Include changes to: token formats, header names, endpoint URLs, scope strings, error response bodies, and SDK method signatures.

## 3. Before/After Code Samples
- For each breaking change, provide a concrete code example in [TARGET_LANGUAGE] showing the old pattern and the new pattern.
- Include complete request/response pairs where relevant.
- Show error handling for the new auth flow, including token refresh and invalid credential scenarios.

## 4. Step-by-Step Migration Procedure
- Provide numbered steps that an engineering team can follow in order.
- Each step must include: what to change, how to verify the change, and how to roll back if it fails.
- Cover: dependency updates, configuration changes, code refactoring, testing, staged rollout, and monitoring.

## 5. Rollback Plan
- Provide explicit rollback procedures for each migration step.
- Include criteria for triggering a rollback (e.g., elevated 401 rates, token refresh failures, scope escalation errors).
- Specify how to revert configuration, code, and infrastructure changes.

## 6. Client Impact Assessment
- List all internal and external client types affected by this migration.
- For each client type, describe the required changes, communication timeline, and support contacts.
- Include a checklist for verifying each client type has completed migration.

## 7. Testing and Validation
- Provide a test plan with specific test cases covering: happy path auth, token expiry, scope validation, error responses, and concurrent sessions.
- Include commands or scripts that can be run to validate the migration in a staging environment.

## Constraints
- All code samples must be in [TARGET_LANGUAGE] and must compile or run without syntax errors.
- Do not use placeholder credentials or hardcoded secrets in code samples. Use environment variables or config references.
- Every breaking change must be documented. Do not omit changes that seem minor.
- If the migration involves multiple client SDKs, address each one explicitly.
- Flag any security-sensitive steps (e.g., secret rotation, token signing key changes) with a ⚠️ SECURITY marker.

## Input Context
[SOURCE_AUTH_SYSTEM]: [SOURCE_DESCRIPTION]
[TARGET_AUTH_SYSTEM]: [TARGET_DESCRIPTION]
[TARGET_LANGUAGE]: [LANGUAGE]
[MIGRATION_DEADLINE]: [DEADLINE]
[ADDITIONAL_CONTEXT]: [ANY_OTHER_RELEVANT_DETAILS]

Before executing this prompt, replace every square-bracket placeholder with concrete values. The [SOURCE_DESCRIPTION] and [TARGET_DESCRIPTION] should include specifics like grant types, token formats, endpoint base URLs, and SDK versions. If the migration spans multiple services or client libraries, include that scope in [ADDITIONAL_CONTEXT]. After generating the guide, run a completeness check: verify that every breaking change in the catalog has a corresponding before/after code sample and a rollback step. For high-risk migrations involving payment systems, user data, or compliance boundaries, route the generated guide through a human security review before publication.

The Auth Migration Guide prompt is designed to be embedded in a documentation generation pipeline, not used as a one-off chat interaction. The primary integration point is a CI/CD workflow triggered by a pull request that introduces an auth system change. When the PR is labeled with auth-migration, a script extracts the diff, the old and new auth configuration schemas, and any migration notes from the PR body. These become the [SOURCE_DIFF], [OLD_AUTH_SCHEMA], [NEW_AUTH_SCHEMA], and [MIGRATION_NOTES] inputs. The prompt is then invoked via the model API, and the resulting markdown is committed to a drafts/ directory for review before publication.

The implementation must include a validation layer that checks the model's output before it reaches a human reviewer. After the prompt returns, run a structured validation script that confirms: (1) every breaking change mentioned in the source diff appears in the output's 'Breaking Changes' section, (2) all code blocks are syntactically valid for the declared [TARGET_LANGUAGE], (3) the output contains a non-empty 'Rollback Procedure' section, and (4) no placeholder tokens remain unresolved. If validation fails, retry the prompt once with the validation errors appended to the [CONSTRAINTS] field. If the second attempt also fails, route the output to a human writer queue with the validation report attached. Log every attempt, the model used, the token counts, and the validation results for auditability.

Model selection matters here. Use a model with strong instruction-following and long-context handling, such as claude-sonnet-4-20250514 or gpt-4o, because the combined source material often exceeds 8K tokens. Set the temperature to 0.2 to balance factual consistency with the slight variability needed for natural prose. Do not use a tool-calling or agentic loop for this prompt; it is a single-turn generation task. The output should be written directly to a markdown file and never automatically published. A technical writer or the PR author must approve the draft before it goes live. For high-risk migrations (e.g., changing token formats or removing grant types), add a second human review step and require sign-off from a security engineer.