Environment Setup Guide Generation Prompt Template

This prompt is designed for developer experience engineers and platform teams who need to reduce the time-to-first-commit for new developers. Its job is to generate a validated, step-by-step local development environment setup guide by analyzing dependency manifests (like package.json, requirements.txt, or go.mod), environment configuration files (.env.example, docker-compose.yml), and setup scripts (Makefile, bootstrap.sh). The ideal user is someone who needs to turn the implicit tribal knowledge embedded in these files into an explicit, executable, and testable onboarding document.

You should use this prompt when you have a repository with a standard set of build and dependency files but lack a human-verified setup guide, or when the existing guide has drifted from the actual configuration. It is most effective when the repository uses common package managers and task runners. The prompt requires you to provide the raw contents of these files as input; it cannot scan the repository itself. The output is a structured guide with prerequisite checks, ordered installation steps, and a troubleshooting section for common failures.

Do not use this prompt for repositories that rely heavily on proprietary internal toolchains not expressed in standard manifest files, or for environments requiring manual license key activation, hardware-specific drivers, or VPN-only resource access that cannot be inferred from the provided configuration. This prompt is also not a substitute for a full CI/CD pipeline definition. If the setup involves sensitive credentials, ensure those are redacted from the input before processing. For high-risk production environments, always require a human reviewer to validate the generated guide against a clean machine before distributing it to the team.

This prompt template generates a step-by-step local development environment setup guide by analyzing dependency manifests, environment configuration files, setup scripts, and tool version constraints found in the repository. The template is designed to be wired into a coding agent or developer tool pipeline where the model has access to repository files. It produces structured output with prerequisite checks, ordered installation steps, verification commands, and troubleshooting guidance. Use this template when you need to reduce time-to-first-commit for new team members or when onboarding documentation has drifted from the actual toolchain.

textCopy
You are an environment setup documentation generator. Your task is to produce a validated, step-by-step local development setup guide from the repository context provided.

## INPUTS
- Repository files: [REPOSITORY_FILES]
- Dependency manifests: [DEPENDENCY_MANIFESTS]
- Environment configuration files: [ENV_CONFIG_FILES]
- Setup scripts: [SETUP_SCRIPTS]
- Tool version constraints: [TOOL_VERSION_CONSTRAINTS]
- Target operating system: [TARGET_OS]
- Existing documentation to reconcile: [EXISTING_DOCS]

## OUTPUT SCHEMA
Return a JSON object with this exact structure:
{
  "guide_title": "string",
  "target_os": "string",
  "prerequisites": [
    {
      "tool": "string (name and minimum version)",
      "check_command": "string (shell command to verify installation)",
      "install_url": "string (official download link)",
      "required": true
    }
  ],
  "setup_steps": [
    {
      "step_number": 1,
      "description": "string (what this step accomplishes)",
      "commands": ["string (exact shell command)"],
      "expected_output": "string (what success looks like)",
      "verification": "string (how to confirm the step worked)",
      "failure_remediation": "string (what to do if this step fails)"
    }
  ],
  "environment_variables": [
    {
      "name": "string",
      "purpose": "string",
      "example_value": "string",
      "required": true,
      "source_file": "string (which config file defines it)"
    }
  ],
  "verification_checks": [
    {
      "check": "string (end-to-end verification command)",
      "expected_result": "string"
    }
  ],
  "common_issues": [
    {
      "symptom": "string",
      "likely_cause": "string",
      "resolution_steps": ["string"]
    }
  ],
  "source_evidence": [
    {
      "claim": "string (what the guide asserts)",
      "source_file": "string (file path that supports this claim)",
      "source_excerpt": "string (relevant line or block)"
    }
  ]
}

## CONSTRAINTS
[CONSTRAINTS]

## EXAMPLES
[EXAMPLES]

## INSTRUCTIONS
1. Extract all dependency requirements from [DEPENDENCY_MANIFESTS] and [TOOL_VERSION_CONSTRAINTS]. Do not assume any tool is installed.
2. Derive the correct installation order from dependency relationships. A tool must be installed before anything that depends on it.
3. Every command must be copy-paste ready for [TARGET_OS]. Use absolute paths only when they appear in the repository configuration.
4. Every setup step must include a verification command that confirms the step succeeded before proceeding.
5. Cross-reference [EXISTING_DOCS] against actual repository files. Flag any discrepancies in the source_evidence array.
6. If a setup script exists in [SETUP_SCRIPTS], explain what it does and when to run it. Do not assume it works without verification.
7. For each environment variable, cite the exact file and line where it is defined or referenced.
8. Common issues must be derived from error handling patterns in setup scripts and configuration, not invented.
9. If you cannot determine a required version from the repository context, mark it as "unknown" and flag it in source_evidence.
10. Do not include steps for tools or services not referenced in the provided repository files.

Adapt this template by replacing each square-bracket placeholder with actual repository context before sending it to the model. The [CONSTRAINTS] placeholder should contain team-specific rules such as required tool versions, security policies, or platform restrictions. The [EXAMPLES] placeholder should include one or two well-formed setup guides from similar repositories to establish the expected tone and level of detail. For production use, wrap this prompt in a harness that validates the output JSON against the schema before surfacing it to users. If the model produces steps that cannot be traced back to a source file, flag the output for human review rather than publishing it.

This prompt is designed to be embedded in a developer onboarding pipeline, not used as a one-off chat interaction. The typical integration point is a CI/CD job, a CLI tool, or an internal developer portal that triggers guide generation when a new repository is registered or when dependency manifests change. The application layer is responsible for assembling the required inputs: dependency manifests (package.json, requirements.txt, go.mod, Cargo.toml, etc.), environment configuration files (.env.example, docker-compose.yml, .tool-versions), setup scripts (Makefile targets, bootstrap.sh, bin/setup), and any existing README or CONTRIBUTING.md that may contain partial setup instructions. These inputs should be gathered by a pre-processing step that walks the repository tree, reads relevant files, and concatenates them into the [REPOSITORY_CONTEXT] placeholder with clear file-path headers so the model can reference specific sources in its output.

The output must pass through a structured validation layer before being surfaced to the developer. Parse the generated markdown into sections (prerequisites, step-by-step instructions, verification, troubleshooting) and run the following checks: (1) every command in the guide must be extractable and testable in a sandbox or dry-run mode—flag any command that references unlisted prerequisites or assumes global tooling not declared in the prerequisites section; (2) step ordering must be validated by building a dependency graph from the guide's steps and checking for topological consistency—a step that requires a database must not appear before the database setup step; (3) prerequisite coverage must be cross-referenced against the dependency manifests—if package.json declares a Node version in engines, the guide must include a Node.js version prerequisite. Log validation failures with the specific step, the violated rule, and the source evidence so the team can debug false positives. For high-risk production environments, route guides with validation failures to a human review queue rather than auto-publishing.

Model choice matters here. Use a model with strong instruction-following and long-context handling (such as Claude 3.5 Sonnet or GPT-4o) because the prompt requires reasoning across multiple configuration files and maintaining consistency between prerequisites, steps, and troubleshooting sections. Set temperature to 0 or a low value (0.1–0.2) to reduce variability in command generation. Implement a retry strategy: if validation fails, feed the specific validation errors back into the prompt as [PREVIOUS_OUTPUT] and [VALIDATION_ERRORS] and request a targeted fix rather than full regeneration. Limit retries to 2 attempts before escalating to human review. Store every generation attempt, its validation results, and the final approved guide in a versioned artifact store so onboarding engineers can trace why a particular setup instruction exists and when it was last regenerated.