Feature Flag System Design Review Prompt Template

Use this prompt when your team is designing a new feature flag system or significantly refactoring an existing one. The prompt acts as a design review partner that examines your architecture document against known failure patterns in flag evaluation, targeting, SDK contracts, and operational safety. It is intended for platform engineers, release engineers, and architects who have a written design proposal and need a structured critique before committing to implementation. The prompt assumes you can provide a design document describing the flag evaluation pipeline, targeting rule model, SDK interface, and permission architecture.

The ideal input is a concrete design proposal, not a vague idea. The prompt works best when you supply details about the evaluation path (how flags are resolved from request to decision), the targeting rule model (user attributes, percentage rollouts, rule precedence), the SDK contract (what client code sees and calls), and the permission architecture (who can create, modify, or kill a flag). Without these specifics, the review will be shallow. If your design document is incomplete, the prompt will identify missing sections as part of its critique, which is itself a useful signal.

Do not use this prompt for reviewing individual flag configurations, debugging a specific flag evaluation bug, or auditing flag hygiene in an already-running system. Those tasks require different prompts focused on runtime behavior rather than design-time architecture review. For runtime debugging, use a prompt that accepts flag state dumps and evaluation logs. For flag hygiene audits, use the Feature Flag Technical Debt Assessment Prompt. This prompt is strictly for design-phase review before implementation begins, when the cost of changing architectural decisions is lowest.

This prompt template is designed to be copied directly into your AI workspace. It instructs the model to act as a principal platform architect and conduct a rigorous, structured review of a feature flag system design. The review focuses on the evaluation path, targeting rules, SDK contracts, and operational safety. To use it, replace the square-bracket placeholders with your specific design document content, architectural diagrams (described in text), and any organizational constraints.

textCopy
You are a principal platform architect with deep expertise in designing and operating large-scale feature flag systems. Your task is to perform a structured design review of the feature flag system described below. You will evaluate the design across four critical dimensions: Flag Evaluation Path, Targeting Rules, SDK Contracts, and Operational Safety.

**DESIGN DOCUMENT:**
[DESIGN_DOCUMENT_CONTENT]

**CONSTRAINTS:**
[CONSTRAINTS]

**OUTPUT_SCHEMA:**
Your review must be a single JSON object with the following structure:
{
  "summary": "A one-paragraph executive summary of the review's key findings and overall risk assessment.",
  "flag_evaluation_path": {
    "assessment": "A detailed analysis of the flag evaluation pipeline, from request to decision. Comment on latency, caching, and the handling of undefined flags.",
    "risks": ["A list of specific, actionable risks, e.g., 'No circuit breaker on the flag evaluation service could cause cascading latency.'"],
    "recommendations": ["A list of concrete recommendations to mitigate the identified risks."]
  },
  "targeting_rules": {
    "assessment": "A detailed analysis of the targeting rule engine. Comment on rule complexity, evaluation order, conflict resolution, and the permission model for creating and modifying rules.",
    "risks": ["A list of specific risks, e.g., 'Percentage-based rollouts combined with user-list targeting can create non-deterministic behavior for users in both groups.'"],
    "recommendations": ["A list of concrete recommendations."]
  },
  "sdk_contracts": {
    "assessment": "A detailed analysis of the client SDKs. Comment on initialization, error handling, default values, update polling/push mechanisms, and the contract for providing evaluation context.",
    "risks": ["A list of specific risks, e.g., 'SDK defaulting to `true` on connection failure could inadvertently expose a disabled feature during an outage.'"],
    "recommendations": ["A list of concrete recommendations."]
  },
  "operational_safety": {
    "assessment": "A detailed analysis of operational concerns. Comment on kill switches, emergency overrides, audit logging, flag debt management, and observability of flag state.",
    "risks": ["A list of specific risks, e.g., 'Lack of an emergency kill switch that bypasses the standard evaluation path creates an unacceptable MTTR for flag-related incidents.'"],
    "recommendations": ["A list of concrete recommendations."]
  },
  "permission_model_gaps": ["A list of specific gaps in the permission model, such as 'No separation between the roles of flag creator and flag approver.'"],
  "runtime_overhead_concerns": ["A list of specific runtime overhead concerns, such as 'The proposed rules engine uses a complex regex that could cause CPU spikes under high load.'"],
  "flag_dependency_conflicts": ["A list of potential conflicts between flags, such as 'Flag-A and Flag-B control the same UI component but have no defined precedence.'"]
}

