Rulestead rulesets are designed to stay readable under change. A flag has one default outcome and an ordered list of rules. Evaluation is simple: first matching rule wins; otherwise the default applies.
Ruleset Shape
At the public API boundary, app code and operators should reason about four things:
- the flag identity and default value
- the ordered rule list
- reusable audiences referenced by rules
- optional variants and rollout weights on rules that need stickiness
That is the model to preserve when authoring or reviewing a flag. You do not need to learn internal evaluator modules or admin LiveView assigns to operate it safely.
Author In The Same Order You Expect To Debug
Put rules in the order you want them explained later:
- most specific allow or treatment rules first
- broader cohort rules after that
- the default value last, outside the rule list
Because evaluation is first-match-wins, rule order is not presentation-only. If you reorder rules, you may change live behavior.
Keep Rules Focused
Good rulesets are narrow and intention-revealing:
- one rollout step per rule
- one audience idea per reusable audience
- one reason an operator can explain in plain language
If a rule starts carrying several unrelated conditions, split it. If several flags repeat the same targeting logic, move that logic into a reusable audience.
Supported Condition Families
Phase v0.1.0 supports bounded attribute predicates inside rules:
- equals
- in
- not_in
- gt
- lt
- gte
- lte
- regex
- exists
Rules can also reference reusable audiences so you do not copy large condition sets into every flag.
Reusable Audience Impact Preview
Operators manage reusable Audience definitions (the product term — internal
code may use segment_match). Before publish or archive of a shared audience,
run an impact preview against the preview basis: authored state ±
explicit samples only.
Previews carry uncertainty by design. They do not claim exact affected-user or population counts. Treat preview output as bounded guidance, not a census.
Audience references fail closed when assets are missing, archived, incompatible, stale, or tenant-mismatched. Always confirm environment scope and tenant scope — same-name audiences in different env/tenant contexts are not assumed equivalent.
The mounted companion at /admin/audiences follows preview → confirm →
audit for audience mutations. Use that workflow instead of bypassing preview
when editing shared audiences.
Variants And Weights
Multivariate flags keep stable variant keys and authored rollout weights.
Weights must add up to 100, and deterministic bucketing keeps the same
targeting key in the same bucket for the same rule.
That gives operators a predictable question to ask during rollout work:
- Which rule matched?
- Which bucket did this targeting key land in?
- Which variant weight owned that bucket range?
Those answers show up again in explainability and rollout workflows.
Draft Then Publish
When you author rules through the admin package, treat draft and publish as separate moments:
- save draft while editing rule order, conditions, or variant weights
- publish when the ruleset is ready to become runtime truth for that environment
This is especially important when multiple operators review the same flag. The mounted admin UI preserves that distinction at the package boundary without making internal LiveView state part of the contract.
Review Checklist
Before you publish or merge a ruleset change, confirm:
- the default value is safe if every rule misses
- the rule list reads top-to-bottom in business priority order
- sticky rules have a clear targeting-key strategy
- reused audiences are named for business meaning, not implementation trivia
- an on-call engineer could explain the outcome from the ruleset alone
Where To Go Next
- Use Evaluation for payload-first runtime calls.
- Use Rollout when a ruleset change is part of a staged release.
- Use Explainability when you need to read a decision back to a support or incident audience.