Feature Flag Specification Builder

Ship features safely with a written flag spec

A feature flag is a runtime switch that decouples deploy from release. The risk is not the flag — it is the undocumented flag. Without a spec, no one remembers who the flag targets, what would trigger a rollback, or when it should be deleted. This builder turns those decisions into a short, shareable specification before the flag goes live.

How it works

The tool collects the fields every well-run flag needs and renders them as Markdown:

• Flag key + description — a stable identifier and a one-line statement of what it controls.
• Targeting rules — ordered conditions that decide who is enabled. Rules are evaluated top-down and the first match wins, so narrow overrides (internal staff) go above broad rules (random 10%).
• Rollout plan — the percentage ladder you will climb, with an explicit pause between steps to inspect metrics.
• Metrics to watch — a guardrail (error rate, latency) and a success metric. Each has a threshold that defines “roll back”.
• Cleanup date — the date by which the flag is removed or the feature becomes the permanent default.

Everything runs locally in your browser; nothing is uploaded.

Example spec output

For example, a checkout redesign flag might produce this spec skeleton:

Flag key:    new_checkout_flow
Description: Gates the redesigned three-step checkout replacing the legacy five-step flow.
Owner:       @eng-payments

Targeting rules (evaluated top-down):
  1. user.team = "internal"  → ENABLED  (dogfood)
  2. random 5%               → ENABLED  (initial canary)
  3. *                       → DISABLED

Rollout plan:
  Step 1:  5%  — hold 48 h, check error rate and p95
  Step 2: 25%  — hold 48 h
  Step 3: 50%  — hold 72 h
  Step 4: 100% — promote or kill within 14 days

Guardrail metric: checkout error rate — roll back if > 1.5%
Success metric:   checkout completion rate — target >= 68%

Cleanup date: [launch + 21 days]

Targeting rules: order matters

Rules are evaluated from the top down and the first match wins. This means a narrow override must sit above a broad rule. If you put the “random 20%” rule before “user.team = internal”, every internal employee lands in the random bucket and the override never fires. The builder enforces this by letting you drag rules into priority order before exporting.

Choosing the right rollout ladder

The standard ladder for a user-facing change is internal → 5% → 25% → 50% → 100%. How long to hold at each step depends on traffic volume. On a high-traffic surface, 48 hours may be more than enough to detect a regression. On a low-traffic page, you may need a week at 25% to collect a meaningful sample. Define the hold duration explicitly in the spec so there is no ambiguity about when it is safe to advance.

The cleanup date: most important field on the form

Flags that outlive their purpose become undocumented permanent branches. Engineers fear touching them because the consequence of removal is unclear. Setting a cleanup date at creation time — before the flag ships — forces a calendar event. The typical window is two to four weeks after reaching 100%. If the feature is still in flux at that date, extend deliberately rather than silently; the date should be the result of a conscious decision.

Tips for keeping a flag system healthy

• Name by intent, not implementation. enable_new_checkout tells you what to remove when done; temp_flag_2 tells you nothing six months later.
• One flag, one purpose. Avoid using the same flag to gate multiple features; disentangling them later is painful.
• Keep specs in version control alongside the code. The Markdown this tool exports drops cleanly into a PR description or a Confluence page.
• Review stale flags in each sprint. A flag past its cleanup date is immediate tech debt.