First, a short reminder of what a flag is, and why it is so easy to create and so easy to forget.

Feature flags in one minute

A feature flag is a switch in your software that decides whether a feature is visible. Instead of hiding a new button by deleting code, you wrap the button in a check: “if the flag is on, show it.” Later you flip the flag in a dashboard and the button appears or disappears without shipping a new release. A remote config value is a close cousin. Instead of just on or off, it holds a number or some text, such as how many items to show per page.

Why creating a flag is cheap

Making a flag takes seconds. You type a name, click create, and add a check to your code. There is no meeting, no ticket and no review needed to feel safe. That ease is exactly why flags are loved. It is also the reason they multiply. Anything that is cheap to create and free to keep will be created often and kept forever, unless somebody decides otherwise.

Why removing a flag is expensive

Removing a flag is different. Someone must confirm that no code still reads it, that no customer still depends on the old behaviour, and that the flag is not secretly guarding something important. They must change code, test it, release it and then delete the flag. None of this is exciting, and none of it ships anything new. When teams are busy, cleanup slides down the list again and again.

The asymmetry that creates debt

Cheap to create, costly to remove, and rarely owned: that three-part combination is the root of almost every flag cleanup problem. The rest of this guide is about changing that balance, by making creation slightly more careful, and removal much easier.

A borrowed idea from money, applied to code.

The original idea

The phrase technical debt was popularised by a software engineer named Ward Cunningham. The idea is simple. When you take a shortcut in your code to ship sooner, you are borrowing time from your future self. The shortcut works today, but you will have to pay it back later, and until you do, you pay interest: everything related to that code takes a little longer, breaks a little more easily and confuses a little more people.

Not all debt is bad

Borrowing is not wrong in itself. A company that borrows to open a shop may earn far more than the interest costs. In the same way, a quick, temporary flag that lets you launch a feature this week may be exactly the right decision. The trouble begins when the debt is forgotten, when nobody knows how much exists, and when the interest quietly grows larger than the benefit ever was.

Debt versus mess

It helps to separate honest debt from plain mess. Honest debt is a deliberate choice with a plan to repay: “we added this flag to launch safely, and we will remove it by the end of next month.” Mess is the same flag with no owner, no date and no memory. The first can be managed. The second can only be discovered later, usually at a bad moment.

The right cleanup plan depends entirely on what the flag was meant to do.

Teams that treat all flags alike either delete useful switches by mistake or keep useless ones forever. A better habit is to sort flags into kinds, because each kind has a different natural lifespan. A widely used way to sort them has four groups.

Release flags: the usual suspects

Most flag debt comes from release flags. They are created with a clear, short job: hide an unfinished feature until it is ready. Once the feature is fully released to everyone, the flag is dead weight, yet it remains because nobody circles back. If you remember one rule from this guide, make it this one: a release flag is born with an expiry date.

Experiment flags

An experiment compares two or more versions of something, such as two checkout designs, to learn which performs better. When the experiment ends, someone must pick the winner, make it the only version and remove the losing code and the flag. Experiments that end without a decision leave behind a flag that still splits users forever, quietly confusing later analysis.

Operational flags

A kill switch is a flag kept on hand to turn off a risky or expensive behaviour instantly, for example a feature that depends on a slow outside service. These are meant to live a long time. They are not debt in the same sense, but they still need owners and regular checks, because a kill switch nobody has tested may fail on the day it is needed.

Permission flags

Flags that decide who has access to which paid features are really product configuration wearing a flag’s clothes. They do not belong in a clean-up drive. They belong in a clearly labelled group so that nobody mistakes them for forgotten experiments.

Old flags are not harmless. They quietly tax every part of the work.

Cost one: code that is hard to read

Every flag check is a fork in the road. A reader of the code must hold both paths in mind: “if the flag is on, this happens; otherwise that happens.” With one flag, that is easy. With fifty nested flags in a single area, nobody can say what the program does without checking a dashboard, and even then the answer may differ by environment.

Cost two: a testing explosion

Each flag doubles the number of possible states of the program. Two flags give four combinations, three give eight, and ten give over a thousand. Nobody tests all of them. The untested combinations are where surprising bugs live, and they appear only for the unlucky customer whose settings happen to land on that combination.

Cost three: operational risk

