API Endpoint Change Impact Assessment Prompt Template

This prompt is designed for integration test engineers and platform developers who need to assess the downstream impact of a change to an API endpoint. The core job-to-be-done is to take a diff of an OpenAPI or GraphQL schema and produce a structured, actionable impact report. The ideal user is someone responsible for maintaining contract test suites, managing API versioning, or preventing breaking changes from reaching consumers. They need to quickly understand which integration tests, contract tests, and downstream services are affected by a proposed schema modification.

The prompt requires a specific, machine-readable input: a unified diff or a before-and-after snapshot of an API specification. Without this concrete input, the assessment will be speculative and unreliable. The output must be highly structured, classifying changes as breaking, additive, or deprecating, and mapping each change to specific test suites or consumer endpoints. This is not a prompt for general code review or architectural hand-waving; it's a precision tool for a controlled, schema-driven workflow. It assumes the existence of a known test inventory and a defined set of downstream consumers to reference.

Do not use this prompt for assessing changes to internal implementation logic that do not alter the API contract. It is also unsuitable for initial API design brainstorming or for generating net-new test cases from scratch. The primary value is in the rapid, repeatable triage of a known change against a known system. Before using this prompt, ensure you have a clean schema diff, a list of registered downstream consumers, and a catalog of existing contract and integration tests. The output should be treated as a high-quality recommendation that still requires human verification, especially for classifying the severity of breaking changes and the associated semantic versioning implications.

This prompt template is designed to be copied directly into your AI harness, test pipeline, or review workflow. It accepts an API specification diff (OpenAPI or GraphQL), a list of existing integration tests, and a consumer registry as inputs. The model is instructed to produce a structured impact assessment that classifies breaking changes, identifies affected contract tests, and warns about downstream consumer impact. All placeholders are enclosed in square brackets and must be replaced with real data before execution.

textCopy
You are an integration test impact analyst. Your task is to assess the impact of an API specification change on existing tests and downstream consumers.

## INPUTS

### API Specification Diff
[OPENAPI_OR_GRAPHQL_DIFF]

### Existing Integration Test Catalog
[TEST_CATALOG]

### Downstream Consumer Registry
[CONSUMER_REGISTRY]

### Risk Threshold
[RISK_LEVEL]

## OUTPUT SCHEMA

Return a JSON object with the following structure:
{
  "breaking_changes": [
    {
      "location": "string (path, operation, field)",
      "change_type": "enum: REMOVED_FIELD | CHANGED_TYPE | REMOVED_ENDPOINT | ADDED_REQUIRED | CHANGED_CONSTRAINT | REMOVED_ENUM_VALUE",
      "severity": "enum: CRITICAL | HIGH | MEDIUM | LOW",
      "semver_impact": "enum: MAJOR | MINOR | PATCH",
      "description": "string"
    }
  ],
  "affected_tests": [
    {
      "test_id": "string",
      "test_name": "string",
      "impact_reason": "string",
      "recommended_action": "enum: UPDATE | RETIRE | SPLIT | RERUN",
      "priority": "integer 1-10"
    }
  ],
  "consumer_impact_warnings": [
    {
      "consumer_name": "string",
      "affected_endpoints": ["string"],
      "breaking": "boolean",
      "migration_notes": "string"
    }
  ],
  "semver_recommendation": "string (MAJOR | MINOR | PATCH)",
  "risk_summary": "string",
  "untested_surfaces": ["string (paths or operations with no matching tests)"]
}

## CONSTRAINTS
- Classify every diff entry as breaking or non-breaking before assessing test impact.
- If a removed field has no test coverage, flag it in `untested_surfaces`.
- For each affected test, explain why it is impacted by a specific diff entry.
- If the diff includes a new required field, mark all existing request-building tests as affected.
- Do not invent test IDs or consumer names not present in the input catalogs.
- If the consumer registry is empty, set `consumer_impact_warnings` to an empty array and note the limitation in `risk_summary`.
- If [RISK_LEVEL] is HIGH, flag any untested breaking change as CRITICAL severity.

## EXAMPLES

### Example Input Diff (truncated)
- Removed field `middleName` from `PATCH /users/{id}` request body.
- Changed type of `amount` from `integer` to `float` in `POST /invoices` response.