**EVALUATION CRITERIA:**
- Be ruthlessly specific. Ground every risk and recommendation in the provided design document.
- If a section of the design is missing or underspecified, call it out explicitly as a risk.
- Prioritize risks that could cause production outages, data corruption, or security vulnerabilities.
- Recommendations must be actionable and practical for a platform engineering team.

After pasting the template, the most critical step is to populate the [DESIGN_DOCUMENT_CONTENT] placeholder with sufficient detail. A vague or incomplete design document will produce a vague and unhelpful review. Include specifics about the evaluation engine's architecture, the rule definition language, the SDK's initialization and update lifecycle, and the operational runbooks. The [CONSTRAINTS] placeholder is your opportunity to guide the review's focus—for example, specifying a particular cloud provider, a maximum acceptable latency budget, or a known organizational weakness like a lack of automated testing for flag configurations.

The output is a strict JSON object, which makes it directly consumable by downstream automation. You can parse this JSON to automatically create tickets in your project management tool for each identified risk or recommendation. Before integrating this into a CI/CD pipeline, test the prompt with several design documents, including one that is intentionally incomplete, to ensure the model reliably identifies missing information as a risk. Always have a senior engineer review the AI's output before it becomes the basis for architectural decisions.

This prompt is designed to be integrated into a design review pipeline, not used as a one-off chat. The primary integration point is a CI/CD or architecture governance workflow where a design document (RFC, ADR, or technical spec) is submitted for automated review before a human architecture review meeting. The prompt expects a structured [DESIGN_DOC] input containing sections on flag evaluation paths, targeting rules, SDK contracts, and permission models. If your design documents are spread across multiple sources (e.g., a wiki page plus an API spec plus a database schema), assemble them into a single context document before calling the prompt. The model choice matters: use a model with strong reasoning capabilities (GPT-4o, Claude 3.5 Sonnet, or Gemini 1.5 Pro) because this prompt requires cross-referencing multiple architectural concerns simultaneously. Avoid smaller or faster models for this task—they will miss dependency conflicts and permission model gaps.

The output is a structured JSON review document. You must validate this output before it reaches a human reviewer. Implement a post-processing validation layer that checks: (1) the review_id and timestamp fields are present and non-null, (2) every finding in the findings array has a non-empty severity field matching one of the expected enum values (CRITICAL, HIGH, MEDIUM, LOW), (3) every CRITICAL finding includes a mitigation block with at least one concrete action, and (4) the overall_risk_score is an integer between 1 and 10. If validation fails, retry the prompt once with the validation errors appended to the [CONSTRAINTS] section as explicit formatting requirements. If the retry also fails, log the failure and route the design document to a human review queue with a flag indicating automated review was incomplete. For high-risk flag systems (those controlling payment flows, authentication, or data access), require human approval on all CRITICAL and HIGH findings before the review is considered complete.

Wire the prompt into your application using a review service that accepts a design document ID, fetches the full document from your document store, assembles the prompt with the document inserted into the [DESIGN_DOC] placeholder, calls the model API, validates the response, and writes the structured review back to your review database. Include trace logging that captures: the prompt version used, the model and temperature, the input document hash, the raw and validated outputs, validation errors if any, and the final review status. This trace data is essential for debugging when the review misses an obvious architectural flaw—you need to know whether the prompt instructions were unclear, the model hallucinated, or the design document itself was incomplete. For teams using RAG, do not retrieve external context for this prompt; the review should be based solely on the submitted design document to ensure the review is self-contained and reproducible. If your flag system design references external standards (e.g., OpenFeature specification), include those references directly in the [DESIGN_DOC] rather than relying on retrieval.

Common failure modes in production include: the model producing findings that are factually inconsistent with the submitted design document (mitigate by including a ground_truth_check instruction in [CONSTRAINTS] that requires each finding to cite a specific section of the design document), the model missing flag dependency conflicts because the design document didn't explicitly list all flag combinations (mitigate by adding a pre-processing step that extracts all flag names and generates a dependency matrix for inclusion in the prompt), and the model producing overly generic findings like 'consider adding monitoring' without specific recommendations (mitigate by including concrete examples in the [EXAMPLES] section that demonstrate the expected specificity level). Start with a low temperature (0.1–0.2) to maximize consistency across reviews, and only increase it if you observe the model failing to surface novel architectural risks that a human reviewer would catch.