A stale flag is a loaded switch with no label. Someone flips it by accident, a script changes it in bulk, or a new teammate guesses wrongly about what it does. A publicly reported trading incident from 2012 is often told as a warning: an old, long-forgotten switch was reused for a new purpose, and on one server the old code behind it was still alive. The result was a very costly failure within minutes. The details are well documented online, and the lesson is simple: dead code behind a live switch is a hazard.

Cost four: slower onboarding

New teammates must learn which flags matter and which are fossils. Without a record, they learn by asking, and the answers differ from person to person. Each confusion costs hours, and experienced engineers are interrupted again and again to explain history that should have been deleted.

Cost five: clutter in the tools

A dashboard with nine hundred flags is hard to search, slow to scan and easy to misread. Real, important flags are buried among dead ones. People stop trusting the list, and a list nobody trusts is a list nobody maintains.

Cost six: wasted effort and money

Dead flags still get evaluated, logged and carried through every release. Dead code still compiles, still gets scanned by security tools, and still needs updating when libraries change. Each of these costs is small. Together, and multiplied across years, they are significant.

Cleanup is easiest when it is planned as the last chapter of a flag’s story, not an afterthought.

flowchart LR
  A["Idea: ticket created"] --> B["Birth: flag created with owner, kind and expiry"]
  B --> C["Build: code added behind the flag"]
  C --> D["Rollout: staff, small group, everyone"]
  D --> E["Stable: flag on for all, no more changes"]
  E --> F["Retire: remove code, archive flag"]
  F --> G["Delete: flag removed from Flagsmith"]

Stage by stage

Where debt sneaks in

Almost all flag debt appears in the gap between stages five and six. The feature works, everyone is happy, attention moves to the next project, and the cleanup ticket sinks. A simple way to close the gap is to schedule the removal at the same moment the rollout reaches one hundred percent, while everyone still remembers why the flag exists.

To clean thoroughly, you must know every place a flag leaves a trace.

The containers

Flagsmith organises everything in layers. An organisation is your company account. A project is usually one product. An environment is one stage of that product, such as development, staging or production. A feature is the definition of a flag, shared across the whole project. A feature state is the value of that feature inside one environment.

The traces a flag leaves

Deleting a flag in the dashboard removes only one of its traces. A thorough cleanup considers all of them.

Environments drift

A flag can be fully on in production, half on in staging and off in development. When it is time to remove it, each environment must be considered. If the flag still has different values in different places, you must decide which value represents the truth before deleting it, because the code you keep must match the behaviour you want everywhere.

The cheapest cleanup is the cleanup you planned on the day the flag was created.

The birth certificate

Every new flag should be created with a small set of information, a sort of birth certificate. It takes one minute to fill in and saves hours later.

Naming that lasts

Good names are the cheapest form of documentation. Begin with the product area, describe the change and avoid names that depend on who asked for it or when it was made. Avoid vague words such as test, new and temp, which age badly. Use the same word separator everywhere so searches work. A name like checkout_new_payment_form will still make sense in two years. A name like newflag2 will not make sense in two weeks.

Tags as the glue

Flagsmith lets you attach tags to flags. Tags are the easiest way to record owner and kind, and they make filtering simple: “show me every release flag owned by the payments team.” If tags are applied consistently from the start, most of the reports and automations later in this guide become simple to build.

Make the removal task part of the plan

The most effective prevention habit is to create the removal task at the same moment as the flag. Put “remove flag and old code” into the original ticket as its own checklist item, or open a linked ticket with a due date. A task that exists from the beginning is far more likely to be done than a good intention.

Before you can clean, you must know what is dirty.

What “stale” means

A stale flag is one that has stopped doing useful work. Its value no longer changes, or its decision no longer matters, but it still sits in the code and the dashboard. Staleness has several faces, and good detection looks for each.

Tools you can use

Flagsmith offers several features that help with detection, though the exact names and availability differ by version and plan, so check your own account. Typical helpers include tags and the ability to mark a flag as stale, an archive option that hides retired flags from everyday lists, flag usage reporting from SDKs, an audit log of every change, and integrations that link flags to code hosting and issues. Some versions can also scan code repositories to show where a flag is referenced, which directly answers the question “is this still used anywhere?”

Use the API for custom reports

