Manage Segments

Manage Segments

Manage metadata for STANDARD, LARGE, and RULE_BASED segments, STANDARD membership, and approved RULE_BASED editor changes. Every mutation requires a complete reference-impact check and explicit approval. LARGE bulk membership operations are outside this skill's scope.

Tools

Works through Harness MCP or CLI with equivalent scope, confirmation and verification requirements. Discover exact CLI action syntax through command help; use tool-map.md for mappings. STANDARD in metadata examples stands for the selected type; definition/key rows apply only to STANDARD.

Instructions

Load references on demand:

• concepts.md — segments section explains STANDARD vs LARGE vs RULE_BASED and how flags reference segments
• write-safety.md — confirm-before-write protocol (production gates, verify before/after)

Phase 1: Establish scope

Follow scope-establishment.md. Ask for the org and project if missing. Restate: Working in org=..., project=...

Phase 2: Discover intent and segment context

Ask only for what is missing:

1. Operation — list, create, change membership, edit rules/exclusions, update metadata, delete, check usage
2. Segment name (case-sensitive; discover from list when ambiguous)
3. Segment type (STANDARD, LARGE, or RULE_BASED; required for all segment metadata operations; choose during create)
4. Target environments (one or more; List environments to resolve names to IDs and note isProduction)
5. Traffic type (for create only; must match the flags that will use the segment; List traffic types to discover)

Phase 3: Execute operation

Resolve exact name and type, then choose the workflow below. Before every mutation, including metadata creation, definition provisioning and key additions, complete the usage check, present its impact with the plan, and obtain production-aware approval. Incomplete checks block writes; approval never waives coverage. Discover the selected operation's exact schema before execution and preserve native org/project scope.

Find / List

• Without segment name: fully paginate all three metadata types and merge; report actual coverage, not a fixed call count.
• With segment name: resolve type and get metadata. For STANDARD, inspect environment definitions and fully paginate keys. For RULE_BASED, inspect authoritative rule-editor configuration, not an observed sample of matching keys. For LARGE, report metadata and references only. Prefer counts or redacted samples over raw user keys.
• For MCP segment metadata, STANDARD segment definitions and flag definitions, size is ignored: explicitly set filters.limit: 100, advance filters.offset, and continue until a short page. Their total is page length, not inventory size. Follow pagination for the other resources; failed/skipped pages cannot establish absence or no usage.

Create

1. Explore naming conventions from existing segments. Recommend a pattern if clear.
2. Confirm traffic type exists (List traffic types) and explain: "The traffic type must match the flags that will use this segment."
3. Choose type (immutable), check exact-name/type uniqueness, and complete the usage gate even for a new name; existing rules can contain references to it.
4. Plan metadata and environment steps separately. LARGE creation is metadata-only; RULE_BASED includes an explicitly agreed editor step. List each environment and apply the production-aware confirmation gate before writing.
5. Create approved metadata, then provision each approved STANDARD definition or guide the RULE_BASED editor step. Revalidate the gate before dependent writes; stop on a conflict or changed state.
6. Re-read changed metadata/definitions. Report metadata creation separately from membership or rules saved; never imply an unfinished step succeeded.

Add / Remove Keys (STANDARD)

Follow standard-membership.md for parsing, production-aware approval, ≤10,000-key append/removal batches and complete membership readback. A first-page check is not verification; report partial completion and never expose raw keys by default.

Usage check

Follow usage-check.md before every mutation. Scan all ACTIVE and ARCHIVED project flags and all environments, including rule matchers, treatment memberships and indirect RULE_BASED dependencies. Above 50 flags, obtain cost approval before definition reads; do not narrow a write's safety scan. Failed, skipped or unparsed coverage blocks the write. References require an explicit impact review; deletion is blocked until dependencies are separately resolved and the gate rerun.

Replace All Keys (STANDARD, Destructive)

Follow Replace all keys: fully inventory the old set, preview removals, obtain destructive-write approval, replace in one call and verify exact set equality. Stop above 10,000 keys—never chunk replacements or silently remove-then-add. Empty replacement requires an explicit clear request and confirmation.

Update Description / Tags

• Update segment (metadata) or Update definition (per-env description).
• Complete the usage gate, draft the before/after change, obtain explicit approval, then update and re-read. Distinguish metadata-only edits from changes affecting evaluation. MCP metadata uses merge patch; CLI uses declared field handlers, not guessed --set arrays. STANDARD per-environment descriptions use Update definition.