Feature Flag Configuration Change Analysis Prompt

This prompt is built for release engineers and platform teams who need to move beyond a manual, line-by-line review of feature flag configuration changes. The core job-to-be-done is connecting a raw configuration diff to its real-world runtime impact before the change is merged and deployed. It requires three specific inputs to be effective: the configuration diff itself (e.g., from a Git PR), the flag's code references (showing where the flag is evaluated in the codebase), and the intended rollout plan (targeting rules, percentage, and schedule). Without these, the analysis will be speculative and low-confidence. The ideal user is someone who can provide this context and is responsible for preventing incidents like a mistyped userId attribute exposing a beta feature to a production audience.

The prompt is designed for high-signal, structured output. It produces a risk-ranked analysis covering four specific areas: targeting rule correctness (e.g., detecting a typo in a user attribute), stale flag detection (identifying flags that are 100% rolled out and safe to remove), conflicting flag combinations (finding two flags that control the same code path with contradictory states), and high-risk code path exposure (flagging a flag that gates a critical payment or authentication flow). This is not a general-purpose code review tool. It is a specialized instrument for a specific class of high-severity misconfiguration. Use it in automated PR checks, pre-deployment review checklists, and technical debt sprints focused on flag cleanup.

Do not use this prompt for reviewing application code logic, assessing algorithmic complexity, or evaluating UI changes. It is not a substitute for a full code review, nor is it designed to reason about feature flag SDK behavior or evaluate the performance of a flag evaluation service. Its value is strictly in analyzing the configuration and its relationship to the code and rollout plan. For high-risk flags controlling revenue-critical paths or user data access, the prompt's output should be treated as a structured input to a mandatory human approval step, not as an automated gate that can pass or fail a deployment on its own. The next step after generating this analysis is to integrate it into your CI/CD pipeline as a non-blocking comment on the PR, allowing the on-call engineer to make the final judgment.

The prompt below is designed to be copied directly into your AI harness. It expects a feature flag configuration diff, a flag registry or catalog for context, and a defined output schema. Replace every square-bracket placeholder with real values before execution. The prompt instructs the model to produce structured JSON suitable for downstream CI/CD checks, release gates, or review dashboards.

textCopy
You are a release engineering analyst reviewing a feature flag configuration change.

## INPUT
Flag Configuration Diff:
[FLAG_CONFIG_DIFF]

Flag Registry Context (current flag catalog with metadata):
[FLAG_REGISTRY_CONTEXT]

## TASK
Analyze the configuration diff and produce a structured rollout impact assessment.

## OUTPUT SCHEMA
Return valid JSON matching this schema:
{
  "change_summary": "string (one-sentence summary of what changed)",
  "targeting_rule_changes": [
    {
      "flag_name": "string",
      "change_type": "ADDED | MODIFIED | REMOVED",
      "previous_rule": "string | null",
      "new_rule": "string | null",
      "affected_segments": ["string"],
      "rollout_percentage_change": "number (percentage point change, positive or negative)",
      "risk_level": "LOW | MEDIUM | HIGH | CRITICAL",
      "risk_rationale": "string"
    }
  ],
  "stale_flag_candidates": [
    {
      "flag_name": "string",
      "staleness_indicator": "string (e.g., 100% rolled out for >30 days, targeting removed, kill switch unused)",
      "recommended_action": "REMOVE | ARCHIVE | INVESTIGATE"
    }
  ],
  "conflicting_flag_combinations": [
    {
      "flag_pair": ["string", "string"],
      "conflict_description": "string",
      "affected_code_paths": ["string"],
      "severity": "LOW | MEDIUM | HIGH | CRITICAL"
    }
  ],
  "high_risk_code_path_flags": [
    {
      "flag_name": "string",
      "controlled_code_path": "string",
      "risk_description": "string",
      "requires_manual_approval": true
    }
  ],
  "overall_rollout_recommendation": "PROCEED | PROCEED_WITH_CAUTION | STAGED_ROLLOUT_REQUIRED | BLOCK",
  "recommended_staged_rollout_plan": "string | null (if staged rollout recommended, describe sequence and monitoring gates)",
  "evidence_links": ["string (references to specific diff lines or registry entries)"]
}

