Multi-File Feature Flag Rollout Prompt

This prompt is designed for an engineering lead or senior developer who needs to introduce a new feature flag across a codebase spanning multiple services, modules, or repositories. The job-to-be-done is producing a concrete, ordered rollout plan that identifies every file requiring a flag check, every configuration location that must be updated, the default behavior when the flag is off, and the cleanup steps required after the flag is fully rolled out and removed. The ideal user has access to the repository structure, understands the existing flagging infrastructure (e.g., a configuration service, environment variables, or a third-party provider), and needs a plan that can be reviewed, executed, and verified by the team before any code is written.

Use this prompt when the feature spans more than two or three files and the risk of missing a code path or introducing inconsistent flag evaluation is high. It is particularly valuable when the flag controls a critical path—such as authentication, payment processing, or data persistence—where a bypassed flag or a misconfigured default could cause a production incident. The prompt expects you to supply the repository context, the feature description, the flag key name, and any known constraints such as deployment ordering or service boundaries. It will produce a structured plan with per-file instructions, flag evaluation points, default behaviors, and cleanup steps.

Do not use this prompt for single-file, trivial flag additions where a developer can identify all touchpoints in under a minute. It is also not appropriate when the flagging infrastructure itself is undefined or when the team has not yet agreed on a flag lifecycle policy (creation, rollout, removal). In those cases, resolve the infrastructure and policy questions first. For high-risk domains such as payments, healthcare data, or safety-critical systems, the output of this prompt must be treated as a draft requiring human review, security sign-off, and staged deployment with monitoring—never as an auto-applied patch. The next section provides the copy-ready prompt template you can adapt to your repository and flagging conventions.

This template is designed to be copied directly into your AI harness or coding agent interface. It instructs the model to produce a comprehensive rollout plan by identifying all files that require flag checks, configuration locations, default behaviors, and cleanup steps. The square-bracket placeholders allow you to inject the specific feature description, repository context, and output constraints without rewriting the core instruction set.

codeCopy
You are an AI coding agent planning a feature flag rollout. Your task is to produce a detailed, multi-file rollout plan based on the provided context.

## FEATURE DESCRIPTION
[FEATURE_DESCRIPTION]

## REPOSITORY CONTEXT
[REPOSITORY_CONTEXT]

## CONSTRAINTS
- The flag key must be [FLAG_KEY].
- The flag must default to [DEFAULT_BEHAVIOR] when not present.
- The rollout must follow a [ROLLOUT_STRATEGY] strategy (e.g., percentage-based, user-segment).
- All changes must be backward-compatible.

## OUTPUT SCHEMA
Produce a JSON object with the following structure:
{
  "plan_name": "string",
  "flag_configuration": {
    "key": "[FLAG_KEY]",
    "default_value": "[DEFAULT_BEHAVIOR]",
    "configuration_file": "string (path to where the flag is defined)",
    "initial_targeting_rules": ["string"]
  },
  "files_requiring_change": [
    {
      "file_path": "string",
      "change_type": "guard_condition | new_code_path | configuration | test",
      "description": "string (explain the exact change needed)",
      "code_snippet_before": "string (optional, existing code)",
      "code_snippet_after": "string (optional, proposed change)",
      "risk_of_bypass": "low | medium | high",
      "bypass_explanation": "string (if risk is medium or high, explain how the flag could be bypassed)"
    }
  ],
  "rollout_phases": [
    {
      "phase": "integer",
      "target_percentage": "integer",
      "target_segment": "string | null",
      "verification_steps": ["string"],
      "rollback_triggers": ["string"]
    }
  ],
  "cleanup_plan": {
    "removal_criteria": "string",
    "files_to_clean": ["string"],
    "post_removal_verification": ["string"]
  },
  "risk_assessment": {
    "overall_risk": "low | medium | high",
    "key_risks": ["string"],
    "untested_code_paths": ["string"]
  }
}

## INSTRUCTIONS
1. Analyze the repository context to find all code paths related to [FEATURE_DESCRIPTION].
2. Identify the exact files where a check for [FLAG_KEY] must be inserted.
3. For each file, specify whether the change is a guard condition, a new code path, or a configuration update.
4. Explicitly flag any code path that could execute the new behavior without evaluating the flag (bypass risk).
5. Propose a phased rollout strategy with clear verification and rollback triggers for each phase.
6. Define the cleanup criteria and list all files that must be modified to remove the flag after full rollout.
7. If you cannot find a required file or are uncertain about a dependency, state that explicitly instead of guessing.

To adapt this template, replace the placeholders with concrete values from your project. For [REPOSITORY_CONTEXT], provide a summary of the relevant directory structure, key files, and dependency graphs—this is critical for accurate file identification. If your flagging system uses a specific SDK or pattern (e.g., a isEnabled helper), mention it in the constraints. For high-risk rollouts, add a [HUMAN_REVIEW_GATE] placeholder that forces the model to mark certain phases as requiring manual approval before proceeding.

This prompt is designed to be called programmatically within a feature flag management pipeline, not as a one-off chat interaction. The primary integration point is a CI/CD job that triggers when a feature flag's rollout status changes (e.g., from beta to general_availability). The application harness should gather the required inputs—a list of changed or target files, the flag key, and the repository context—and construct the prompt request. Because the output is a structured rollout plan, the harness must parse the model's response into a machine-readable format (JSON) and validate it against a strict schema before any downstream actions, such as creating Jira tasks or opening pull requests, are taken.

For a concrete implementation, use a model with strong structured output capabilities and set response_format to json_schema with a schema that enforces the expected fields: files_requiring_flag_check, flag_configuration_locations, default_behaviors, cleanup_steps, and bypass_risks. The harness should implement a retry loop with exponential backoff (max 3 attempts) if the initial response fails JSON schema validation. A critical validation step is to cross-reference the files_requiring_flag_check list against the actual diff of the triggering change; if the model identifies a file not present in the change set, flag it for human review as a potential hallucination. Log every prompt version, input hash, raw output, and validation result to an observability platform for auditability and regression testing.

The highest-risk failure mode is a false negative where the model misses a code path that bypasses the flag. To mitigate this, the harness should not treat the model's output as the final word. Instead, after generating the plan, run a secondary static analysis tool (e.g., a custom grep or AST walker) to find all references to the flag key in the repository. Compare this list against the model's files_requiring_flag_check output. Any file found by static analysis but missed by the model must be appended to the plan and surfaced in a review UI with a warning. The final step is a human approval gate: the complete, augmented plan is presented in a pull request comment or a dedicated review tool, and merging is blocked until an authorized engineer confirms the plan's completeness.