The chat surface is the entry point. The value is the routing, reasoning, and agentic action behind it. If a chat response cannot resolve into one of four artifact types, the advisor will not produce it.
Minimum viable friction
Guardrails exist to prevent unsafe or irreversible writes, not to slow the user down. The advisor is agentic; that means it should feel like it is doing the work with you, not like it is asking permission for every step. Two rules govern how much friction is acceptable:Rule 1: Pre-fill everything you can infer
By the time the advisor presents a draft, every input it could infer from Sense and Interpret is already filled: field, block, cycle, firing rule card, severity, suggested assignee, why/what/when/how brief, target zone. The user sees a pre-filled draft, not an empty form. They review, adjust, confirm. The user is asked only when:- The action is irreversible, cross-scope, or safety-critical (see Rule 2).
- Two candidate values are equally likely and the advisor cannot resolve without input.
- A refusal is triggered and there is a viable alternative path.
Rule 2: The reversibility test
Confirmations exist for actions the user cannot easily walk back. Apply this test:Commit + undo
Reversible, single-scope, non-safety-critical. Examples: create a scout task, reassign before acceptance, draft a VRA map, edit a task brief. Advisor commits immediately and shows a 5-second undo.
Confirm first
Irreversible, cross-scope, or safety-critical. Examples: export a VRA map to a machine, apply-to-fleet across estates, close a scout task without a visit, override a “insufficient data” verification verdict, mute a severity-high+ alert.
Rule 3: Soft warnings over hard refusals
Most workflow concerns (a scout with too many open tasks, a busy day for the estate) are management issues, not safety issues. The advisor surfaces them as soft warnings the user can proceed past, not hard refusals. Hard refusals are reserved for:- Safety-critical writes (rates outside agronomic min/max, muting severity-critical alerts).
- Entitlement violations (acting on entities the user cannot see).
- Structural refusals declared by the target module.
- Actions with external cost or blast radius (agency exports, notifications at scale).
The four artifact types
Every advisor response is one of four artifacts. This is the response contract.Answer
Text with citations to data points or literature refs. No writes. No navigation. Used for informational queries where the user does not need a page context.
View
Navigate the user to a target page and apply an overlay: highlighted zones, a reasoning panel, a suggested-action strip, or a “why this page” ribbon. No writes.
Task
A concrete write to a module (scout task, VRA draft, alert mute, activity entry). Always human-confirmed before commit. Always passes the target module’s guardrails.
Proposal
A suggested change to the knowledge base (threshold edit, new mitigation action, diagnosis page revision). Never auto-applied. Always routed to a human reviewer, regardless of confidence.
Session-only memory
Semai Advisor has no per-user memory. Every session is fresh. This is deliberate.Why session-only
- Coherence. Two users asking the same question about the same field get the same answer. No divergence.
- Testability. Same input plus same identity produces the same reasoning trace.
- Safety. The agent cannot learn and internalize a user’s bad habits.
- Institutional knowledge stays institutional. Every durable learning must flow through the knowledge tiers as a Proposal, reviewed and versioned. Nothing sneaks into the model via personal drift.
- Privacy is trivial. Nothing persistent to forget.
What replaces personalization
Personalization comes from identity and launch context, not memory:- Estate manager opening chat from the Muda granary page → session pre-scoped to that estate.
- Scout opening chat on mobile → default views tuned to today’s assigned tasks.
- Regional head opening chat from the National Overview → session pre-scoped to the aggregation layer.
Knowledge tiers
Writes to knowledge (literature, rule cards, diagnosis pages) follow four tiers. The advisor plays only within tiers 1 and 2.
The advisor can flag the need for a schema change (“this pattern doesn’t fit any existing rule card type”) but cannot draft one. Structural conformance is the scalability guardrail: the agent can only ever fill in shapes your team has already defined.
Module guardrails
Every module that accepts writes declares its own guardrails using the shared guardrails template. The advisor is a consumer of module guardrails, not their author. This matters because:- Non-agent paths (UI, API, integrations) hit the same rules.
- The agent cannot escalate its own permissions.
- Refusals (the safety floor) apply to the agent identically to any other caller.
Safety floor
Regardless of session, personalization, or artifact type, the following are non-negotiable:- Severity ≥ high signals cannot be suppressed, muted beyond the bounded window declared below, or personalized away. Only presentation is personalized, never thresholds.
- The advisor cannot act on entities the user does not have access to under their identity and entitlements.
- Every Task and Proposal artifact requires explicit human confirmation before commit.
- Every write, whether by agent or human, is audited with actor, source, timestamps, and before/after values.
Mute bounds by severity
The bounded window referenced above is a per-severity mute ceiling. Muting a rule or channel for a given severity may not exceed this window; the advisor offers this value as the “bounded alternative” when a longer mute is attempted.
Dismissal of a
rulecard_firing (a 14-day suppression on the same rulecard, field, crop_cycle) is not subject to the mute bound — dismissal targets a specific firing instance, not the rule that produced it. A dismissed firing whose effective_band is critical still surfaces every re-firing on the same field during the suppression window as a new activity entry; only the notification is suppressed.
How it connects to the rest of the platform
The advisor reads across the platform and writes back through module guardrails. Nothing bypasses.1
Reads (data graph)
Live entities: Field Data, Indices, Crop Cycle Models, Risk Model rule cards, Aggregation rollups.
2
Reads (knowledge base)
Crop literature (diagnosis pages, field-walk protocols), rule card metadata, mitigation actions.
3
Navigates + overlays
Sends a View artifact: routes the user to the right page and overlays reasoning and offered actions.
4
Writes (tasks)
Sends a Task artifact: creates a scout task, drafts a VRA map, mutes an alert. Human confirms; module guardrails validate; commit or refuse.
5
Writes (proposals)
Sends a Proposal artifact: files a literature edit or threshold change. Routed to a human reviewer. Approved changes are versioned and enter the knowledge base.
6
Closes the loop
Every completed task or applied proposal emits an event back into Activity & Alerts, the Risk Model, and where applicable, Verification.
What comes next in these docs
- The Agent Loop — the five-stage loop (Sense → Interpret → Decide → Act → Close) every advisor action follows.
- Intent Taxonomy — the seven intents (Inform, Diagnose, Decide, Act, Verify, Learn, Configure) and how each maps to entry, target page, overlay, and artifact.