## CONSTRAINTS
- Only report findings grounded in the provided diff and registry context. Do not invent flags, rules, or code paths.
- For each HIGH or CRITICAL risk finding, include a specific evidence link to the diff line or registry entry.
- If a flag controls payment, authentication, data deletion, or user permission code paths, mark it as high-risk and set requires_manual_approval to true.
- Stale flag detection: flag any flag that has been at 100% rollout for more than 30 days, has had its targeting rules removed entirely, or is a kill switch that has never been triggered in the last 90 days.
- Conflicting flag detection: identify pairs of flags whose targeting rules overlap and control the same code path or feature surface, creating unpredictable behavior.
- If no issues are found in a category, return an empty array.
- Do not speculate about runtime behavior beyond what the configuration controls.

## EXAMPLES
[FEW_SHOT_EXAMPLES]

## RISK LEVEL
[HIGH_RISK_DOMAINS]

Adaptation guidance: Replace [FLAG_CONFIG_DIFF] with the actual diff output from your flag management system (LaunchDarkly, Split, Flagsmith, or custom). Populate [FLAG_REGISTRY_CONTEXT] with a structured dump of current flag metadata including rollout percentages, creation dates, last modified timestamps, and owning teams. [FEW_SHOT_EXAMPLES] should contain 2-3 annotated examples of correct output for your organization's flag patterns. [HIGH_RISK_DOMAINS] should list your organization's critical code paths (e.g., "billing, auth, user_data_deletion, admin_permissions"). If your flag system uses custom terminology, adjust the schema field descriptions accordingly.

Before shipping: Validate the output JSON against the schema. Run this prompt against 10-20 known flag changes with expected outcomes and measure precision/recall on stale flag detection and conflict identification. Flag any CRITICAL or BLOCK findings for human review before automated gating. Log every invocation with the diff hash, model version, and output for auditability.

This prompt is designed to be called programmatically as a gate in your CI/CD pipeline, triggered by pull requests that modify feature flag configuration files (e.g., YAML, JSON, TOML in a flags/ directory). The harness should extract the raw diff from the PR, pass it as the [FLAG_CONFIG_DIFF] input, and provide the full current flag state as [CURRENT_FLAG_STATE] to enable stale flag and conflict detection. The model's structured output—a JSON object containing rollout_impact, stale_flag_candidates, conflicting_flags, and high_risk_path_flags—must be parsed and acted upon by subsequent pipeline steps, not just displayed as a comment.

To integrate this into a production system, wrap the model call in a thin service that handles retries, validation, and logging. Use a strict JSON schema validator (e.g., jsonschema in Python or zod in TypeScript) to ensure the model's output conforms to the expected structure before it is consumed. If validation fails, implement a single retry with a repair prompt that includes the validation error message. Log the raw prompt, the model's response, and the validation result to your observability platform for trace analysis. For high-risk flags—those controlling payment processing, authentication, or data deletion paths—the harness should automatically add a requires_human_approval: true label to the PR and block the merge until a designated release engineer acknowledges the rollout_impact assessment.

Model choice matters here: use a model with strong JSON mode and reasoning capabilities, such as claude-3-5-sonnet or gpt-4o, because the analysis requires cross-referencing multiple flag rules and inferring runtime behavior from configuration alone. Do not use a lightweight model for this task; the cost of a missed conflicting flag or a stale flag controlling a deprecated code path is far higher than the token cost. The harness should also implement a caching layer: if the [CURRENT_FLAG_STATE] has not changed since the last analysis, reuse the cached context to reduce latency and cost. Finally, ensure the harness posts the structured findings as a PR comment with a summary table and links to the full JSON payload, so reviewers can quickly see the blast radius without reading raw configuration diffs.