GitOps Repository Structure Change Review Prompt

This prompt is designed for platform engineering teams that manage multi-environment GitOps repositories using ArgoCD or Flux. The primary job-to-be-done is a pre-merge structural review of changes to repository layouts, kustomization overlays, and sync policies. You should use this prompt when a pull request modifies the inheritance chain between environments (e.g., base, staging, production overlays), reorders sync waves, or alters the promotion path that code follows toward production. The ideal user is a platform engineer or DevOps lead who understands the repository's directory conventions and can provide the full file diff as input, but needs automated assistance to catch structural risks that manual review often misses—such as a production overlay accidentally inheriting a development-only resource or a sync wave reordering that deploys a database migration after the application starts.

Do not use this prompt for reviewing application source code, business logic, or infrastructure-as-code templates like Terraform or CloudFormation. It is not a security scanner, a performance reviewer, or a replacement for unit tests. The prompt is also inappropriate when the repository structure is undocumented or when the reviewer cannot provide the full diff context—without the surrounding file tree and overlay relationships, the model cannot reliably trace inheritance chains. For high-risk production changes, always pair this automated review with a human approval gate. The prompt produces a structured risk report, not a merge decision. Treat its output as a prioritized checklist for the human reviewer, not as an automated gate that blocks or approves PRs without oversight.

Before running this prompt, ensure you have gathered the complete file diff, the repository's directory structure showing overlay relationships, and any team-specific conventions for sync wave ordering or promotion paths. After receiving the structured risk report, map each finding to the specific file and line number provided, verify the inheritance chain analysis against your own understanding of the repository layout, and escalate any finding marked as CRITICAL to a second reviewer. Avoid the temptation to skip human review for low-severity findings—structural risks can compound silently across multiple PRs.

This prompt template is designed to analyze changes to ArgoCD or Flux repository layouts, kustomization overlays, and sync policies. It evaluates promotion path integrity, environment inheritance chain breaks, and automated sync wave ordering risks. The template uses square-bracket placeholders that you replace with your actual diff, repository context, and operational constraints before sending it to the model.

textCopy
You are a GitOps repository structure reviewer. Analyze the provided repository structure diff for risks to promotion path integrity, environment inheritance chains, and sync wave ordering.

## INPUT
[REPOSITORY_DIFF]

## CONTEXT
- Repository Type: [ARGO_CD | FLUX | BOTH]
- Environments: [ENVIRONMENT_LIST]
- Promotion Path: [PROMOTION_PATH_DESCRIPTION]
- Sync Policy: [SYNC_POLICY_DETAILS]
- Organizational Constraints: [ORG_CONSTRAINTS]

## OUTPUT_SCHEMA
Return a JSON object with the following structure:
{
  "summary": "string: one-sentence summary of the change",
  "risk_level": "LOW | MEDIUM | HIGH | CRITICAL",
  "findings": [
    {
      "id": "string: unique finding identifier",
      "severity": "LOW | MEDIUM | HIGH | CRITICAL",
      "category": "PROMOTION_PATH | INHERITANCE_CHAIN | SYNC_ORDER | OVERLAY_CONFLICT | POLICY_VIOLATION",
      "file": "string: affected file path",
      "line_range": "string: line numbers or range",
      "description": "string: what changed and why it matters",
      "impact": "string: potential operational consequence",
      "recommendation": "string: specific fix or mitigation"
    }
  ],
  "promotion_path_impact": {
    "broken_links": ["string: environment names where promotion chain is broken"],
    "orphaned_overlays": ["string: overlay paths no longer referenced"],
    "recommended_order": ["string: correct promotion sequence"]
  },
  "inheritance_analysis": {
    "broken_inheritance": ["string: overlay paths with broken parent references"],
    "unintended_overrides": ["string: values unexpectedly overridden"],
    "missing_inherited_values": ["string: required values not propagated"]
  },
  "sync_wave_analysis": {
    "ordering_conflicts": ["string: resources with conflicting wave annotations"],
    "missing_dependencies": ["string: resources deployed before their dependencies"],
    "recommended_wave_adjustments": ["string: specific wave number changes"]
  },
  "requires_human_review": true | false,
  "human_review_reasons": ["string: specific reasons human review is needed"]
}

