> ## Documentation Index
> Fetch the complete documentation index at: https://badixth-dc85e378.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Field Scouting: AI-Assisted Task Assignment and Guided Routes
> Turn satellite anomaly detection into GPS-guided scouting routes, and turn every alert into an AI-briefed task that tells the assignee why, what, when, and how - grounded in your crop literature.
Field Scouting is where the platform's signals become work. Every scout task is either created **from an alert or risk card** (with an AI-generated brief) or **from a scouting plan** (a route derived from anomaly-ranked zones). Both paths feed the same completion event back into the [Risk Model](/concepts/risk-model) and [Activity & Alerts](/guides/activity-and-alerts), closing the loop between satellite signals and ground truth.
Every completed scout task can escalate, demote, or reset the severity of the rule card that spawned it. See `activity_bindings` in the [Risk Model](/concepts/risk-model#activity-bindings).
## Two paths to a scout task
Click **Open scout task** on any Risk Monitoring card or field alert. The platform pre-populates the task with an **AI brief** (why, what, when, how) drawn from the matching rule card and diagnosis page. You pick the assignee and the task is ready.
Generate a full-field route from the latest NDVI map. The system ranks anomalous zones and lays out a time-efficient walking order. Use this for periodic scouting or when no specific risk is driving the visit.
## Path 1: AI-assisted assignment from an alert or risk
This is the primary path for reactive scouting. It answers the four questions an assignee should never have to guess.
From [Activity & Alerts](/guides/activity-and-alerts) or the Risk Monitoring dashboard, open the entry that needs ground confirmation. Every field alert and risk card has an **Open scout task** action.
The task draft opens with a pre-generated brief in four fixed sections. This is the same schema the AI advisor uses, so the assignee sees a familiar structure.
| Section | Populated from |
| -------- | -------------------------------------------------------------------------------------------------------------- |
| **Why** | The alert or risk summary, the rule card `drivers` that fired, and the current severity band. |
| **What** | The `mitigation.actions` from the rule card, filtered to scout-relevant steps. |
| **When** | `mitigation.window_days_by_severity` for the current severity, minus any elapsed time. Renders as a countdown. |
| **How** | The crop-specific `field-walk-protocol.mdx` and diagnosis page excerpt from `literature_ref` on the rule card. |
Select a teammate. The platform surfaces the three teammates with the shortest recent scout-response time for the field's zone, and flags anyone already at task capacity. Change assignee at any time before completion.
The AI proposes a sample size and pattern based on the rule card:
* **Sample size** - default from `drivers` confidence (e.g., 8 tillers for a blast confirmation).
* **GPS points** - centroids of the affected zones, ranked by severity.
* **What to record** - a checklist of the specific symptoms named in the diagnosis page (e.g., "diamond-shaped lesions", "collar rot", "whiteheads").
Adjust any of these before assigning.
Click **Assign**. The task appears in the assignee's mobile app queue immediately, and a `task.assigned` entry lands in their [Activity & Alerts](/guides/activity-and-alerts) feed. Delivery channel follows the assignee's Notification Preferences.
### What the assignee sees
The mobile task view mirrors the desktop brief so nothing is lost in translation:
* **Header** - field, zone, severity, countdown to mitigation window close.
* **Why** - one paragraph, plain language. No jargon unless the term is defined inline.
* **What to do** - numbered checklist. Each item is tap-to-complete.
* **When** - visible countdown; turns red inside the last 24 hours.
* **How** - collapsible field-walk protocol with the specific symptoms illustrated by photos from the diagnosis page.
* **Ask the advisor** - opens a chat grounded in the same rule card, in case the scout hits something unexpected.
The AI brief is generated once when the task is created, and re-generated whenever the underlying rule card's severity changes. The assignee always sees the current window and current action list, not a stale copy.
### Example brief
For a HIGH blast risk at booting on field A2:
* **Why**: "Leaf wetness has exceeded 40 hours in the last 7 days and night temperatures are inside the 20-28 C blast window. NDRE is 0.06 below expected. Blast risk score 0.72 (HIGH). Booting stage; neck-blast window opens in 24-48 hours."
* **What**: "Sample 8 tillers each at the 3 highest-severity zone centroids. Record: presence of diamond-shaped lesions, collar lesions, node rot. Photograph any lesion found. Flag block for preventive fungicide if lesions confirmed on 2 or more tillers per zone."
* **When**: "3 days remaining. Complete before Fri 14 Jun."
* **How**: The [rice field walk protocol](/guides/Crop/Rice/field-walk-protocol) and [Blast](/guides/Crop/Rice/biotic/diseases/blast) sections on symptom identification.
## Path 2: Generating a full-field scouting plan
Use this when there is no specific alert driving the visit. It is the same functionality that existed before AI-assisted assignment.
Open any field from the **Fields** page, then click the **Scouting** tab in the field detail panel. Any previously completed scouting sessions are listed here by date.
Click **Generate Scouting Plan**. The system analyses the latest NDVI map, identifies the 5-10 most anomalous zones ranked by severity, and places a numbered scouting point at the centroid of each zone. Points are ordered into a time-efficient route using nearest-neighbour path optimization.
Inspect each numbered point on the map. Click a point to view its NDVI value, severity rank, zone area, and the date of the source imagery. Drag any point to a more accessible location if terrain or obstacles make the auto-placed position impractical.
Click **Export to Mobile**. If you are logged in to the SemaiSens mobile app on your phone, the route syncs automatically. Alternatively, scan the QR code displayed on screen to open the route directly on any paired device.
In the mobile app, navigate to each numbered point using the built-in GPS guidance. At each point, record your observations:
* Attach one or more **photos** of the crop or symptom
* Add free-text **notes** describing what you see
* Tag a **pest or disease flag** from the built-in lookup list
* Mark the point as **Resolved**, **Monitoring**, or **Action Required**
When you return to connectivity, tap **Sync** in the mobile app. All observations, photos, and flags upload to the platform and are attached to the scouting session. The completed session appears immediately in the field's Scouting tab.
## Completion feeds the risk model
Every completed scout task emits an event the [Risk Model](/concepts/risk-model#activity-bindings) can act on:
| Scout outcome | Event | Effect on the source rule card |
| ------------------------------ | -------------------------------------------------- | --------------------------------------------------------------------- |
| Symptom confirmed | `scout.completed` with `lesions_confirmed = true` | Severity escalates (typically to CRITICAL). |
| No symptom found | `scout.completed` with `lesions_confirmed = false` | Contradiction alert raised; recommend re-scout or check other causes. |
| Ambiguous / needs lab | `scout.completed` with `needs_confirmation = true` | Severity held; soil test or lab sample task suggested. |
| Task overdue in critical stage | `task.overdue` | Severity promotes one band automatically. |
This is what makes the loop closed: the AI does not just brief the scout, the scout's finding **updates the AI's model** for the next decision.
## Mobile App
Download the SemaiSens app from the App Store. Supports iPhone and iPad. iOS 15 or later required.
Download from the Google Play Store. Android 10 or later required. Works on phones and rugged field tablets.
### Offline mode
The mobile app is designed for areas with poor connectivity. When you export a scouting route or receive an AI-briefed task, the underlying NDVI map tiles, task brief, diagnosis excerpt, and photo references download to your device automatically. You can navigate, record observations, take photos, and add notes with no data signal. Everything queues locally and syncs the next time the device connects to Wi-Fi or a cellular network.
Do not force-close the app immediately after returning to connectivity. Allow the sync progress indicator to reach 100% before closing to ensure no observations are lost.
## Scouting Reports
After a session syncs, SemaiSens automatically generates a PDF scouting report. Each report includes:
* **Field name** and date of scouting session
* **NDVI context map** with scouting points overlaid
* **Observations table** - point number, GPS coordinates, severity flag, and notes for each stop
* **Photo gallery** with captions tied to each scouting point
* **Summary statistics** - number of points visited, percentage flagged as Action Required
* **Rule card outcome** - for AI-briefed tasks, the resulting severity change on the source rule card
Scouting reports are eligible source events for [Verification](/guides/verification). A completed, geo-referenced scout report attached to a satellite pass on the same date is one of the strongest ground-truth records a subsidy or takaful assessor can receive.
### Downloading reports
Find completed reports under the **Reports** tab in the left sidebar. Click any report to preview it or click **Download PDF** to save it locally. You can also retrieve reports programmatically:
```http theme={null}
GET https://api.example.com/v1/reports/{id}
Authorization: Bearer
```
```json theme={null}
{
"id": "rpt_01j9sct",
"type": "scouting",
"field_id": "fld_01j8xyz",
"generated_at": "2024-07-15T14:22:00Z",
"download_url": "https://api.example.com/v1/reports/rpt_01j9sct/download"
}
```
Schedule a scouting session at least once per week during peak vegetative growth and at every critical growth stage (tillering, heading, grain fill). Regular ground-truth data makes the platform's anomaly detection significantly more accurate for your specific crop and soil conditions over time.
## Task lifecycle
Task states were referenced across this page and in the [Audit Envelope](/snippets/audit-envelope) without ever being enumerated. This section enumerates them. **Every state below is cited to behaviour the platform already has**; nothing here is new, and where the evidence runs out the row says so rather than inventing a state.
### The four resting states
| State | Meaning | Evidence |
| ----------- | ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `draft` | Created, nobody against it | Audit rows record `scout_task` → `draft` per [Audit Envelope](/snippets/audit-envelope) |
| `assigned` | A name against it, not yet accepted | Same audit sequence, `draft` → `assigned`. Carries a future date where the work is scheduled ahead |
| `accepted` | The assignee has taken it; the work is under way | Implied by "reassign-**before-acceptance**" and by the escalation on tasks with "no acceptance within 2 hours" (see [Guardrails](#guardrails)). A task in this state is what that table calls **in-flight** |
| `completed` | Finished. **Append-only** — a correction is a new entry, never an edit | "completion is append-only", and `scout.completed` in [Risk Model activity bindings](/concepts/risk-model#activity-bindings) |
There are four.
### Two things that are not states
**Overdue is a flag, not a state.** `task.overdue` is an **event** in [activity bindings](/concepts/risk-model#activity-bindings) that fires `promote_severity`. A task past its window is still `assigned` or `accepted` — it is late, not elsewhere. Nothing transitions *into* overdue and nothing transitions out of it by action; only the clock and the work decide it.
**Refusal returns the task to `draft`.** An assignee may decline. The docs track this — three refused assignments by the same scout in seven days escalates to their supervisor, and a recent refusal streak raises a soft warning — so the refusal and its author are retained on the task as history. The task itself has no assignee again, so it rests at `draft` carrying that record. Refusal is a transition with a memory, not a fifth state.
### A projection is not the state
**A board's columns are not these four states.** Any surface grouping tasks reads state **plus two attributes**, and stating that here is the point of this section:
| Column on a board | Resolves from |
| ---------------------- | ---------------------------------------------------------------------------------------- |
| To do | `draft` — including a task refused, and a task assigned with a future date not yet asked |
| Waiting to be accepted | `assigned`, where the assignee has been asked and the acceptance clock is running |
| In flight | `accepted` |
| Done | `completed`, within whatever window that surface declares |
The distinction between the first two columns is **whether the assignee has been asked**, not the state. A task assigned for next Tuesday has an assignee and no running clock; putting it beside tasks whose two-hour escalation is live would mix two different things under one heading.
### Transitions
| From → to | What it is | Who | What it costs |
| ------------------------ | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `draft` → `assigned` | Assigning | Anyone entitled to assign on that field | Refused where the assignee has no field access. Confirmed on bulk across estates. Soft-warned on volume and refusal streak |
| `assigned` → `draft` | Unassigning, or the assignee refusing | The assigner, or the assignee | Commits optimistically with the **5-second undo** already used for reassign-before-acceptance. Retains who and when |
| `assigned` → `accepted` | Accepting | **The assignee.** Acceptance is the act that stops the two-hour escalation clock, so it cannot be performed on their behalf without making that clock meaningless | — |
| `accepted` → `completed` | Completing | The assignee, or anyone entitled to close | **Confirmed**, and more heavily where closing without a visit or without photos. Irreversible past the undo window |
| `completed` → anything | — | — | **Refused.** Completion is append-only; a correction is a new entry |
### Not decided here
* **Whether a "mark as started on their behalf" action should exist.** If it does, it is a different verb from acceptance, needs its own audit distinction, and must not stop the escalation clock. Requires a decision before any surface offers it.
* **A per-role permission table for these transitions.** The refusals above constrain by entitlement and by assignee identity, but the docs carry no task-permission matrix equivalent to the one in [Finding Provenance](/concepts/finding-provenance). Until one exists, entitlement is the only gate.
* **Whether this lifecycle governs work items other than scout tasks** — application plans, prescription exports, proof packs. It is written here because this is where task states were already described, and it may need to graduate to a concept page if it turns out to be general.
## Guardrails
This module follows the shared [guardrails template](/snippets/guardrails-template). The agent and every non-agent write path must respect these rules.
| Category | Rule |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Input validation** | Task requires: `field_id`, `assignee_id`, `source` (alert, risk, plan), and a populated **why/what/when/how** brief. Geometry of the target zone must be within the field boundary. The advisor pre-fills all of these from Sense + Interpret; the user reviews rather than authors. |
| **Preconditions** | Field must have an active crop cycle. Assignee must have read access to the field and belong to the same estate or an authorized cross-estate role. |
| **Refusals** | Assigning to a user without field access. Suppressing a task that originates from a **severity ≥ high** rule card (safety floor). Creating a task on a closed cycle. |
| **Confirmations** | Closing a task without a visit or without photos (irreversible: completion is append-only). Deleting an in-flight task that has already emitted events. Bulk assignment across estates. Everything else, including create, reassign-before-acceptance, and edit-brief, commits optimistically with a 5-second undo. |
| **Soft warnings** | Scout already has many open tasks (surfaces the count; user can proceed). Field has received many tasks recently. Assignee has a recent refusal streak. Duplicate brief detected against a recent task on the same rule card version. |
| **Rate and scope limits** | Bulk assignment capped at N tasks per action (org-configurable) because of notification blast radius. No hard cap on total open tasks per scout; workflow volume is a soft warning, not a refusal. |
| **Audit** | Every task write logs actor, source (UI, API, agent), rule card ID and version, assignee, timestamps, and any severity band changes triggered by `activity_bindings`. Completion writes are append-only and cannot be edited after sync. |
| **Escalation** | Task overdue past `mitigation.window_days_by_severity` escalates to the estate manager. Three refused assignments by the same scout in 7 days escalates to their supervisor. Severity-critical tasks with no acceptance within 2 hours page the on-call role. |
## Related
* [Activity & Alerts](/guides/activity-and-alerts) - the feed where every task assignment, completion, and escalation is recorded.
* [Activity Log](/guides/activity-log) - the same events as a Gantt timeline for planning and stand-ups.
* [Risk Model](/concepts/risk-model) - the rule cards that power AI briefs and the `activity_bindings` scout completions trigger.
* [VRA Maps](/guides/prescription-maps) - the natural follow-up when a scout confirms a hazard and a variable-rate response is needed.
* [Verification](/guides/verification) - turn completed scout sessions into satellite-stamped proof for subsidy, takaful, and NADMA claims.
* [Fields Workspace](/guides/fields-workspace/overview) - the map-first workspace where most scout tasks are created via the quick-action FAB.