For anything the dashboard does not offer, the REST API lets you read every flag with its tags, creation date and state across environments. A small script can build a report of every release flag older than ninety days that is identical in all environments and has no segment rules. That single list is often the most productive cleanup backlog a team can have.

Cross-check before you trust a signal

No single signal proves a flag is dead. A flag that is never read might guard a rarely used report. A flag that has not changed for a year might be a valuable kill switch. Treat the signals as a way to build a short list, then confirm each flag with a person and with a code search before acting.

What gets measured gets managed. A handful of simple numbers tells you almost everything.

Five numbers worth tracking

The most important ratio

If you track only one thing, track the monthly balance between flags created and flags removed. If you create thirty and remove ten, you gain twenty flags of debt every month, and the list will double within a year. If you remove as many as you create, the list stays steady however busy you are. This single ratio turns a vague worry into a clear target.

flowchart LR
  C["Flags created each month"] --> B{"Compare"}
  R["Flags removed each month"] --> B
  B -->|"Created greater than removed"| G["Debt growing: schedule cleanup"]
  B -->|"About equal"| S["Debt stable: keep the habit"]
  B -->|"Removed greater than created"| D["Debt shrinking: good progress"]

Put the numbers where people can see them

Numbers hidden in a spreadsheet change nothing. Publish them on a team page, include them in a monthly review, and celebrate improvements. A simple chart that shows the flag count by month is enough to start conversations. When the line rises steadily, people notice, and noticing is the first step of repayment.

Not every old flag should go, and not every flag should go at once.

Sort candidates into four boxes

Once you have a shortlist, sort each flag into one of four boxes. This takes a few minutes per flag and prevents most mistakes.

Questions that decide the box

• Is the flag on or off for everyone, in every environment? If yes, one path of code is dead.
• Which path is dead? If the flag is on for everyone, the “off” code can go. If it is off for everyone, the feature was abandoned and the “on” code can go.
• Is there any reason to switch it back? A recently launched feature may still need an emergency way back.
• Does anything else depend on it? Other flags, reports, partners or scheduled jobs may read it.
• Who owns it, and do they agree? If the owner is unknown, escalate before acting.

Ranking by value and safety

Start with flags that are easy to remove and costly to keep: old, fully rolled out, in busy parts of the code. Leave the tricky ones for later, once the team has built confidence and routines. Quick, safe wins create momentum, and momentum is what makes cleanup a habit instead of a one-off campaign.

The order of operations matters. Removing things in the wrong order is how outages happen.

sequenceDiagram
  participant O as Owner
  participant C as Code
  participant F as Flagsmith
  participant M as Monitoring
  O->>F: Confirm final value in every environment
  O->>C: Remove flag checks and the dead code path
  C->>C: Update tests and default values
  C->>M: Release and watch graphs
  M-->>O: Quiet period passes with no problems
  O->>F: Archive the flag
  F-->>O: Hidden from everyday lists, easy to restore
  O->>F: Delete the flag after a final wait

The steps in detail

Why code comes before the dashboard

A common mistake is deleting the flag in the dashboard first because it is the quickest step. If any code still reads the flag, that code now gets a missing value and falls back to its default, which may silently flip behaviour for real users. Removing the code first means the flag is already unnecessary when it disappears.

Why archive before delete

Archiving is a gentle step. If a forgotten report or an old app version still depends on the flag, the failure will appear, you will notice, and you can restore the flag within seconds. Deleting is permanent, so it deserves a pause and a final check.

Most of the cleanup effort lives in code, not in the dashboard.

What a flag check looks like in spirit

In plain terms, a flag check is a fork: “if the flag is on, do the new thing, otherwise do the old thing.” Removal means choosing the winner of that fork, keeping its code, and deleting the other path together with the fork itself. When the flag is fully on, you keep the new path. When the flag was abandoned and is off, you keep the old path.

Common shapes of flag use

Habits that make removal safe

• Isolate flag checks. Keep each flag read in as few places as possible, ideally one decision point, so removal touches little code.
• Prefer small, separate changes. Remove one flag per change, so a problem points at one cause.
• Let tests lead. Make sure the winning path is well covered by tests before deleting the losing path.
• Remove helpers too. Functions, styles and assets used only by the dead path should go with it.
• Let tools help. Linters and static analysis can flag unreachable code after the check is removed.

What to do in the dashboard once the code is clean.

Archiving

