API Change Exploration Charter Prompt

This prompt is designed for integration testers and QA leads who need to generate time-boxed exploratory test charters when an API contract, endpoint, or schema changes. The core job-to-be-done is converting a concrete change artifact—such as an OpenAPI diff or a structured changelog—into a set of investigation missions. These missions target backward compatibility breaks, error handling gaps, parameter edge cases, and downstream consumer impact. The ideal user has access to the before-and-after API specifications and needs to structure unscripted testing into mission-driven sessions before the change reaches production.

To use this prompt effectively, you must provide a structured [API_CHANGE_INPUT] that captures the delta between two API versions. This input should include modified endpoints, added or removed fields, changed validation rules, and deprecated parameters. The prompt works best when the change is non-trivial and carries integration risk—for example, a breaking change to a payment API's required fields or a new error response format in a user-facing service. The output is a set of charters, each containing a mission statement, investigation targets, oracle heuristics, and a time budget. You should review the generated charters for relevance and adjust the time allocations based on your team's context before starting a session.

Do not use this prompt for general API smoke testing or for generating automated contract test scripts; those tasks belong in the API and Contract Test Generation playbook. Similarly, if you lack a concrete diff and only have a high-level feature description, the Change-Based Exploration Charter Prompt is a better starting point. This prompt is also not a substitute for security-focused testing—if your primary concern is authentication bypass or privilege escalation, use the Authentication and Authorization Boundary Charter Prompt. After generating charters with this prompt, the next step is to execute them in time-boxed sessions and capture findings using the Exploratory Session Note-Taking Scaffold Prompt Template to ensure the investigation record is complete and auditable.

This prompt template converts an API change artifact—such as an OpenAPI diff, changelog, or release notes—into a structured exploratory test charter. The charter is designed for a time-boxed testing session and includes a clear mission, investigation targets, oracle heuristics, and risk areas. Replace every square-bracket placeholder with concrete values before execution. The prompt expects a detailed diff or changelog as the primary input; without it, the generated charter will be vague and untestable.

codeCopy
You are an exploratory test architect specializing in API change analysis. Your task is to produce a time-boxed exploratory test charter based on a provided API diff or changelog. The charter must guide a tester to investigate backward compatibility, error handling, parameter edge cases, and consumer impact.

## INPUT
[API_CHANGE_DETAIL]

## CONSTRAINTS
- The session is time-boxed to [SESSION_DURATION_MINUTES] minutes.
- Focus exclusively on the changed endpoints, schemas, parameters, and status codes described in the input.
- Do not propose testing unchanged parts of the API.
- The charter must be specific enough that a tester unfamiliar with the change can execute it.
- If the input is insufficient to generate a meaningful charter, respond with a list of clarifying questions instead of a weak charter.

## OUTPUT SCHEMA
Return a JSON object with the following structure:
{
  "charter_id": "string",
  "mission": "A one-sentence mission statement describing the goal of the session.",
  "time_box_minutes": number,
  "change_summary": "A 2-3 sentence summary of the API changes under investigation.",
  "investigation_targets": [
    {
      "target": "Description of a specific area, endpoint, or behavior to investigate.",
      "risk": "The risk being probed (e.g., backward compatibility break, missing validation).",
      "oracle_heuristic": "How the tester will recognize a problem (e.g., 'Status 200 on a request that should return 422')."
    }
  ],
  "test_data_suggestions": ["List of payloads, parameter values, or scenarios to try."],
  "consumer_impact_notes": "Notes on which API consumers are likely affected and how.",
  "follow_up_charter_ideas": ["Ideas for subsequent charters if this session finds issues."]
}

## EXAMPLES
[OPTIONAL_FEW_SHOT_EXAMPLES]

## RISK LEVEL
[RISK_LEVEL]

Adaptation notes: Replace [API_CHANGE_DETAIL] with the full text of your OpenAPI diff, changelog, or release notes. Set [SESSION_DURATION_MINUTES] to a realistic time box (e.g., 60 or 90). Use [OPTIONAL_FEW_SHOT_EXAMPLES] to include 1-2 example charters if the model needs additional guidance on the desired specificity. Set [RISK_LEVEL] to high, medium, or low to adjust the intensity of the investigation targets. If the API change involves regulated data or payment flows, always set risk to high and require human review of the generated charter before execution. For production use, validate the output JSON against the schema and reject any response that omits required fields or contains vague targets like "test everything."

This prompt is designed to be called programmatically as part of a CI/CD pipeline or a QA sprint planning tool. The primary input is an OpenAPI diff or changelog, which should be pre-processed into a structured text block before being injected into the [OPENAPI_DIFF] placeholder. The system should also inject a [RISK_CONTEXT] string derived from recent production incidents or feature flags to focus the exploration. The output is a structured JSON object containing an array of charters, each with a mission, investigation targets, and oracle heuristics. The application layer must parse this JSON to create tickets in a test management system like Xray or TestRail.

To ensure reliability, implement a validation layer that checks the JSON schema before accepting the output. If the model returns malformed JSON, use a retry loop with a repair prompt that includes the raw output and the validation error message. Limit retries to three attempts before escalating to a human QA lead for manual charter creation. Log every prompt version, input diff hash, raw output, and validation result to an observability platform for auditability. For high-risk API changes (e.g., payment or authentication endpoints), the workflow should route the generated charters to a human for approval before they are assigned to testers.

Model choice matters here. Use a model with strong JSON mode and a large context window to handle extensive OpenAPI diffs. If the diff is too large, pre-process it by extracting only the changed paths, parameters, and schemas. Do not use this prompt for trivial changes like description text updates; implement a pre-filter that skips the prompt if the diff contains no structural or schema modifications. The final step should always be a human review of the charter's scope and risk alignment before the exploratory session begins.