Quickstart Version Pinning Prompt Template

This prompt is for SDK and platform engineers who need to generate quickstart instructions that lock dependencies to specific, tested versions. The core job-to-be-done is preventing future breakage for new users by ensuring that package manager commands, import statements, and environment configurations reference exact version numbers rather than floating tags or ranges. The ideal user is a documentation engineer or DevRel professional who understands that a quickstart's primary value is time-to-first-success, and that an unpinned dependency breaking silently destroys that value. Required context includes the target language ecosystem, the current stable versions of all SDKs and tools, and the minimum supported platform versions.

Use this prompt when you are authoring or regenerating a getting-started guide for a public-facing API, SDK, or developer tool. It is particularly valuable before a major release, during a dependency upgrade cycle, or when onboarding data shows that environment setup errors are the top failure mode. Do not use this prompt for internal scripts, one-off prototypes, or documentation for pre-release alpha software where version surfaces are intentionally unstable. The prompt is also inappropriate for generating conceptual overviews or architecture docs; it is strictly for actionable, copy-pasteable setup instructions.

The prompt requires you to supply the current stable version matrix, the target package registries, and any known deprecation timelines. If you cannot provide this information, the output will be generic and potentially harmful. Before using the generated output, validate that every pinned version resolves correctly in a clean environment and that the upgrade guidance includes a clear path to the next breaking change. The next step after reading this section is to gather your version matrix and prepare the [DEPENDENCY_MAP] input.

This prompt template is designed for SDK and platform engineers who need to generate quickstart instructions that lock dependencies to specific versions. The goal is to prevent future breakage caused by unpinned or floating version ranges. The template takes a target SDK, API version, and tooling context as input and produces a set of version constraints, installation commands, and a brief rationale for each pinned version. It also includes upgrade guidance so the quickstart remains maintainable.

codeCopy
You are a technical documentation engineer specializing in SDK and API quickstart guides. Your task is to generate version-pinned dependency instructions for a new developer onboarding guide.

## Required Inputs
- [SDK_NAME]: The name of the primary SDK or client library.
- [API_VERSION]: The target API version (e.g., v2, 2024-01-01).
- [LANGUAGE]: The programming language for the quickstart.
- [TOOLING]: A list of required tools, package managers, or runtimes.
- [MINIMUM_STABILITY]: The minimum stability level (e.g., stable, beta, preview).

## Output Schema
Return a JSON object with the following structure:
{
  "sdk_version": "<exact version string>",
  "api_version": "<exact version string>",
  "dependencies": [
    {
      "name": "<dependency name>",
      "version": "<exact version constraint>",
      "install_command": "<package manager command>",
      "rationale": "<one-sentence reason for pinning>"
    }
  ],
  "runtime_requirement": "<version constraint for language runtime>",
  "upgrade_guidance": "<how to check for newer versions and safely upgrade>"
}

## Constraints
- Pin all dependencies to exact versions (e.g., "1.2.3", not "^1.2.3" or "~1.2.3").
- Use the package manager conventions for [LANGUAGE] (e.g., pip for Python, npm for JavaScript, maven for Java).
- If a dependency is in beta or preview, include a clear stability warning.
- The upgrade_guidance field must include a command to check for newer versions and a note about reading changelogs before upgrading.
- Do not include any placeholder text in the output; all fields must be concrete.
- If you cannot determine a stable version for a required dependency, set the version to "UNKNOWN" and add a warning to the rationale.

## Examples
Input: SDK_NAME="acme-python", API_VERSION="2024-01-01", LANGUAGE="python", TOOLING="pip, python>=3.9", MINIMUM_STABILITY="stable"
Output:
{
  "sdk_version": "1.5.2",
  "api_version": "2024-01-01",
  "dependencies": [
    {
      "name": "acme-python",
      "version": "1.5.2",
      "install_command": "pip install acme-python==1.5.2",
      "rationale": "Latest stable release with support for API version 2024-01-01."
    },
    {
      "name": "requests",
      "version": "2.31.0",
      "install_command": "pip install requests==2.31.0",
      "rationale": "Pinned to avoid breaking changes in HTTP library behavior."
    }
  ],
  "runtime_requirement": ">=3.9,<3.13",
  "upgrade_guidance": "Run 'pip list --outdated' to check for newer versions. Review the acme-python changelog at https://example.com/changelog before upgrading. Test your integration in a sandbox environment after any version bump."
}

## Risk Level
[RISK_LEVEL]: Set to "high" if any dependency is in beta or if the API version is deprecated; otherwise "low".

To adapt this template, replace the square-bracket placeholders with your specific SDK, API version, language, and tooling context. The output is structured JSON, making it easy to integrate into a documentation pipeline or a CI/CD check that validates quickstart accuracy. For high-risk outputs where a dependency version is unknown or unstable, route the result for human review before publication. Test the generated install commands in a clean environment to confirm they produce a working setup.

This prompt is designed to be called programmatically as part of a documentation build or release workflow, not as a one-off chat interaction. The primary integration point is a CI/CD pipeline that triggers when a new SDK or API version is tagged. The application layer should supply the [PACKAGE_NAME], [CURRENT_VERSION], [LANGUAGE_ECOSYSTEM], and [KNOWN_BREAKING_CHANGES] variables from a release manifest or package registry query. The model's output must be treated as a draft that requires structural validation before it can be merged into the public quickstart guide.

After receiving the model response, the harness must run a strict schema validator against the output. The expected schema includes a pinned_dependencies array where each object has package, version, constraint_operator, and rationale fields, plus a deprecation_notes array and an upgrade_guidance string. If the output fails JSON schema validation, the harness should retry once with the validation error appended to the [CONSTRAINTS] field. If the second attempt also fails, the workflow must escalate to a human reviewer via a pull request comment rather than silently falling back to unpinned instructions. For model choice, use a model with strong JSON mode support (e.g., GPT-4o with response_format set to json_schema or Claude 3.5 Sonnet with tool-use extraction) to minimize malformed output.

Logging should capture the prompt version hash, the input variables, the raw model output, the validation result, and the final published snippet for auditability. Do not log secrets if [PACKAGE_REGISTRY_URL] includes authentication tokens. The eval suite for this prompt should include test cases for: a simple semver pin, a package with a known CVE requiring an upper bound exclusion, a pre-release version, and a scenario where no breaking changes are known. Each test case must assert that the output contains no unpinned or latest references and that every constraint operator is valid for the target ecosystem's package manager. Before enabling auto-merge, run the eval suite against the prompt and require 100% pass on the reproducibility and deprecation-awareness checks.