Flagsmith lets you archive a flag. An archived flag is hidden from normal lists, which reduces clutter, but it is not destroyed. Archiving is ideal as a holding area: it signals “this is retired” to everyone, while keeping the option of bringing it back. The exact behaviour of archived flags in SDK responses can differ, so confirm in the documentation for your version, and test with a non-production flag first.

Deleting

Deleting removes the flag and its states permanently. Its history in the audit log remains, which is valuable: months later, someone can still learn when and by whom a flag was removed. Delete only after the quiet period has passed, and make sure the owner has signed off.

Overrides: the hidden leftovers

Segment overrides give a flag special values for groups of users. Identity overrides give special values to individual users. Both are easy to forget. When a flag is deleted, its overrides disappear with it, but while the flag is alive they continue to influence results. Before retiring a flag, review its overrides, because they may reveal users or groups that still depend on the old behaviour.

Environments

Check every environment. A flag may be long finished in production but still used in a staging test or an old demo environment. If you remove it everywhere at once, those places may break. Either update them in advance or accept that they will use defaults and fix them as they appear.

Segments left behind

Segments are reusable groups, such as “beta testers.” After removing a flag, the segment may now be unused. Review segments too, since an old segment that no flag uses is a small piece of debt of its own. Take care, though: a segment might be used by other flags, so check before deleting.

Flags with several versions need an extra step: choosing the winner.

Why experiments are tricky

A normal release flag has two states. An experiment has several variations, each shown to a share of users. When it ends, you must decide what happens to every user who was in a variation. The winner becomes the only behaviour. The losers are removed. Skipping the decision leaves users permanently split into groups nobody is studying.

A clean ending for an experiment

Keep the analytics story intact

If your analytics tools received flag states as user properties, those properties will stop updating when the flag is removed. Make a note in the analysis documents, so that someone studying data next year understands why the property disappears on a certain date, and which variation became the default from then on.

On phones, old code never really dies.

The long tail of app versions

On a server, you control when new code runs. On a phone, users update when they feel like it. Some never do. This means that for months or years, versions of your app that still read an old flag may keep running on real devices. If you delete the flag the moment your newest version stops using it, those old versions may behave unpredictably.

What happens to old versions

When an old app asks for a flag that no longer exists, the SDK returns nothing, and the app falls back to its built-in default. If the default was chosen sensibly, the old app simply shows its old behaviour. If the default is the opposite of what the flag had been saying, those users suddenly see the feature disappear or appear, which can be confusing or even harmful.

A safe approach

• Check how many users run old versions. Use analytics to see which versions are still active.
• Keep the flag until old versions fade. If a meaningful number of users run a version that reads the flag, keep the flag alive in its final state until they upgrade or you retire support.
• Choose defaults that match the final state. For future versions, set the default to the winning behaviour so removal changes nothing.
• Use a version trait. Send the app version as a trait, so you can target or exclude old versions precisely.
• Consider forced upgrades. If very old versions block cleanup, a gentle upgrade prompt can help.

Cleanup that depends on remembering will fail. Cleanup that machines remind you about will not.

What can be automated

flowchart TD
  S["Scheduled job each week"] --> L["Read all flags through the REST API"]
  L --> F["Filter: past removal date, no owner, same value everywhere"]
  F --> T["Tag cleanup candidates"]
  T --> R["Build report grouped by team"]
  R --> N["Post to team chat channels"]
  N --> H["Owners decide: remove, extend or mark permanent"]
  H --> U["Record decision in flag description"]

Automation advises, humans decide

Resist the urge to delete automatically. A script that archives or deletes flags on its own will eventually remove something important. Let automation find candidates, label them and nag owners, while people make the final decision. If you do automate archiving, restrict it to flags that meet strict, well-tested conditions, and always run a dry run first.

Use least privilege for cleanup robots

A reporting script needs only read access. A tagging script needs permission to edit tags. A script that archives needs a little more. Give each job its own named key with only the permissions it needs, so the audit log shows exactly which robot did what, and a mistake cannot cause more damage than its role allows.

Technical debt is a people problem wearing technical clothes.

Who owns cleanup?

The creator of a flag should own its removal. This is the simplest and most effective rule. It keeps responsibility close to knowledge, since the person who made the flag knows best why it exists. When the creator leaves or changes teams, ownership passes to the team, not to the void. That is why the owner tag names a team, not just a person.

