Feature Flag Technical Debt Assessment Prompt

This prompt is for engineering managers and platform teams who need to audit the health of a feature flag system that has been running in production for months or years. The job is to produce a structured technical debt report that identifies stale flags, untested flag combinations, missing cleanup automation, and ownership gaps. Use it when you suspect flag proliferation is slowing down development, increasing testing complexity, or creating runtime risk that no single team owns. The prompt assumes you can provide a flag inventory, recent change history, and any existing flag governance policies.

Do not use this prompt for designing a new feature flag system from scratch—that requires the Feature Flag System Design Review Prompt Template instead. Do not use it for real-time incident response where a flag is actively causing an outage; the Feature Flag Operational Runbook Prompt Template is the right tool for that scenario. This prompt is also not a replacement for runtime flag evaluation analysis or performance profiling. It focuses on the organizational and process debt that accumulates around flag management, not on the technical performance of the flag evaluation path itself.

Before running this prompt, gather your flag inventory with metadata: creation date, owner, expected removal date, current rollout percentage, and any known dependencies between flags. The prompt works best when you also provide your team's stated flag policy—even if that policy is informal or aspirational. The output will be most actionable when you can compare actual flag hygiene against your own team's standards. If you lack a flag inventory or policy, start by using this prompt to define what a healthy baseline should look like, then iterate as you collect better data.

This template is designed to be copied directly into your prompt library or AI harness. It uses square-bracket placeholders for all dynamic inputs, allowing you to adapt it to your specific codebase, flagging system, and risk tolerance without rewriting the core instructions. The prompt instructs the model to act as a release engineering auditor, systematically evaluating flag staleness, testing gaps, ownership, and automation maturity.

codeCopy
You are a release engineering auditor specializing in feature flag hygiene and delivery architecture risk. Your task is to analyze the provided feature flag inventory and produce a structured technical debt assessment report.

## INPUT DATA
[FLAG_INVENTORY]

## CONTEXT
- Flagging system: [FLAG_SYSTEM_NAME]
- Codebase language and repository structure: [REPO_CONTEXT]
- Current release cadence: [RELEASE_CADENCE]
- Known incident history related to flags: [INCIDENT_HISTORY]

## OUTPUT SCHEMA
Return a JSON object with the following structure:
{
  "summary": {
    "total_flags": <number>,
    "stale_flags": <number>,
    "flags_without_owners": <number>,
    "untested_flag_combinations_risk": "low|medium|high|critical",
    "overall_debt_score": "low|medium|high|critical"
  },
  "stale_flags": [
    {
      "flag_name": "<string>",
      "created_date": "<ISO date>",
      "last_modified_date": "<ISO date>",
      "current_rollout_percentage": <number>,
      "estimated_removal_effort": "low|medium|high",
      "blockers_to_removal": ["<string>"]
    }
  ],
  "ownership_gaps": [
    {
      "flag_name": "<string>",
      "current_owner": "<string or null>",
      "last_known_team": "<string or null>",
      "risk": "<string>"
    }
  ],
  "testing_gaps": [
    {
      "flag_name": "<string>",
      "has_unit_tests": <boolean>,
      "has_integration_tests": <boolean>,
      "tested_states": ["<string>"],
      "untested_combinations_risk": "<string>"
    }
  ],
  "automation_gaps": [
    {
      "gap_type": "missing_cleanup_automation|missing_deprecation_policy|missing_ownership_enforcement",
      "description": "<string>",
      "affected_flag_count": <number>,
      "recommended_action": "<string>"
    }
  ],
  "runtime_risk_assessment": {
    "flag_evaluation_overhead_ms": <number or null>,
    "flag_dependency_conflicts": ["<string>"],
    "proliferation_risk": "low|medium|high|critical",
    "notes": "<string>"
  },
  "recommendations": [
    {
      "priority": <number>,
      "category": "removal|ownership|testing|automation|runtime",
      "action": "<string>",
      "effort_estimate": "low|medium|high",
      "risk_reduction": "low|medium|high|critical"
    }
  ]
}

## CONSTRAINTS
- Flag a flag as "stale" if it has been at 100% rollout for more than [STALE_THRESHOLD_DAYS] days without a removal ticket, or if it was created more than [MAX_FLAG_AGE_DAYS] days ago and is still below 100%.
- Treat any flag without a documented owner as a high-severity ownership gap.
- For testing gaps, consider any flag with more than [MAX_FLAG_STATES] boolean states that lacks integration tests for all combinations as high risk.
- If runtime overhead data is not available, note it as null and flag it as a monitoring gap in recommendations.
- Do not invent flag names, dates, or metrics. Only use data present in [FLAG_INVENTORY].
- If the inventory is empty or unparseable, return a JSON object with an error field explaining the issue.

## EVALUATION CRITERIA
- Completeness: Every flag in the inventory must appear in at least one relevant section if it has debt.
- Actionability: Every recommendation must include a concrete next step, not a vague suggestion.
- Severity calibration: Do not mark low-risk items as critical. Use the defined enums consistently.

To adapt this template, replace each square-bracket placeholder with data from your flag management system. The [FLAG_INVENTORY] should contain a structured list of flags with their metadata—export this from LaunchDarkly, Split, Flagsmith, or your internal system. Adjust [STALE_THRESHOLD_DAYS] and [MAX_FLAG_AGE_DAYS] to match your team's flag lifecycle policies. If your organization uses a different severity scale, modify the enum values in the output schema, but keep the structure consistent so downstream tooling can parse the report reliably.

Before deploying this prompt into an automated pipeline, validate the output against the JSON schema. A common failure mode is the model returning a markdown-wrapped JSON block instead of raw JSON—use a post-processing step to strip fences. For high-risk flag inventories where removal could cause production incidents, route the generated report through a human review step before any automated cleanup actions are triggered. Pair this prompt with the Feature Flag Operational Runbook Prompt Template for incident response workflows.

This prompt is designed to be integrated into a scheduled audit pipeline, not a real-time chat interface. The primary integration point is a CI/CD system (like GitHub Actions or Jenkins) or a cron-based platform service that runs weekly. The application harness should fetch the current state of the feature flag system via an internal API or configuration repository, serialize that state into the [FLAG_MANIFEST] input, and inject it into the prompt. The model's structured output is then parsed and written to a persistent audit log, such as a JSON file in a dedicated feature-flag-audit repository or a database table, enabling trend analysis over time.

The harness must enforce a strict output contract. Before the model call, define the expected JSON schema for the debt report. After receiving the response, validate it against that schema. If validation fails, implement a single retry with a repair prompt that includes the raw output and the schema error. If the retry also fails, log the failure and raise a non-blocking alert to the platform team. For high-risk flags identified in the report (e.g., flags with risk_level: critical), the harness should automatically create a ticket in the team's project management tool (like Jira or Linear) and assign it to the flag's owner, using the recommended_action from the model's output as the ticket description.

Model choice matters for this task. Use a model with strong reasoning capabilities and a large context window, as the [FLAG_MANIFEST] can be extensive. A model like claude-sonnet-4-20250514 or gpt-4o is appropriate. To manage cost and latency, consider pre-processing the manifest to exclude flags that have been fully removed for over 90 days. The harness should also log the prompt template version, model version, and a hash of the input manifest alongside the output for full traceability. Avoid wiring this prompt directly to a flag-kill switch; the output is an assessment for human review, not an automated action.