Update Flag Targeting

Change how an existing Harness FME feature flag serves traffic in one or more environments. Always read the current definition first, then merge-patch only what changes. Show a diff of just what changed and use plain-language before/after to describe who gets what.

Related: Segment membership changes are /manage-segments; deep flag analysis (impact, dependencies, single-flag state) is /explain-flag. Reverse-lookup scans (dependents, segment usage) are in tool-map.md.

Tools

Works through the Harness MCP server or the Harness CLI; names are from tool-map.md.

Instructions

See concepts.md for FME evaluation order, killed state, treatments vs control, and round-tripping shapes. See write-safety.md for the confirm-before-write protocol; this skill links to it and does not duplicate it.

Phase 1: Establish scope

Follow scope-establishment.md. Ask for org_id and project_id if not already known. Restate: Working in org=..., project=...

Phase 2: Gather intent

Ask only for what's missing:

1. Flag name (case-sensitive identifier)
2. Target environments (names or IDs, or "all")
3. What to change (map the user's request to one or more operations in the table below)

Phase 3: Read current state

Always fully paginate List flag definitions for the flag before planning changes in the target environments: explicitly set MCP filters.limit: 100, advance filters.offset, and stop only on a short page. size is ignored for this list. Incomplete inventory is not evidence a definition is missing; stop rather than initialize from a first-page miss. Follow pagination for environment and experiment lookups too. Never compose rules, targets, or matchers from memory — copy shapes from the live definition or another flag in the project that already uses that shape. If no example exists, warn that the shape is unverified, try it in a non-production env first, and let the API's 400 messages guide you (see schema-validation-loop.md).

Note per environment from the definition:

• isKilled (boolean), defaultTreatment, treatments (case-sensitive; read them, don't guess)
• defaultRule (array of {treatment, size} summing to 100)
• rules (array, replaced whole on update)
• trafficAllocation (0-100; keys outside it get defaultTreatment)
• individual targets and segment references (shapes undocumented; round-trip them)
• impressions.lastImpressionAt (usage signal; null = never received traffic; absent = unknown)

List environments to resolve names to IDs and note isProduction.

Phase 4: Safety checks (before planning)

Run these checks before composing the plan. Stop at the first failure and report it to the user.

Phase 5: Plan the change

Based on the user's intent and current state, compose the updated definition. See targeting-recipes.md for per-operation shape details.

Map user intent to operations:

Show a diff of just the fields that changed and state the before/after in plain language per environment. For non-production first, then production. For production environments, say: "This changes live production traffic in <env>."

Phase 6: Confirm and execute

Follow write-safety.md for the protocol (present plan → STOP → explicit confirmation → execute non-prod first → production). Comment format: "update-flag-targeting: <what> — <why>", e.g. "update-flag-targeting: ramp new-checkout to 25% in staging — FME-123".

On errors: 400 (read API error, fix field, retry once per schema-validation-loop.md); 404 (re-check identifiers, never create to fill); 409 (report as-is, stop).

Phase 7: Verify and restate

Re-read each changed environment's definition, then describe the live behavior in the same plain-language form. If it doesn't match the plan, stop.

Summarize per operation-summary.md: operation, environments changed, before/after, what was confirmed, verification, risks, UI link.

Examples

• "Ramp new-checkout to 10% in staging" — (a) Percentage rollout.
• "Add a targeting rule for beta users in production" — (c) Add targeting rule.
• "Add user-key-123 to the on treatment" — (d) Add individual targets.
• "Kill the flag in production" — (j) Kill (emergency path).
• "Copy staging config to production" — (h) Copy env to env.
• "Set up the flag in qa, it has no definition there" — (i) Initialize safe default.

Performance Notes

• One fully paginated List flag definitions inventory covers the flag's environments; it can require multiple requests. Never equate a page with the complete inventory.
• Merge-patch update: omit a field to leave it unchanged. treatments, rules, and defaultRule can't be null and are replaced whole, so always send the complete array.
• Large multi-env changes: run non-production envs first to verify the shape works before touching production.

Troubleshooting

Generic errors: see tool-map.md.

References

• targeting-recipes.md — per-operation shape details
• concepts.md — FME evaluation order, treatments, killed state
• tool-map.md — tool names, params, common errors
• write-safety.md — confirm-before-write protocol, experiment check
• scope-establishment.md — org/project scope rules
• schema-validation-loop.md — validation error recovery
• operation-summary.md — structured completion summary