Rituals that make cleanup normal

Make removal respected work

Cleanup rarely wins praise, because nothing visible ships. Change that. Mention flag removals in team updates. Count them in planning. Treat a deletion that makes a file simpler as an achievement. When removal is respected, it gets done. When it is treated as a chore for later, it never is.

Budget some time for it

Reserve a small, steady share of each team’s time, such as a few percent, for cleanup and maintenance. This keeps debt from compounding and avoids the awkward bargaining over every single cleanup task. A modest regular allowance beats a large occasional campaign.

Cleanup changes production, so it deserves the same care as any other change.

Permissions

Not everyone should be able to delete flags. A sensible arrangement lets many engineers view flags, a smaller group archive and delete them, and reserves administrative actions for a few trusted people. This follows the principle of least privilege: each person and each robot gets only the access the job requires.

Approval for risky removals

For flags that touch critical paths such as payments or login, require a second person to review the removal plan. Some Flagsmith plans offer change approval workflows. Where they are not available, a pull request on the code change and a short checklist in the ticket achieve the same discipline.

The audit log as your safety record

Every change, including archive and delete, is written to the audit log with who made it and when. This gives you a trustworthy history for incident reviews and for audits. It only works if identities are meaningful, so avoid shared logins and give each automation its own named key.

Keys and secrets

Cleanup scripts use powerful credentials. Keep them in a secrets manager, never in repositories or chat messages, rotate them on a schedule, and revoke them when a script is retired. A forgotten cleanup key with delete permission is a hazard of its own.

A removal is a change, and every change deserves a few minutes of attention afterwards.

What to watch

• Error rates in the services touched by the change.
• Key business graphs such as sign-ups, orders or successful payments.
• Fallback and default usage in SDK logs, which can reveal code that still reads the removed flag.
• Support tickets and user reports in the day or two following.
• Old app version behaviour, if mobile clients are involved.

Use markers on dashboards

Flagsmith integrations can push flag change events to monitoring tools, so that archive and delete actions appear as markers on your graphs. If a metric changes right after a marker, you know where to look first. Make sure cleanup robots have clear names so the markers explain themselves.

A short watch routine

Know how to go back

Decide your way back before you start. If the code removal causes trouble, the usual path is to revert the release. If the flag was archived, unarchive it. Because flags are switches, a restored flag with its final value is usually enough to bring the old behaviour back quickly while you investigate calmly.

Habits that keep flag debt low, and habits that quietly build it.

Patterns worth copying

Advantages and trade-offs of regular cleanup

Anti-patterns to avoid

A practical checklist drawn from everything so far.

Do these

• Tag every flag with an owner and a kind when it is created.
• Give temporary flags a removal date and a linked ticket.
• Schedule removal at the moment of full rollout, while memory is fresh.
• Measure the created-versus-removed balance every month.
• Remove code first, then archive, wait, and delete.
• Review overrides and environments before retiring a flag.
• Handle old mobile versions deliberately.
• Let automation find candidates and let people decide.

Common mistakes and quick cures

A made-up company shows how the pieces fit together.

The story below is hypothetical. Imagine a video streaming company called Blue Harbor, with a mobile app, a web player and ten backend services. After four years, Flagsmith shows 1,100 flags. Nobody can say how many matter. A new engineering manager decides to bring order.

What made this smooth

Nothing needed heroics. The team made debt visible, agreed on simple rules, let machines find candidates and humans decide, protected old app versions, and watched after every removal. Each small habit covered a different risk, and together they turned an intimidating mess into a routine chore.

Every growing system faces the same quiet decay. Learning from other fields makes the lesson stick.

Flag debt is one example of a much older pattern: things that are easy to add and hard to remove accumulate until they hurt. The examples below describe publicly known practices in general terms, not any company’s private systems.

The shared pattern

Across all of these, the same few habits keep appearing. Record who owns each thing. Give temporary things an end date. Measure how much exists. Review on a schedule. Retire gently, with a way back. Make removal respected work. Teams that follow these habits in one area find it easy to apply them in another.

Lessons you can reuse

• Plan the end of a thing on the day it begins.
• Keep an inventory with owners.
• Prefer small, regular tidying over occasional crisis cleaning.
• Retire in stages so mistakes can be undone.
• Measure the trend, not just the total.

