Skip to main content

Best-Practice Rules

Best-practice rules are explicit constraints OpsWorker applies when reasoning about your environment. Where internal knowledge provides background context, rules provide guardrails.

The AI respects rules during both investigations and chat. A "never auto-remediate" rule means the AI never recommends an action without explicit human approval. A "prefer HPA over manual scaling" rule biases recommendations away from manual kubectl scale.

Types of Rules​

Rules fall into two broad categories:

TypePurposeExample
Hard rule (guardrail)Things OpsWorker must never do"Never recommend deleting PersistentVolumeClaims"
Soft rule (preference)Things OpsWorker should prefer"Prefer scaling via HPA changes over kubectl scale"

Hard rules act as veto conditions. Soft rules act as biases.

Good Rule Examples​

Hard rules​

  • "Never auto-remediate. All recommendations require human approval."
  • "Do not suggest deleting PersistentVolumes or PersistentVolumeClaims under any circumstances."
  • "Do not recommend kubectl exec into production pods. Use logs and events instead."
  • "Do not modify production network policies or Ingress resources without verifying impact first."
  • "Do not suggest scaling stateful sets below the configured minReplicas value."

Soft rules​

  • "Prefer Helm-based rollback over kubectl rollout undo when both are possible."
  • "When suggesting resource limit changes, base recommendations on observed Prometheus metrics, not guesses."
  • "Prefer adjusting HPA thresholds over manual scaling for HPA-managed deployments."
  • "When multiple pods are affected, mention the namespace-wide pattern rather than each pod individually."
  • "Always show the dry-run flag first when suggesting destructive operations."

What Makes a Good Rule​

  • Unambiguous — a rule that needs interpretation will be interpreted inconsistently
  • Testable — you should be able to read an AI response and know whether the rule was followed
  • Stable — rules should hold for months, not days
  • Universal — rules apply across investigations and chat, so they should make sense in both contexts

What to Avoid​

  • ❌ Style preferences ("be concise") — use AI Memory preferences instead
  • ❌ Single-incident rules ("during today's outage, don't suggest restarting X") — rules persist, situations don't
  • ❌ Contradictory rules — if rule A says "always X" and rule B says "never X", the AI will pick inconsistently

How OpsWorker Applies Rules​

Rules load into the AI's context at the start of every investigation and chat session. They sit alongside AI Memory and internal knowledge as system-level context.

When the AI generates a recommendation, it cross-references against the rule set. If a candidate action would violate a hard rule, the AI does not include it. If multiple actions are valid, soft rules bias which one is preferred.

Scope​

Best-practice rules are organization-scoped — they apply across all clusters in your OpsWorker organization. If you need a rule that applies only to one cluster, phrase it conditionally ("On the prod-us-east cluster, never...").

Editing Rules​

Rules can be edited or deleted at any time from the Knowledge Sources → Best-practice rules view. Changes take effect immediately for new investigations and chat sessions — in-flight sessions continue using the previous ruleset.

Treat rule edits as a reviewed operation. Because rules shape AI behavior org-wide, an accidental rule change can have wide impact. Consider:

  • Reviewing rule edits in a team channel before applying
  • Adding a brief rationale to each rule so future editors understand intent
  • Periodic rule audits (quarterly)

Best Practices​

  • Start with a small set. Five well-chosen hard rules is better than thirty vague ones.
  • Test rules in chat first. Ask the AI a question where the rule should apply, verify the rule was followed, then move on.
  • Pair rules with internal knowledge. Rules say what not to do; internal knowledge says how to do the right thing.

Next Steps​