### Example Output
{
  "breaking_changes": [
    {
      "location": "PATCH /users/{id} request body: middleName",
      "change_type": "REMOVED_FIELD",
      "severity": "HIGH",
      "semver_impact": "MAJOR",
      "description": "Field middleName removed from update payload. Clients sending this field will receive an error or it will be silently ignored depending on server strictness."
    }
  ],
  "affected_tests": [
    {
      "test_id": "TC-402",
      "test_name": "Update user full name with middle name",
      "impact_reason": "Test sends middleName in request body which is now removed.",
      "recommended_action": "UPDATE",
      "priority": 8
    }
  ],
  "consumer_impact_warnings": [
    {
      "consumer_name": "mobile-app-v3",
      "affected_endpoints": ["PATCH /users/{id}"],
      "breaking": true,
      "migration_notes": "Remove middleName from update payloads before upgrading. Coordinate deployment with API version header change."
    }
  ],
  "semver_recommendation": "MAJOR",
  "risk_summary": "One breaking change detected. One test affected. One consumer requires migration.",
  "untested_surfaces": []
}

## INSTRUCTIONS
1. Parse the diff to identify all added, removed, or modified endpoints, fields, parameters, types, and constraints.
2. For each change, determine if it is breaking according to semantic versioning rules.
3. Cross-reference breaking changes against the test catalog to identify affected tests.
4. Cross-reference all changes against the consumer registry to identify impacted consumers.
5. Produce the output JSON strictly following the schema above.
6. If no breaking changes exist, set `semver_recommendation` to PATCH or MINOR as appropriate.

To adapt this template, replace each bracketed placeholder with data from your pipeline. The [OPENAPI_OR_GRAPHQL_DIFF] should be a structured diff, not a raw git diff—tools like openapi-diff or GraphQL Inspector produce suitable input. The [TEST_CATALOG] should include test IDs, names, and the endpoints or schemas each test exercises. The [CONSUMER_REGISTRY] should list known API consumers and the endpoints they depend on. If you lack a formal registry, substitute a best-effort list derived from API gateway logs or team documentation, and set [RISK_LEVEL] to HIGH to force conservative impact assessment.

Before deploying this prompt into an automated CI pipeline, validate the output against a golden dataset of known diffs and expected assessments. Common failure modes include misclassifying additive changes as breaking, missing transitive consumer impact when an internal endpoint changes, and producing test IDs that do not exist in the input catalog. Add a post-processing validation step that rejects any output where affected_tests references unknown test IDs or where breaking_changes is empty but semver_recommendation is MAJOR. For high-risk API surfaces, route the assessment to a human reviewer before blocking a release gate.

This prompt is designed to be called programmatically within a CI/CD pipeline, triggered by a pull request that modifies an OpenAPI specification, GraphQL schema, or gRPC protobuf file. The primary integration point is a GitHub Action, GitLab CI job, or a custom webhook that detects a schema diff. The application layer should extract the raw diff using a command like git diff origin/main -- openapi.yaml and pass it as the [SCHEMA_DIFF] input. Do not pass the entire specification file; the model performs best when it focuses on the precise lines that changed, which keeps the context window small and the analysis sharp.

Before calling the LLM, the harness must validate the input. Check that the [SCHEMA_DIFF] is not empty and that it matches a recognized specification format. If the diff is empty or unparseable, the pipeline should exit early with a clear status message. After receiving the model's JSON output, a post-processing validator must confirm the response conforms to the expected schema: a list of objects, each with affected_test, test_type, impact_severity, breaking_change, and rationale fields. If the JSON is malformed, implement a single retry with a repair prompt that includes the raw output and the validation error. If the retry also fails, the pipeline should fail open by flagging the PR with a manual review label and posting the raw model output as a comment for a human to interpret.

For high-reliability environments, route the prompt to a model with strong JSON mode and reasoning capabilities, such as gpt-4o or claude-3-5-sonnet. Set temperature=0 to maximize deterministic, repeatable assessments. Log the full prompt, the diff, and the model's response to your observability platform as a structured trace. This creates an audit trail linking a specific commit's schema change to the generated impact assessment. The final step in the harness should convert the validated JSON output into actionable tasks: post the breaking change warnings as a PR comment, create a Jira ticket for each high severity item, and generate a dynamic test run command that executes only the affected test suites identified in the affected_test fields. Avoid the temptation to automatically skip tests based on this assessment; the output is a recommendation for a human release manager or SDET to approve, not an autonomous gate.