Knowing the limits of any practice is as valuable as knowing its strengths.

It cannot replace good creation habits

No amount of cleanup will keep up with careless creation. If flags keep appearing without owners and dates, you will always be digging out. Prevention and cleanup are two halves of one habit.

It cannot be fully automated

Machines can find candidates, but only people can judge whether a flag still matters. Business context, customer promises and upcoming plans live in human heads. Treat automation as a flashlight, not a bulldozer.

It cannot remove risk entirely

Every change carries some risk, including removal. Process reduces the risk but does not erase it. That is why small steps, quiet periods, watching and rollback plans matter.

It cannot fix poorly structured code

If flag checks are scattered across hundreds of files, removal will be slow however well planned. Cleanup reveals structural problems, and fixing them is a separate, longer task. Improve how flags are read in code so future removals are easier.

It is not a substitute for deleting features that should never have shipped

Sometimes a flag marks a feature that is genuinely abandoned. The right answer is to remove the feature entirely, not to keep a switch that can never matter. Product decisions and flag decisions should be made together.

Three practical tools to keep beside your team’s notes.

Part one: a ninety-day plan

Part two: a removal runbook

A runbook is a short, step-by-step guide that a tired person can follow. Here is one for retiring a single flag.

Part three: a one-page cheat sheet

• Tag at birth. Owner, kind and removal date, always.
• Plan the end. The removal task is created with the flag.
• Measure the balance. Created versus removed, every month.
• Find by many signals. Age, sameness, usage, owners, code search.
• Triage into four boxes. Remove now, remove soon, keep and label, investigate.
• Code first. Then release, archive, wait and delete.
• Mind the leftovers. Overrides, segments, environments and old app versions.
• Automate the nudges. Humans make the decisions.
• Protect kill switches. Label them permanent and review them.
• Keep it small and regular. A little every week beats a campaign every year.

Pin this list beside your team’s runbook. New joiners can read it in two minutes, and experienced engineers will find that it settles most arguments quickly. Good habits around cleanup are what turn a fast-growing flag programme into a lasting asset instead of a slowly collapsing pile.

One last piece of advice concerns patience. Nobody clears four years of debt in a week. Begin with the easy wins, build routines, and let the numbers show your progress. Teams that clean gradually and consistently end up with simpler, safer systems than teams that wait for a perfect moment, because every removal is justified by a real flag they have already examined.

Quick definitions of the words used in this guide.

Cleanup competes with new features for time. Here is how to win that argument fairly.

Speak the language of cost and risk

Managers rarely respond to “the code is messy.” They respond to cost, speed and risk. Translate flag debt into those terms. Cost: how many engineer-hours are spent each month working around old flags, explaining them to newcomers, or testing combinations that should not exist. Speed: how much longer changes take in areas crowded with flags. Risk: how many critical paths contain switches nobody understands.

Estimating the interest

You do not need exact figures. A rough estimate is enough to start a conversation. Ask a few engineers how many minutes a week they lose to flag confusion, multiply by the number of people, and convert to hours per month. Then compare that with the hours needed to remove the oldest hundred flags. Very often the one-time cost of removal is repaid within a few months.

These numbers are only an illustration, and your own will differ. The point is the method: make the cost visible, compare it with the cost of the cure, and let the comparison speak.

Tell stories, not only numbers

A single memorable incident is worth a page of statistics. If a confusing flag once delayed a release by a day, or caused a short outage, tell that story plainly and without blame. People remember stories, and stories turn an abstract worry into a concrete reason to act.

Ask for something small first

Do not ask for a six-month programme. Ask for one afternoon, one team and one clear measure of success. When that small trial shows fewer flags, simpler code and no incidents, the next request is much easier. Credibility is built one small success at a time.

Connect cleanup to goals people already care about

• Faster delivery. Simpler code means shorter changes and fewer surprises during release.
• Reliability. Fewer unknown switches means fewer unplanned incidents.
• Onboarding. New hires become productive sooner when the codebase tells a clear story.
• Security and compliance. A clean inventory with owners makes audits easier.
• Cost. Less dead code and fewer unused resources reduce effort and spending.

A small, honest dashboard keeps the whole team aware of the state of the drawer.

What a flag health page should show

