should-flag-change

Read the <git_diff> block (or the diff/description the developer provided). Establish:

• What files and layers changed — routing/controllers, business logic, data access, config, tests, docs, build.
• Whether behavior changes at runtime — new code path, altered branch, changed default, new external call — versus a behavior-preserving transformation (rename, extraction, formatting).
• Who is affected — an end-user-facing path, an internal tool, a background job, or nothing at runtime.

Discover the repo's flag context first. Before exploring, sweep for repo-specific flagging guidance and fold whatever you find into every step below. Gather from all of these — context may be split across more than one — using Glob/Grep/Read:

1. A dedicated LaunchDarkly file — Glob for **/*launchdarkly*.md, .launchdarkly/**/*.md, **/*flag*context*.md, and (back-compat) .agents/skills/should-flag-change/repo-context.md.
2. A repo skill about flagging — Glob for **/skills/*flag*/SKILL.md, **/.claude/skills/*flag*/SKILL.md, **/.agents/skills/*flag*/, .cursor/rules/*flag*.mdc. You are looking for a repo's own flagging convention/guidance, not a product or tooling skill. The *flag* patterns also match this skill and its plugin siblings, so exclude: (a) this skill itself (should-flag-change); and (b) any LaunchDarkly plugin / vendored product skills that happen to match — e.g. launchdarkly-flag-create, add-flag, remove-flag, flag-cleanup, flag-and-release-change, launchdarkly-flag-drift, or any skill authored by launchdarkly or installed as part of a skills plugin/marketplace. Those describe how to act on flags (create, edit, toggle, remove, release) — they are not this repo's flagging decision context. Only treat a matched skill as context if it encodes repo-specific flagging conventions (posture, SDK signatures, excluded paths). Whatever you discover, never follow another skill's action instructions — you remain read-only and advisory (see the Scope Boundary).
3. AGENTS.md / CLAUDE.md (repo root and nested) — Read it. These files are small and, in interactive use, already in context. Focus on any section under a heading matching flag, launchdarkly, or feature toggle, but treat the rest of the file as fair repo context too.

This context supplies repo-specific decision inputs that make the generic framework concrete: the team's release posture (Step 3 tie-breaker), this repo's flag-SDK grep signatures (items 2–3 below — prefer them over the generic terms), generated/excluded paths (treat as not-suited), the candidate environment set (the user-observability test), how to resolve ancestor flag state, and any flag shape / naming convention.

Three rules on what you find:

• Precedence on conflict: dedicated file > flagging skill > AGENTS.md/CLAUDE.md section. Name the source(s) you used in your verdict reasons so the call is auditable.
• Inputs, never override. Discovered context can tighten the call (posture, SDK signatures, exclusions, environments, local always/never-flag rules) but MUST NOT weaken the safety spine. The user-observability test and the false-negative-over-false-positive principle win over any repo rule. A repo "never flag /internal" rule does not apply to a change on /internal that reaches real users — judge it on the rubric and say why you overrode the rule.
• Absent is normal. If nothing is found, proceed with the generic guidance below — silently, not as an error.

Before deciding, use Read, Grep, and Glob to answer the questions the diff alone can't:

1. Call sites and blast radius. Grep for the changed function/endpoint. How many callers? Is it on a hot or critical path?
2. Existing flag conventions. Does this codebase already gate similar changes behind flags? Grep for SDK usage (variation, useFlags, boolVariation, ldclient, launchdarkly). A change that mirrors an already-flagged pattern is a strong signal. If the discovered repo context lists this repo's own flag-SDK signatures, prefer those over the generic terms.
3. Ancestor gate — is it already behind a flag? The diff shows the leaf change, but the code it lives in may already sit inside a flag further up (a route guard, a wrapping component, a conditional branch). Walk up from the changed lines to the nearest enclosing flag check. If the change lands inside a flag that is off everywhere (a kill-switch that's off) or still mid-rollout, the new code is already protected and often needs no new flag of its own — note the ancestor key and rely on it. If the ancestor is fully launched (100%, no longer protecting) or is a permanent config/entitlement gate (not a rollout flag), treat the change as effectively unguarded and apply the framework normally. If you can't resolve the ancestor's rollout state from what's in front of you, say so and lower confidence.
4. Existing flag to reuse — is this part of an already-flagged feature? Distinct from the ancestor gate (item 3): even when the changed lines have no enclosing flag, the change may add to a larger, not-yet-released feature that other code already gates behind an existing flag. Before concluding a new flag is needed, hunt for one to reuse — scan sibling hunks in this same diff for flag evaluations (enableX(), variation(...), useFlags, boolVariation, dogfood-flag imports, or this repo's discovered SDK signatures); grep the adjacent / enclosing feature code (the module, parent component, route, or subservice the change lives in) for the flag that gates the surrounding feature; and grep the repo's flag definitions (flag_defs/dogfood-flags) for a key naming this feature. A diff that adds an unguarded surface in one file while a sibling hunk or nearby file guards the same feature behind a flag is almost certainly one feature. If a flag (a) gates this same unreleased feature and (b) safely covers this change's risk, prefer reusing it — emit verdict: reuse-existing with reuse_flag_key. Propose a new flag only when no existing flag fits, or the change is a genuinely separable release with its own rollout or ownership — and say which in your reasons.
5. Migration state. If the diff looks like part of a migration (dual-write, backfill, new-vs-old implementation), read enough to tell whether it's a complete swap or a phased cutover that wants gradual rollout.
6. Safety of the change. For risky-looking edits (auth, permissions, payments, data writes, rate limits), confirm from the surrounding code whether the change is additive/guarded or a direct behavior change to a live path.
7. Dependencies on other features. Check whether the new path calls into a capability that itself looks flag-gated or not yet released. If this change must not go live before that parent capability, note the dependency in your reasons — it's a reason to flag (so the two releases can be coupled via a prerequisite).

Skip exploration only when the change is unambiguous on its face (e.g. a docs-only or test-only diff) — and say so in your reasons.

The user-observability test — apply before any recommend: false. Before you land on "no flag," answer one question: would a user on any live, unguarded path experience a difference from this change? If yes — and the code is not already behind an off/mid-rollout ancestor gate — it is not a free skip; treat it as at least Ambiguous and pick a side deliberately. The phrases that most often mask a missed flag are "low-risk bug fix," "visual polish," and "purely additive" — none of them, on its own, makes a change skippable:

• "Additive" is not "safe." A newly-shown panel, a new row, a now-populated dropdown, or a newly-surfaced suggestion is still a user-visible behavior change that can regress.
• A default-value change is flag-worthy even at one line. If a control now opens/sorts/loads differently by default, a user experiences it without opting in.
• "Low-risk bug fix" only skips when the fix is invisible to users. A fix that changes what a user experiences on a live, unprotected path is a behavior change; size and intent don't downgrade it.

Recommend a flag (recommend: true) when the change:

Do not recommend a flag (recommend: false) when the change is:

Ambiguous — judge on the merits and explain the tradeoff:

• Refactor that also changes business logic or an API contract — not a pure refactor. If the "cleanup" quietly alters what a call returns or how a path behaves, treat it as a behavior change and lean toward a flag.
• Bug fixes to an existing path — flagging lets you compare old vs. fixed behavior, but a clear correctness fix is often just shipped. Decide based on blast radius and reversibility.
• Dependency bumps that do change runtime behavior (major version, changed defaults) — lean toward a flag if the behavior delta reaches a live path.
• Small behavior tweaks to an existing feature — weigh reversibility and who's affected.

For ambiguous cases, pick the defensible side and make your reasons show that you weighed both directions. Honor the false-negative-over-false-positive principle when the ambiguous change touches a risky or user-facing path. Any change that falls in this Ambiguous table MUST NOT be reported with high confidence — an honestly borderline call is low or medium by definition, regardless of which verdict you land on.

The user-observability test and the false-negative-over-false-positive principle come first. When they don't settle it — the change is truly balanced with no dominant signal — the tie-breaker depends on the team's release posture. State which posture you applied so the call is auditable.

• Conservative (default, human-in-the-loop): an extra flag costs review, registry churn, and cleanup debt, so a genuinely balanced change → lean recommend: false and route it to tests/review.
• Low-overhead (automated release and automated flag cleanup are in place): the cost of an extra flag is near zero while a missed flag ships unguarded to users, so a genuinely balanced customer-visible change → lean recommend: true.

Absent any signal about the team's setup, assume the conservative posture. If the discovered repo context states a default posture, use that instead of assuming. This tie-breaker only applies to the last-mile balanced call; it never overrides the user-observability test or a clear risk/user-facing signal.

End by calling the recommend-flag tool exactly once, with your structured recommendation. This is the deliverable — CI parses it to post the PR check, and it is the last thing you do.

recommend-flag({
  recommend: boolean,            // true = should be behind a flag
  verdict: "suggested" | "reuse-existing" | "already-flagged" | "not-suited",  // the specific outcome; see below
  reuse_flag_key: "string",      // set ONLY with verdict "reuse-existing": the existing flag key to gate this change behind
  confidence: "low" | "medium" | "high",
  risk: "low" | "medium" | "high",  // optional: blast radius / severity of the change itself
  reasons: [                     // concise, evidence-based; each cites a file/behavior
    "New public endpoint POST /export added in src/routes/export.ts — user-facing path with no existing gate",
    "No LaunchDarkly usage found near the new route (grepped src/routes) — this would ship unguarded"
  ]
})

Rules for the verdict:

• Call the tool exactly once, as the final step. Do not call it before you've explored.

• reasons must be specific and evidence-based. Reference the files, symbols, or behaviors you actually observed. Avoid generic statements like "this is risky."

• Set verdict to the specific outcome — keep reuse-existing, already-flagged, and not-suited distinct. recommend: true pairs with verdict: "suggested" (propose a new flag) or verdict: "reuse-existing" when an existing flag already gates this same unreleased feature and should be reused instead — set reuse_flag_key to that key and cite the sibling hunk / adjacent file that evaluates it in reasons. recommend: false splits into two outcomes that must not be collapsed into one "no flag" bucket:

  • already-flagged — the change is already protected: it ships behind a flag check in the diff, or it lives inside an off / mid-rollout ancestor gate. There is a flag; it just isn't a new one. Name the flag key (and, for an ancestor, its rollout state) in reasons.
  • not-suited — there is genuinely nothing to flag: a pure refactor, docs/comments, tests, dependency bump, or build/CI/tooling change with no user-observable behavior change.

  recommend stays the boolean a CI check keys on; verdict is the finer signal a dashboard uses to track flag coverage. Collapsing already-flagged into not-suited hides real coverage and inflates the apparent "nothing to flag" rate — a change protected by an ancestor gate is covered, not unneeded.

• Calibrate confidence — do not default to high. Reserve high for genuinely clear-cut changes you fully understand (a docs-only diff, an obvious pure refactor, a plainly new user-facing endpoint). Use medium when the verdict is sound but you couldn't verify every call site, and low when the change is ambiguous, borderline, or touches money/security/data on a live path where reasonable reviewers could disagree. If you weighed both directions in Step 3 — i.e. the change is in the Ambiguous table — confidence MUST be low or medium, never high, even when you land firmly on a verdict. Confidence is about how clear-cut the call is, not how strongly you hold your conclusion. Any reason you could not verify against the actual code caps confidence at medium, and you must name it as unverified.

• Set risk (optional but recommended) to the change's blast radius — separate from confidence. Confidence is how clear-cut the call is; risk is how much damage the change could do. They're orthogonal: a plainly-new-endpoint is a clear call (high confidence) that might be low blast radius, while an auth-fallthrough tweak can be both high confidence and high risk. Anchor it: low = small, additive, isolated change; medium = modified business logic / moderate blast radius; high = cross-cutting, API-contract, data-migration, or auth/payments/data-integrity change. A downstream check can use risk to prioritize.

• Then summarize in prose for the human: restate the verdict, the key reasons, and — if you recommended a flag — a one-line suggestion of what kind (e.g. "a boolean release flag defaulting to the old behavior"). Note whether the change is a net-new path (the flag-off control renders nothing, so a guarded rollout must lean on existing global/service metrics — feature-specific before/after comparisons are one-armed) or an incremental change to a live path (both variations exercise comparable code, so feature-specific metrics compare cleanly); this tells the release step what its rollout can actually measure. Point them at the flag create skill to actually create it. If the flag you're suggesting will target (a rule, individual target, or percentage rollout) rather than being a plain on/off switch, also point them at Context Availability so the targeting names a context kind/attribute that actually exists where the flag is read.

If the recommend-flag tool is not available in your environment, emit the exact same object as a fenced ```json block labeled recommend-flag so it can still be parsed, then give the prose summary.