Feature Flag Dependency Tangle Detection Prompt

This prompt is for release engineers and platform teams who need to audit a feature flag system that has grown beyond simple on/off toggles. The job-to-be-done is producing a structured tangle report that identifies interdependent flags, maps flag-to-code coupling, and surfaces removal sequencing constraints. You should use this when you suspect flag debt is slowing down releases, when a flag cleanup sprint is being planned, or when a production incident was caused by an unexpected interaction between flags. The ideal user has access to flag configuration files, the codebase where flags are evaluated, and ideally a flag tracking system or spreadsheet. Required context includes the flag definitions, their rollout rules, and the code paths they gate.

Do not use this prompt for a simple inventory of flags or for basic stale flag detection. It is not a replacement for a feature flag management platform's built-in analytics. This prompt is specifically designed for dependency analysis—finding hidden coupling where one flag's behavior depends on another flag's state, or where removing a flag would silently change the behavior of a different flag. If your system has fewer than ten flags or you are only looking for flags that are always true or always false, a simpler dead flag detection prompt will be faster and cheaper. This prompt becomes valuable when the interaction graph is too complex to reason about manually, typically above twenty flags with overlapping rollout rules or shared code paths.

Before running this prompt, gather the raw material: your flag configuration as structured data (JSON, YAML, or TOML), the relevant source files where flags are evaluated, and any existing documentation about flag ownership or expected retirement dates. The prompt expects you to provide these as [FLAG_CONFIG] and [CODE_SNIPPETS] placeholders. If you cannot provide the actual code where flags are evaluated, the analysis will be limited to configuration-level dependencies and will miss the most dangerous class of bugs—code-level coupling where one flag's evaluation branch calls another flag. After receiving the tangle report, validate the findings against your flag management system and prioritize remediation based on the removal sequencing constraints and dead flag quantification provided in the output.

This prompt template is designed to be dropped into your release engineering workflow. It expects structured input describing your feature flag inventory, the codebase context, and your desired output format. The square-bracket placeholders allow you to adapt it to your specific flag management system, programming language, and risk tolerance without rewriting the core analysis logic.

textCopy
You are a release engineering auditor specializing in feature flag hygiene and system complexity.

Your task is to analyze the provided feature flag inventory and codebase context to produce a Feature Flag Dependency Tangle Report.

## INPUT

### Feature Flag Inventory
[FLAG_INVENTORY]

### Codebase Context
[CODEBASE_CONTEXT]

### Constraints
[CONSTRAINTS]

## OUTPUT SCHEMA

Return a single JSON object conforming to this structure:
{
  "tangled_flags": [
    {
      "flag_id": "string",
      "flag_name": "string",
      "dependencies": ["flag_id"],
      "dependents": ["flag_id"],
      "code_locations": ["file_path:line_number"],
      "tangle_severity": "high" | "medium" | "low",
      "removal_blockers": ["string describing why this flag cannot be removed independently"],
      "suggested_removal_order": "integer representing safe removal sequence position"
    }
  ],
  "dead_flags": [
    {
      "flag_id": "string",
      "flag_name": "string",
      "evidence_of_death": "string explaining why this flag is considered dead",
      "last_modified_date": "ISO date string or null"
    }
  ],
  "flag_debt_quantification": {
    "total_flags": "integer",
    "tangled_flags_count": "integer",
    "dead_flags_count": "integer",
    "average_dependency_depth": "float",
    "estimated_removal_effort_days": "float"
  },
  "removal_sequencing_plan": [
    {
      "step": "integer",
      "flag_id": "string",
      "action": "remove" | "untangle",
      "prerequisite_steps": ["integer"],
      "risk_notes": "string"
    }
  ]
}

## INSTRUCTIONS

1. Parse the [FLAG_INVENTORY] to identify all flags, their current status, and any declared dependencies or rollout rules.
2. Analyze the [CODEBASE_CONTEXT] to find actual flag usage in code, including boolean checks, context propagation, and any implicit dependencies where one flag's behavior changes based on another flag's state.
3. Identify **tangled flags**: flags that depend on other flags being in a specific state, or flags whose code paths are interleaved such that removal order matters.
4. Identify **dead flags**: flags that are no longer referenced in code, have been fully rolled out with no off-ramp, or whose controlling code has been removed.
5. Quantify flag debt using the metrics in the output schema.
6. Produce a safe removal sequencing plan that respects all dependencies.
7. Apply any [CONSTRAINTS] provided, such as ignoring test files, respecting allowlists, or flagging specific risk patterns.