You do not need a fancy tool. A single page, refreshed weekly by a script, is enough. It should answer five questions at a glance: how many flags exist, how old they are, who owns them, which are past their removal date, and whether the list is growing or shrinking.

flowchart LR
  A["Flagsmith REST API"] --> B["Weekly report job"]
  B --> C["Compute age, owners, sameness, overdue"]
  C --> D["Store snapshot for trend charts"]
  D --> E["Publish health page"]
  C --> F["Post overdue lists to team channels"]
  E --> G["Monthly review meeting"]
  F --> H["Owners act on their flags"]

Keep snapshots to see trends

A single report tells you where you are. A series of reports tells you where you are heading. Save a snapshot each week, even if it is just a small file, so you can draw trend lines and show that the work is paying off. Snapshots also help in audits, because they prove what the flag inventory looked like on a given date.

Make the page friendly

A health page nobody reads is wasted. Keep it short, use plain words, show the trend first and the lists second, and link each flag to its place in Flagsmith and its ticket. Avoid blaming individuals. Group by team, and phrase it as an invitation: “These five flags are ready for retirement.”

Beware of vanity numbers

A falling total looks good, but it can be gamed: archive flags instead of cleaning code, and the count drops while the debt remains. Pair the flag count with a measure that reflects real code removal, such as the number of flag checks found by a code search. If the number of checks in the code falls along with the flag count, the improvement is real.

A small set of questions for the monthly review

• Did we create more flags than we removed? If so, why?
• Which team has the most overdue flags, and what is blocking them?
• Are any permanent flags overdue for review?
• Did any removal cause a surprise, and what did we learn?
• What is the single most valuable flag we could retire next month?

Ten minutes on these questions each month keeps the practice alive. The aim is not perfection. It is steady attention, and steady attention is what stops the drawer from filling with keys again.

Five questions to ask before you create any flag

Prevention is the cheapest cleanup. Before creating a new flag, pause for a minute and answer five short questions. Doing so takes almost no time and prevents most of the debt described in this guide.

These five questions work for a tiny change and for a company-wide programme alike. Teams that make them a habit rarely have dramatic flag problems, because small issues are noticed and fixed while they are still small, long before they can interfere with a launch, an experiment or an incident response.

A culture that tidies as it goes

In the end, flag hygiene is a matter of culture more than tools. In a healthy team, removing a flag is as normal as writing a test. Nobody needs to be asked, because everyone remembers that a feature is not finished until its scaffolding is gone. Leaders set this tone by praising tidy work, by giving time for it, and by never treating cleanup as something done only when there is nothing better to do. Newcomers pick up the habit by watching how the team behaves, which is why the first few weeks of a new engineer are the best moment to show them how flags are created, tracked and retired. A culture like this does not appear overnight, but it grows steadily from small, repeated, visible actions, and it keeps paying back long after the first cleanup day has been forgotten.

Write down what you learn

Every cleanup teaches something. A flag that turned out to guard a rare report, an old app version that still read a switch, a segment that three flags shared: each lesson is worth a sentence. Keep a short shared note of surprises and how they were handled, and link it from your removal runbook. The next person to retire a flag will read it, avoid the same trap and add a lesson of their own. Over a year, that small note becomes the most practical guide your team owns, because it describes your systems, your habits and your history, not someone else’s.

It also helps to say thank you. When a teammate removes a stubborn flag that has haunted a service for years, mention it in the team channel. Recognition is cheap, it is remembered, and it tells everyone that tidy work is valued. People repeat what is noticed and appreciated, and that quiet encouragement does more for flag hygiene than any rulebook or tool ever could.

Finally, keep your expectations realistic and your tone kind. Some flags will turn out to be harder to remove than anyone expected, and some mistakes will happen along the way. Treat each one as information about the system, not as a failure of a person. Blameless reviews, short written notes and a steady rhythm of small improvements will carry a team much further than pressure ever does. The goal is not a perfectly empty flag list. The goal is a list in which every item has a purpose, an owner and a plan, so that nobody ever again has to wonder what a mysterious switch does, or whether it is safe to touch.

If you take only one idea from this guide, let it be that every flag deserves an ending. Decide that ending on the day the flag is born, write it where everyone can see it, and check on it regularly. Everything else in this guide is detail in service of that single, simple promise.

Quick answers to the questions beginners ask most often.

The whole guide on one page.