Feature-Flag-Guarded Change

Flag wrap pattern (per stack — pick the one already used in this repo;

never introduce a second flagging mechanism into a repo that has one)

• Check CLAUDE.md / existing code for the repo's flag library (LaunchDarkly, Unleash, a homegrown config table, etc.) first. Only propose a new mechanism if none exists, and flag that as a decision for the user, not something to silently pick.
• Wrap at the narrowest point that fully gates the new behavior — a single entry point, not scattered if (flag) checks across many files. Scattered checks are exactly what makes flags hard to clean up later.

Kill-switch requirement (non-negotiable)

• The flag's OFF state must map to the exact previous behavior, verified by running the old test suite with the flag forced off after the change lands — not assumed from reading the diff.
• The kill switch must be flippable without a deploy (config/remote-flag service, not a hardcoded constant requiring a rebuild) for anything touching production traffic. If the repo's flag mechanism can't do this, say so before proceeding — it changes the risk profile of the whole change.

Cleanup ticket (required, not optional)

Every flag-wrapped change generates a follow-up ticket at creation time, not after: "Remove flag <name> once <rollout criterion> is met" with the flag name, both code paths' locations, and the removal owner. A flag with no cleanup ticket is exactly how flag debt accumulates — do not skip this step even for a change that "will obviously get cleaned up."

Procedure

1. Confirm the repo's flag mechanism (see above).
2. Wrap the new behavior at the narrowest single point; old path stays the default until explicitly flipped.
3. Verify OFF state == prior behavior (run old suite with flag forced off).
4. Verify ON state via the new/changed tests.
5. Create the cleanup ticket with rollout criterion and removal owner filled in — not left as a placeholder.
6. Report both code paths' locations and the exact toggle mechanism (env var, config key, dashboard) so someone else can flip it without reading the diff.

Anti-patterns

• Never scatter flag checks across more than the minimum call sites needed.
• Never ship a flag whose OFF state was assumed equivalent to prior behavior without actually running the old suite against it.
• Never skip the cleanup ticket — "no flag = no risky merge" only holds if flags don't become permanent by default.