## CONSTRAINTS
- Only report findings backed by evidence in the diff.
- Do not flag intentional environment-specific overrides that are documented.
- If a kustomization base reference changes, trace the impact through all overlays.
- Flag any sync wave number changes that could reorder resource creation or deletion.
- For CRITICAL findings, require human review.
- If the diff includes changes to multiple environments, analyze each independently before assessing cross-environment impact.
- Do not hallucinate file paths or resource names not present in the diff.

## EXAMPLES
Example finding for broken promotion path:
{
  "id": "FIND-001",
  "severity": "HIGH",
  "category": "PROMOTION_PATH",
  "file": "overlays/staging/kustomization.yaml",
  "line_range": "L12-L14",
  "description": "Staging overlay now references base from feature branch instead of main, breaking the dev->staging->production promotion chain.",
  "impact": "Staging environment will deploy untested feature branch code, bypassing dev validation.",
  "recommendation": "Revert base reference to main branch and use image tags for feature testing."
}

## RISK_LEVEL
[HIGH]

To adapt this template, replace each square-bracket placeholder with your actual values. For [REPOSITORY_DIFF], include the full git diff of the proposed changes. For [ENVIRONMENT_LIST], list all environments in your promotion chain (e.g., dev, staging, production). The [PROMOTION_PATH_DESCRIPTION] should describe how changes flow between environments. If your organization has specific constraints like naming conventions or required approval gates, include them in [ORG_CONSTRAINTS]. The [RISK_LEVEL] placeholder sets the sensitivity threshold for the review—use HIGH for production-critical repositories.

Before integrating this prompt into your CI/CD pipeline, test it against known safe and breaking changes to calibrate the risk_level threshold. Validate that the JSON output schema is strictly followed by running a schema validator on the model response before surfacing findings to developers. For CRITICAL findings, always route to a human reviewer rather than auto-blocking merges until you have established trust in the prompt's accuracy over multiple review cycles.

This prompt is designed to run as a gating step in a GitOps pipeline, triggered by pull requests that modify repository layout files such as Kustomization overlays, ArgoCD Application manifests, sync wave annotations, or Flux source and kustomization resources. The implementation harness must capture the diff output of the proposed changes, pass it to the model along with the repository context, and enforce structured output validation before the pipeline can proceed. The prompt expects a complete picture of the promotion path, so the harness should assemble the full overlay inheritance chain—base, staging, production—even if the diff only touches one environment. Without this context, the model cannot reliably detect environment inheritance breaks or sync wave ordering conflicts.

Wire the prompt into a GitHub Actions, GitLab CI, or Jenkins pipeline step that runs after the PR is opened and before merge is allowed. The step should: (1) compute the git diff for the changed files, (2) resolve the full kustomization or Application tree by walking parent directories or fetching referenced bases, (3) assemble the [REPO_STRUCTURE_CONTEXT] with the directory tree, overlay relationships, and sync policy annotations, (4) call the model API with the prompt template and structured output schema, (5) validate the JSON response against the expected schema—rejecting missing severity fields, invalid enum values, or findings without file references—and (6) post the validated findings as a PR comment with a summary status check. If validation fails, retry once with the validation errors injected into the [CONSTRAINTS] block. If the retry also fails, fail the check and require human review. For high-risk environments, always require a human approval step on findings with severity 'critical' or 'high' before the PR can merge.

Model choice matters here. Use a model with strong structured output support and a large context window, as the assembled repository context can be substantial. Claude 3.5 Sonnet or GPT-4o with strict JSON mode are good defaults. Set temperature to 0 to minimize variance in severity classification. Log every model call—including the full prompt, response, validation result, and retry attempts—to your observability platform for trace analysis and prompt regression testing. Avoid running this prompt on every commit; gate it on PRs that touch paths matching **/kustomization.yaml, **/argo-app.yaml, **/flux-kustomization.yaml, or **/sync-policy.yaml to control cost and latency. The next step after implementation is building a regression test suite with known-good and known-bad repository structure changes to catch prompt drift before it reaches production.