Feature Flag and Toggle Discovery Prompt

Use this prompt when an AI coding agent must understand how runtime behavior is gated before planning any change that touches application logic. The primary job-to-be-done is discovery: producing a structured, auditable inventory of every feature flag, toggle, and runtime gate found in the repository. This includes their source locations, default values, gating conditions, and the SDK or configuration mechanism used. The ideal user is a developer or platform engineer integrating an AI coding agent into a workflow where editing a file without knowing its flag context could silently break a dark launch, override an operational kill switch, or create a change that never reaches users in production.

Run this prompt before the agent edits any file that might be behind a flag, before refactoring conditional logic that appears to be dead code, and before reconciling code-level flags with infrastructure-level configuration such as LaunchDarkly, Split, or internal feature flag services. The prompt assumes the agent has read access to the repository and can search across source files, configuration files, environment variable definitions, and any feature flag SDK usage patterns. It is a discovery step, not a modification step. The output should be treated as a snapshot that may need reconciliation against a runtime config dump from the actual flag service, since flags defined only in infrastructure config and never referenced in application code will not appear in the code-level inventory.

Do not use this prompt when the repository is known to have no feature flags, when the agent is operating in a sandbox without access to the full codebase, or when the task is a trivial documentation or formatting change that does not interact with runtime behavior. Do not use it as a substitute for runtime flag evaluation during testing. The prompt is also inappropriate for repositories where feature gates are entirely external and referenced only through opaque configuration keys with no in-code usage patterns to discover. In those cases, pair the agent with a direct API call to the feature flag service instead. After running this prompt, the next step is typically to validate the discovered flags against a runtime configuration dump, flag any code paths that appear gated but have no matching flag definition, and proceed with the planned change only after confirming the flag's operational state.

This prompt instructs an AI coding agent to systematically search a repository for feature flags, toggles, and runtime gates. It is designed to be copied directly into your agent harness, with all dynamic values replaced before execution. The template forces the agent to produce a structured inventory rather than a narrative summary, making the output machine-readable for downstream validation against a runtime configuration dump.

textCopy
You are a codebase analysis agent. Your task is to discover all feature flags, feature toggles, and runtime behavior gates in the repository at [REPOSITORY_PATH].

## SEARCH STRATEGY
1. Identify the feature flag library or framework in use by examining [DEPENDENCY_FILES].
2. Search for flag evaluation calls using patterns from [FLAG_EVALUATION_PATTERNS].
3. Search for flag definitions, defaults, and configuration using patterns from [FLAG_DEFINITION_PATTERNS].
4. Cross-reference flags found in code with any flag configuration files at [FLAG_CONFIG_PATHS].
5. Flag any toggles defined only in infrastructure config (e.g., environment variables, Kubernetes ConfigMaps) that have no corresponding application-code definition.

## OUTPUT SCHEMA
Return a JSON object with this exact structure:
{
  "flags": [
    {
      "flag_name": "string",
      "file_path": "string",
      "line_number": number,
      "default_value": "boolean | string | null",
      "conditions": ["string"],
      "evaluation_context": "string",
      "definition_source": "code | config | both",
      "infrastructure_only": boolean
    }
  ],
  "flag_library_detected": "string | null",
  "flags_found_only_in_infrastructure": ["string"],
  "search_coverage_notes": ["string"]
}

## CONSTRAINTS
- Do not include commented-out flag evaluations.
- Do not include flags from [EXCLUDED_DIRECTORIES].
- If a flag's default value cannot be determined, set default_value to null.
- For each flag, include the exact file path relative to the repository root.
- If a flag appears in multiple files, list each occurrence as a separate entry.
- Flag any flag whose name appears in infrastructure config but not in application code by setting infrastructure_only to true.

## EXAMPLES
[FEW_SHOT_EXAMPLES]

## RISK LEVEL
[RISK_LEVEL]

Adaptation guidance: Replace [REPOSITORY_PATH] with the absolute path the agent can access. Populate [DEPENDENCY_FILES] with a list like package.json, requirements.txt, go.mod, Cargo.toml so the agent knows where to look for the flag library. [FLAG_EVALUATION_PATTERNS] should include regex or AST patterns specific to the flag libraries your team uses—for example, if feature_flag('...') or unleash.isEnabled('...'). [FLAG_DEFINITION_PATTERNS] covers where defaults are set, such as flags.yml or const FLAGS = {...}. [FLAG_CONFIG_PATHS] points to directories like config/ or infra/ where runtime flag configuration lives. [EXCLUDED_DIRECTORIES] should list node_modules, vendor, .git, dist, build and any generated code directories. [FEW_SHOT_EXAMPLES] should contain 2–3 correctly formatted flag entries from your codebase to anchor the output format. Set [RISK_LEVEL] to high if flag misidentification could cause production incidents, triggering additional verification steps in the harness.

What to do next: After copying this template into your agent harness, run it against a repository where you already know the ground-truth flag inventory. Compare the agent's output against your manual inventory to measure recall and precision before trusting it on unfamiliar codebases. Pay special attention to flags_found_only_in_infrastructure—these are the flags most likely to be missed by code-only searches and most likely to cause surprises during deployment.

The Feature Flag and Toggle Discovery Prompt is not a standalone query—it is a structured extraction step that must be followed by validation against a runtime configuration dump. The prompt produces an inventory of flags with file locations, default values, and gating conditions, but it can only see what exists in application code. Flags defined exclusively in infrastructure-as-code, feature management SaaS dashboards, or environment-variable-only configs will be invisible to this prompt. The harness must therefore treat the prompt output as a partial inventory and reconcile it against an authoritative runtime source before any agent acts on flag state.

Wire the prompt into an agent workflow as a pre-edit discovery step. The agent should first run this prompt against the repository, then call a separate tool or API to fetch the current runtime flag configuration from the feature management system (LaunchDarkly, Flagsmith, custom config service, or environment-variable dump). The harness must merge these two sources: flags found in code but absent from runtime config are likely stale or dead; flags found in runtime config but absent from code are infrastructure-defined and require a different discovery path. Log discrepancies as warnings. For high-risk workflows—such as flag removal, default-value changes, or rollout percentage modifications—require human approval before the agent proceeds. The harness should also validate that every reported file location actually exists on disk and that extracted default values match the runtime defaults where both sources agree.

Model choice matters here. Use a model with strong code-structure reasoning and large context windows, since flag definitions can span multiple files and config layers. If the repository is large, pre-filter candidate files using ripgrep or AST-based search for common flag patterns (feature_flag, toggle, enabled, variant, experiment, LDClient, flagsmith, getValue, isEnabled) before passing them to the prompt. Set a retry policy: if the output fails schema validation—missing required fields like flag_name, file_location, or default_value—retry once with a stricter schema reminder. If the retry also fails, surface the partial output with validation errors and stop. Do not loop indefinitely. Store the final merged inventory as a structured artifact that downstream agent steps can reference, and version it alongside the commit SHA so future runs can detect drift.