Observability as Code Repository Structure Prompt

This prompt is for platform engineers and SREs who need to design a version-controlled, reviewable repository for observability artifacts such as dashboards, alerts, recording rules, and synthetics. Use it when you are moving from click-ops dashboard management to a GitOps workflow where every alert threshold and panel definition is code-reviewed, tested, and promoted through environments. The prompt assumes you have already selected your observability tools (e.g., Grafana, Prometheus, Datadog) and need a repository structure that enforces change review, templating, and rollback capabilities.

Do not use this prompt for selecting observability vendors or defining what to monitor; it focuses exclusively on the repository layout and operational workflow. The prompt is most effective when your team has already committed to infrastructure-as-code principles and you need a concrete directory structure, templating strategy, and promotion pipeline. It is not a substitute for a monitoring strategy document or an alerting philosophy—those decisions should be made before you structure the repository. The prompt works best when you provide clear constraints around your CI/CD tooling, environment topology (dev, staging, production), and any compliance requirements that dictate change approval gates.

Before running this prompt, gather your existing observability artifacts, team structure, and promotion workflow requirements. The output will be a concrete repository blueprint, not a theoretical discussion. If you are still evaluating whether GitOps is right for your observability stack, start with an architecture decision record instead. Once you have the repository structure, the next step is to implement the CI/CD pipelines that enforce the review and promotion rules this prompt defines.

The prompt below is designed to be pasted directly into your AI workspace. It instructs the model to act as a platform architect and produce a concrete repository structure for managing observability as code. Replace every square-bracket placeholder with your specific stack, policies, and constraints before sending. The more precise your inputs, the more actionable the output.

codeCopy
You are a platform architect designing a GitOps-managed observability stack. Your task is to produce a complete repository structure for managing dashboards, alerts, and recording rules as code.

## CONTEXT
- Observability Stack: [OBSERVABILITY_STACK, e.g., Prometheus, Grafana, OpenTelemetry, Datadog]
- Infrastructure Platform: [PLATFORM, e.g., Kubernetes, AWS ECS, Nomad]
- GitOps Tool: [GITOPS_TOOL, e.g., ArgoCD, Flux, Atlantis]
- Environment Promotion Path: [ENVIRONMENTS, e.g., dev -> staging -> production]
- Team Structure: [TEAMS, e.g., platform-team, payments-squad, frontend-team]
- Compliance Requirements: [COMPLIANCE, e.g., SOC2, HIPAA, PCI-DSS, none]

## CONSTRAINTS
- Every change must be reviewable via pull request.
- The structure must support environment-specific overrides with a clear inheritance model.
- Rollback must be achievable by reverting a single commit.
- Secrets (API keys, tokens) must never be stored in the repository; reference external secret stores only.
- Include a validation step that runs in CI before any merge to a protected branch.

## OUTPUT SCHEMA
Return a JSON object with the following structure:
{
  "repository_name": "string",
  "top_level_directories": [
    {
      "path": "string",
      "purpose": "string"
    }
  ],
  "templating_strategy": {
    "tool": "string",
    "base_template_location": "string",
    "override_mechanism": "string"
  },
  "promotion_pipeline": {
    "ci_tool": "string",
    "stages": [
      {
        "name": "string",
        "trigger": "string",
        "validation_steps": ["string"],
        "deployment_action": "string"
      }
    ]
  },
  "rollback_procedure": "string",
  "secrets_management": "string",
  "team_ownership_model": "string"
}

## RISK_LEVEL: HIGH
This prompt designs production infrastructure. The output must be reviewed by a senior platform engineer before implementation. Ensure the structure does not grant unintended write access to lower environments.

After pasting the prompt, adapt the [OBSERVABILITY_STACK] and [PLATFORM] placeholders to match your exact toolchain. If your promotion path has more than three environments, expand the [ENVIRONMENTS] list explicitly. The output JSON is designed to be consumed by a scaffolding script or a GitOps operator, so validate that the generated directory paths and pipeline stages map to your actual CI system before committing. For high-risk environments, add a manual approval gate as an additional pipeline stage and ensure the rollback procedure references a tested git revert workflow.

This prompt is designed to be the first step in a GitOps-based observability pipeline. It should be invoked programmatically when a platform engineer requests a new observability stack or a major refactor of an existing one. The prompt expects structured inputs about the target environment, toolchain, and governance requirements, and it produces a directory layout, templating strategy, and promotion pipeline specification. The output is not a final repository—it is a blueprint that a subsequent automation step (or a human) uses to scaffold the actual repository structure.

To wire this into an application, wrap the prompt in a function that collects the required inputs from a service catalog, a configuration file, or a user-facing form. The function should validate that all required inputs are present before calling the model. After receiving the model's response, run a structural validator that checks for the presence of required directories (e.g., dashboards/, alerts/, rules/), a promotion pipeline definition (e.g., environments/ with dev, staging, production), and a templating strategy (e.g., templates/ with Helm or Jsonnet files). If validation fails, retry the prompt once with the validator's error message appended as additional context. Log the input parameters, the raw model output, and the validation result for auditability. For high-risk environments, require a human to approve the generated structure before it is applied to a live repository.

Model choice matters here. Use a model with strong code generation and structured output capabilities, such as Claude 3.5 Sonnet or GPT-4o, and set the temperature low (0.0–0.2) to maximize consistency. If your observability stack uses a specific templating engine (e.g., Helm, Kustomize, Jsonnet), include that as a constraint in the prompt. Do not use this prompt for simple single-service monitoring setups—it is overkill for small projects. The next step after generating the structure is to feed it into a repository scaffolding tool like cookiecutter or a custom CI/CD pipeline that creates the actual directories, placeholder files, and CI configuration. Avoid the temptation to let the model generate the full content of every file; the prompt should produce the skeleton, and the actual dashboard JSON, alert rules, and recording rules should be authored separately with their own review processes.