## RISK LEVEL
[RISK_LEVEL]

If [RISK_LEVEL] is "high", flag any uncertainty and require human review before finalizing the removal plan. Do not assume a flag is dead without explicit evidence.

To adapt this template, replace the placeholders with data from your systems. [FLAG_INVENTORY] should be a structured dump from your feature flag service (e.g., LaunchDarkly, Split, or an internal system) containing flag keys, rollout percentages, targeting rules, and creation dates. [CODEBASE_CONTEXT] can be a grep output of flag references, an AST analysis summary, or a concatenation of relevant source files. [CONSTRAINTS] might include rules like "ignore flags in /test/ directories" or "do not suggest removal of flags tagged 'permanent'." [RISK_LEVEL] should be set to "high" for production-critical systems where a bad removal plan could cause an outage.

After copying the template, test it with a small, known set of flags where you can manually verify the output. Compare the model's tangle detection against your own understanding of the flag dependencies. If the model misses a known dependency, add an example to [CODEBASE_CONTEXT] that makes the relationship explicit. For high-risk environments, always run the output through a human review step before executing any removal plan.

This prompt is designed to run as a scheduled analysis job or a pre-release gate, not as an interactive chat. The primary integration point is a release engineering pipeline that collects flag configuration files, codebase references to flags, and flag metadata (owner, creation date, expected removal date) into a structured [INPUT] payload. The model returns a tangle report that downstream automation can parse and act on. Because the output drives cleanup tickets and release go/no-go decisions, the harness must validate the report structure, ground every claimed dependency to a source location, and fail closed when the model produces ambiguous or incomplete results.

Wire the prompt into a script or microservice that assembles the input from three sources: your feature flag management system (e.g., LaunchDarkly, Split, or an internal service), a grep or static analysis pass over the codebase for flag references, and a metadata file mapping flag keys to owning teams and removal deadlines. The assembled [INPUT] should include a JSON array of flag objects, each with the flag key, the files and line numbers where it appears, its current state (active, deprecated, removed), and any known dependencies declared in flag rules. The [OUTPUT_SCHEMA] should enforce a strict JSON structure with fields for tangled_flags (arrays of mutually dependent flag groups), dead_flags (flags with no code references), removal_sequence (a topologically ordered list for safe flag removal), and debt_score (a numeric estimate of flag debt severity). Validate the output against this schema before accepting it. If validation fails, retry once with a repair prompt that includes the schema violation details. If the second attempt fails, escalate to a human reviewer and block the release gate.

Model choice matters here. Use a model with strong structured output capabilities and a context window large enough to hold the full flag-to-code mapping. For large codebases with hundreds of flags, split the input by service or team boundary and run the prompt in parallel, then merge the results with a deduplication step. Log every run: the input hash, the model version, the output, the validation result, and any retry attempts. This audit trail is essential when a flag removal breaks production and the team needs to trace whether the tangle report missed a dependency. For high-risk releases, add a human approval step that presents the removal_sequence and tangled_flags to the release manager before any flag is toggled or removed.

Common failure modes to guard against: the model may report false dependencies when two flags appear in the same file but are logically independent. Mitigate this by including a [CONSTRAINTS] block that instructs the model to only report a dependency when one flag's evaluation directly gates another flag's state, not when they merely co-occur. The model may also miss dependencies that are constructed dynamically (e.g., flag keys built from string concatenation). The harness should flag any flag key that appears in the codebase but not in the model's output as a potential missed dependency and route it for manual review. Finally, the debt_score is a heuristic, not a metric to automate decisions on. Use it to prioritize cleanup backlogs, not to auto-remove flags.

Integrate the validated output into your existing toolchain: create Jira tickets for each tangled flag group, post the removal sequence to the release runbook, and update a dashboard tracking flag debt over time. The prompt is a diagnostic tool, not a remediation engine. It tells you what is tangled and what to remove first. The actual flag removal, code cleanup, and deployment verification remain engineering tasks that require human judgment and testing.