exit-zone-geosteering

Overview

Exit Zone Geosteering turns a deterministic logging-while-drilling stream into auditable verification, economics, exit-warning, handover, decision-review, replay, and dashboard outputs. It stores JSONL observations below the Amazon Quick workspace. Every observation carries confidence, reasoning, and source citations. Quick reports evidence and projections. It does not interpret the geology or generate a steer.

Workflow

<Definition - Skill data root> A relative directory below WORKSPACE_DIR, defaulting to exit-zone-geosteering-data. Every script rejects absolute paths and paths that escape WORKSPACE_DIR. </Definition - Skill data root>

<Definition - Observation> A JSON object persisted as one line in wells/{wellbore_id}/observations.jsonl. It includes id, type, value, confidence, reasoning, source, wellbore_id, depth_md, timestamp, feature, and schema version. </Definition - Observation>

<Definition - Confidence> A deterministic weighted score: curve agreement 0.45, offset match 0.25, and conservative margin 0.30. Acceptance is inclusive at 0.65. The emitted reasoning names each factor, value, weight, contribution, and cited source. </Definition - Confidence>

<Definition - Warning tiers> At or below 10 minutes is Escalate, above 10 through 30 is Warn, above 30 through 60 is Watch, and above 60 produces no alert. </Definition - Warning tiers>

<Definition - Crossing key> A tuple of boundary zone, boundary measured depth, and Warn or Escalate tier from a persisted exit_alert. The scheduled watch compares the pre-run set of crossing keys with the new result so each threshold crossing is surfaced once. </Definition - Crossing key>

<Definition - Canonical script input> The request object passed to every script. For SYN1 it is {"workspace_dir":"{workspace_dir}","wellbore_id":"SYN1","data_root":"exit-zone-geosteering-data"}, where {workspace_dir} is replaced with the workspace directory supplied by Amazon Quick. For another validated well, replace only the wellbore value. See references/script-interface.md. </Definition - Canonical script input>

<Workflow - Verify description="Seed a deterministic well when needed, compare its trailing stand with the zone model, and persist an auditable pay-zone delta." tools=[file_read, run_python_with_write] triggers=["verify well SYN1", "compare live pay to the model", "verify geosteering observations"]

1. [Agent] Read README.md ## Pre-requisites and references/script-interface.md, then confirm file_read and run_python_with_write are available. Validate: Both required built-in tools are available. If fails: Stop, name the missing tool, and do not access or create data.
2. [Agent] Extract the wellbore identifier, defaulting to SYN1, and validate it against ^[A-Za-z0-9._-]+$. Validate: The entire identifier matches the allowlist. If fails: Stop and ask for an identifier containing only letters, digits, period, underscore, or hyphen.
3. [Decide] Check whether the skill data root contains wells/{wellbore_id}/stream.jsonl. If absent, read the three reference JSON files and scripts/create_synthetic_well.py, then run create mode with the parsed references. Validate: The script returns status=created, 19 records, and the requested wellbore_id; each reference retains source and as_of. If fails: Report the script error and stop without running verification.
4. [Agent] Read scripts/run_verification.py and execute it with run_python_with_write using <Definition - Canonical script input>. Validate: Output contains P30, P50, live pay, model pay, confidence, threshold, accepted, factors, reasoning, and source; the persisted observation matches. If fails: Name missing data or report the exact script error, then stop.
5. [Decide] Compare confidence with the emitted threshold. Validate: accepted equals confidence >= threshold and the factor contributions re-add to confidence. If fails: Treat the observation as rejected, report the mismatch, and never price it.

</Workflow - Verify>

<Workflow - Price Impact description="Calculate deterministic correct-now and hold-three-stands dollar outcomes from an accepted verification." tools=[file_read, run_python_with_write] triggers=["price impact for SYN1", "calculate geosteering value", "compare correct now with holding three stands"]

1. [Agent] Read the prerequisites and script interface, confirm file_read and run_python_with_write, and validate the wellbore identifier per Rule 3. Validate: Required tools are available and the identifier matches. If fails: Stop and report the missing tool or invalid identifier.
2. [Agent] Confirm the data root contains the price deck, zone tops, and an accepted payzone_delta observation. Validate: Price has source, as_of, numeric usd_per_bbl; the delta has accepted=true and numeric P50. If fails: Run <Workflow - Verify> only when its prerequisites exist; otherwise name the missing prerequisite and stop.
3. [Agent] Read scripts/run_price_impact.py and execute it with <Definition - Canonical script input>. Validate: Output has exactly correct_now and hold_3_stands, each in USD, plus full deterministic basis and sources. If fails: Report the script error and do not calculate a replacement figure.
4. [Agent] Present both outcomes exactly as emitted and state that generated text may not alter them. Validate: Displayed values equal JSON values to the cent and cite the pay-zone observation and price deck. If fails: Re-read the JSON and replace the presentation with exact values.

</Workflow - Price Impact>

<Workflow - Zone-Exit Warning description="Project the next zone boundary from trajectory rate and classify the result as Watch, Warn, or Escalate." tools=[file_read, run_python_with_write, agent_management, memory_management] triggers=["check zone exit", "run a zone-exit warning", "assess exit-zone risk"]

1. [Agent] Read the prerequisites and script interface, confirm file_read and run_python_with_write, and validate the wellbore identifier per Rule 3. Validate: Required tools are available and the identifier matches. If fails: Stop and report the missing tool or invalid identifier.
2. [Agent] Confirm two advancing timestamped depth records and references/zone_tops.json exist below the data root. Validate: Timestamps and depths advance, and at least one zone base lies ahead of the bit. If fails: Report whether rate or boundary data is missing. Do not guess an ETA.
3. [Agent] Read scripts/run_zone_exit.py and execute it with <Definition - Canonical script input>. Validate: Output is no_alert or includes boundary, depth, margin, rate, ETA, and a tier consistent with <Definition - Warning tiers>. If fails: Report the script error and stop without emitting a warning.
4. [Agent] Present tier, ETA, margin, rate basis, confidence, reasoning, and citations. Preserve steer: null. Validate: The response states that Quick does not interpret the geology or generate the steer. If fails: Remove steering direction and restate only the emitted projection.
5. [Decide] If this is an interactive standalone run, continue to <Workflow - Scheduled Watch Offer>. If called by Replay, Decision Review child task, or a scheduled task, skip the offer. Validate: Exactly one branch is selected from invocation context. If fails: Skip the offer rather than risk asking repeatedly.

</Workflow - Zone-Exit Warning>

<Workflow - Decision Review description="Gate on Verify, run price and exit analysis in parallel isolated tasks, run handover, and render one cited decision card." tools=[file_read, run_python_with_write, start_task, create_task_group, get_task_group_result, inspect_task, get_current_time, agent_management, memory_management] triggers=["run the geosteering decision review for SYN1", "what should the geosteerer look at right now", "full exit-zone check"]

1. [Agent] Read README.md ## Pre-requisites and references/script-interface.md; confirm every required Decision Review tool is available; validate the wellbore_id; capture the workspace directory supplied by Amazon Quick as workspace_dir; set the relative data_root; and serialize the exact <Definition - Canonical script input> object. Validate: Tools are available, identifier matches Rule 3, workspace_dir is a non-empty string, data_root is relative, and the input JSON parses to exactly workspace_dir, wellbore_id, and data_root. If fails: Stop before Verify and report the missing tool or invalid input.
2. [Agent] Run <Workflow - Verify> in the parent context before creating any task group. Validate: A complete payzone_delta observation was persisted and its confidence arithmetic is valid. If fails: Stop before dispatch and report the Verify error.
3. [Decide] Inspect Verify acceptance and choose exactly one branch:
   • accepted=true: continue to parallel dispatch.
   • accepted=false: stop before dispatch and render one decision card with verification REJECTED, both parallel features NOT RUN, no handover, and no steer generated. Validate: The accepted flag matches the 0.65 inclusive threshold, and no task group is created for the rejected branch. If fails: Treat the verification as rejected, report the threshold mismatch, and stop before dispatch.

4. [Agent] Call create_task_group, then call start_task twice without awaiting either task so both run in parallel. Attach both tasks to the group and use the fast model tier. Pass these self-contained prompts, substituting only the validated values:

   Price task prompt: You are an isolated deterministic Price Impact worker with no conversation history. wellbore_id={wellbore_id}; data_root={data_root}; workspace_dir={workspace_dir}; exact request JSON={input_json}. Use file_read to read the complete references/script-interface.md and scripts/run_price_impact.py. Inside run_python_with_write: import run_price_impact as script (the sandbox exposes bundled scripts on the import path by file stem) and call script.run({input_json}) with workspace_dir in that object. Never read or assign __file__, __dict__, or any dunder attribute; the sandbox blocks them. Never compile or exec the source yourself. Do not invoke a subprocess, mutate os.environ, modify sys.path, import another bundled script, or reimplement main. Make at most two run_python_with_write attempts. Return exactly {"feature":"price_impact","status":"ok","observation":<complete unmodified impact_estimate observation>} or, after at most two failed sandbox attempts, {"feature":"price_impact","status":"unknown","error":"<exact error>"}. The observation must contain id, type, value.scenarios with correct_now and hold_3_stands USD, value.basis, confidence, reasoning, and source. Do not invent, alter, or round any number.

   Zone task prompt: You are an isolated deterministic Zone-Exit Warning worker with no conversation history. wellbore_id={wellbore_id}; data_root={data_root}; workspace_dir={workspace_dir}; exact request JSON={input_json}. Use file_read to read the complete references/script-interface.md and scripts/run_zone_exit.py. Inside run_python_with_write: import run_zone_exit as script (the sandbox exposes bundled scripts on the import path by file stem) and call script.run({input_json}) with workspace_dir in that object. Never read or assign __file__, __dict__, or any dunder attribute; the sandbox blocks them. Never compile or exec the source yourself. Do not invoke a subprocess, mutate os.environ, modify sys.path, import another bundled script, or reimplement main. Make at most two run_python_with_write attempts. Return exactly {"feature":"zone_exit_warning","status":"ok","observation":<complete unmodified exit_alert observation>}, {"feature":"zone_exit_warning","status":"no_alert","projection":<complete unmodified projection>}, or, after at most two failed sandbox attempts, {"feature":"zone_exit_warning","status":"unknown","error":"<exact error>"}. An alert must contain tier, ETA, margin, boundary, rate, steer null, confidence, reasoning, and source. Do not infer a steer or alter any number.

   Validate: One group exists, exactly two tasks are attached, both prompts contain wellbore_id, data_root, workspace_dir, exact request JSON, script path, the complete temporary-module exec plus run(request) recipe, the subprocess and environment-mutation prohibitions, the two-attempt bound, and the required output shape; both tasks were started before either result was awaited. If fails: Mark any task that did not start UNKNOWN; continue with a started sibling. If neither starts, continue to handover with both features UNKNOWN.

5. [Agent] Poll the task group with at most eight get_task_group_result calls, stopping early when both tasks are terminal and waiting at least five seconds between non-terminal calls. After the eighth call, call inspect_task exactly once on the oldest still-running task, then mark every task that is still running UNKNOWN. If and only if every task in the group failed and every failure contains 503 or service_overloaded, create exactly one replacement task group, restart both tasks with the same prompts, and apply the same eight-call polling bound. Never retry a mixed-result group, an individual task, or a replacement group. Map each terminal envelope by feature, not completion order. Validate: No group receives more than eight result calls; waits separate non-terminal polls; inspect_task is called at most once per group and only after its eighth non-terminal result; still-running tasks become UNKNOWN; and at most one whole-group retry occurs, only when all original failures are 503 or service_overloaded. If fails: Stop polling immediately, mark each unresolved feature UNKNOWN with the last exact status or error, preserve every successful result, and do not retry again.
6. [Agent] Run <Workflow - Shift Handover> in the parent context after task collection, even when one feature is UNKNOWN. Validate: Result is a complete handover with integrity pass or exact provenance_failure details. If fails: Set provenance status to UNKNOWN, preserve the feature results, and do not draft a handover manually.
7. [Agent] Render exactly one <Template - Decision Card>. Use Verify for confidence and its cited reasoning; use only Price Impact values for both dollar branches; use only Zone-Exit Warning for tier, ETA, and margin; use Shift Handover for provenance. Any failed feature is UNKNOWN. Include No steer is generated. Validate: One card contains every required field, exact figures, citations, provenance status, and no steering direction. If fails: Rebuild the single card directly from the four workflow outputs without filling missing values.
8. [Agent] Continue to <Workflow - Scheduled Watch Offer> after the card is delivered. Validate: The offer workflow performs both durable checks before asking anything. If fails: Do not offer in this run.

</Workflow - Decision Review>

<Workflow - Shift Handover description="Check lineage integrity and create a deterministic shift handover from persisted observations." tools=[file_read, run_python_with_write, get_current_time] triggers=["generate handover", "create shift handover", "check geosteering provenance"]

1. [Agent] Read prerequisites and script interface, confirm all required tools, validate the wellbore identifier, and call get_current_time for the report-generation label only. Validate: Tools are available, identifier matches, and calculations use observation timestamps rather than wall-clock time. If fails: Stop and report the missing tool or invalid identifier.
2. [Agent] Confirm wells/{wellbore_id}/observations.jsonl exists and is non-empty. Validate: Every line parses with id, type, source, wellbore_id, and timestamp. If fails: Name the missing or malformed line and stop.
3. [Agent] Read scripts/create_handover.py and execute it with <Definition - Canonical script input>. Validate: Output is a handover with integrity.status=pass or status=provenance_failure with exact orphan details. If fails: Report the script error and do not draft a handover manually.
4. [Decide] If provenance passes, present what happened, open alerts, zone status, price impacts, and lineage. If it fails, present the orphan list and stop. Validate: Failed integrity never produces or claims a completed handover. If fails: Withdraw the handover and show the exact integrity result.

</Workflow - Shift Handover>

<Workflow - Dashboard description="Project persisted stream and observation data, build a local Highcharts dashboard, and open a plain fallback when chart skills are unavailable." tools=[file_read, run_python_with_write, open_in_session_tab] triggers=["show geosteering dashboard", "open exit-zone dashboard", "render geosteering status"]

1. [Agent] Read prerequisites and script interface, confirm required file, write, and tab tools, validate the wellbore_id, and check whether both built-in highcharts and html_design skills are enabled. Validate: Required tools are available, identifier matches, and chart-skill availability is recorded as both available or fallback required. If fails: Stop only for a missing required tool or invalid identifier. A missing chart skill selects fallback.
2. [Agent] Read assets/dashboard.html and scripts/create_dashboard.py, then run the projector with template plus <Definition - Canonical script input>. Validate: Output reports status=projected, confined data_output and fallback_output, observation count, stream count, and all five chart-series counts. If fails: Report the template or projection error and stop.
3. [Decide] When both chart skills are available, load highcharts and html_design. Use file_read to load data_output, then build the self-contained dashboard programmatically inside run_python_with_write. Parse the projected JSON with json.loads; create one series payload containing lwd_curves, trajectory, zone_bands, confidence_trend, and alert_feed; serialize that payload exactly once with json.dumps(..., separators=(",", ":")); inject that literal unchanged into the HTML; and make every Highcharts series read from the injected payload. Never type or copy a chart value by hand. Use the Highcharts code vendored by the built-in skills, never a CDN. Include: LWD channel curves against measured depth; a curtain-section trajectory with measured depth reversed and plot bands from zone_bands; confidence versus depth from confidence_trend; and a time-ordered alert feed from alert_feed. Retain summary cards, deterministic economics, citations, and the no-steer statement. Write it below the data root as outputs/{wellbore_id}-dashboard.html. Validate: The HTML contains all four required views; all five projected series are present; extracting the injected series literal produces UTF-8 bytes identical to json.dumps of the corresponding data_output values; no chart value was manually entered; no script or stylesheet URL starts with http:// or https://; and no third-party JavaScript was written under assets/. If fails: Select fallback_output, state that interactive charts could not be generated or failed byte-identity validation, and continue.
4. [Decide] When either chart skill is unavailable, select fallback_output and state which built-in skill was unavailable and that the dashboard is plain HTML without interactive charts. Validate: The fallback path comes from the projector and includes LWD, trajectory, zone, confidence, alert, economics, evidence, and history tables or an honest empty state. If fails: Report both chart and fallback failures and stop.
5. [Agent] Open the selected HTML path with open_in_session_tab and report whether it is Highcharts or fallback plus the observation count. Validate: The selected dashboard opens and the report matches the projector output. If fails: Report the output path and ask the user to open it manually. Do not claim it opened.

</Workflow - Dashboard>

<Workflow - Replay description="Optionally reseed SYN1, advance one deterministic tick at a time, and report the warning-tier progression." tools=[file_read, run_python_with_write] triggers=["replay SYN1", "replay SYN1 from the start", "run geosteering replay", "advance the well until an exit warning"]

1. [Agent] Read prerequisites, script interface, references, scripts/create_synthetic_well.py, scripts/run_verification.py, and scripts/run_zone_exit.py; confirm file_read and run_python_with_write; capture workspace_dir; and validate the wellbore_id and data_root. Validate: Required tools and files are available, workspace_dir is a non-empty string, identifier matches Rule 3, and data_root is confined. If fails: Stop before creating, replacing, or appending data.
2. [Decide] Inspect the stream before appending. If it is absent, create it with exactly 12 ticks and the three parsed reference objects. If it exists, execute run_zone_exit.run with <Definition - Canonical script input> to calculate its current tier. Select the reseed-offer branch when the user asked to replay from the start or the existing tier is Warn or Escalate; otherwise preserve the stream. Validate: An absent stream becomes a deterministic 12-record stream; an existing stream receives no appended tick during inspection; and the offer branch is selected from the explicit request or the script result, not guessed. If fails: Report the inspection or seed error and stop without appending a tick.
3. [Ask user] On the reseed-offer branch, offer to replace the synthetic replay data with a fresh 12-tick seed: The current replay starts at {{current_tier_or_requested_start}}. Reseed SYN1 with 12 ticks so replay shows Watch -> Warn -> Escalate over several appended ticks? If accepted, call create_synthetic_well.run with workspace_dir, data_root, wellbore_id, ticks: 12, and all three parsed references. If declined, preserve the current stream. Skip this question when the stream was absent and step 2 already created 12 ticks. Validate: Reseeding occurs only after acceptance or for an absent stream; create mode honors ticks: 12; the resulting stream has 12 records ending at 10055.5 ft; and references retain source and as_of. If fails: Preserve the existing stream when possible, report the exact reseed error, and stop rather than claim replay-from-start.
4. [Decide] Set the replay stop condition. For a newly created or accepted 12-record reseed, record seed tier Watch as tick 0 and continue until the first Escalate, recording the first appended tick for each later tier. For a preserved stream, stop at the first appended Warn or Escalate. Validate: A 12-record baseline projects Watch at 44.5 minutes and 44.5 ft; the selected stop condition matches the seed branch. If fails: Stop before appending rather than use an ambiguous replay goal.
5. [Agent] Begin a bounded in-session loop of at most 100 iterations. On each iteration execute create_synthetic_well.run with {"workspace_dir":"{workspace_dir}","mode":"append_tick","wellbore_id":"{wellbore_id}","data_root":"{data_root}"}, then execute run_zone_exit.run with <Definition - Canonical script input>. Execute run_verification.run only when the appended depth lies inside a zone in references/zone_tops.json (TargetZone top is 10070.0 ft); while the bit is still above the first zone top, report verification: skipped, bit above zone top for that tick. Use the source-exec recipe in references/script-interface.md. Do not start a scheduler and do not run the scheduled-offer branch. Validate: Exactly one stream record is appended per iteration; its id, depth, and timestamp advance; Zone-Exit runs after every append; Verify runs on every tick whose depth is inside a zone and is reported as skipped otherwise; and every request includes workspace_dir. If fails: Stop at the failed tick, report its index and exact error, and preserve earlier appended data. A no zone reference covers the latest bit depth error from Verify on a tick above the zone top is not a failure; treat it as the skipped case.
6. [Decide] Inspect the Zone-Exit result after each tick. Record each tier only on its first occurrence. For a reseeded replay, continue through Watch and Warn, then stop immediately on the first Escalate. For a preserved replay, stop immediately on the first Warn or Escalate. Report tick number, tier, ETA, margin, confidence, reasoning, and sources for each first crossing, and state that no steer is generated. Validate: The 12-record replay reports Watch at tick 0, first Warn at appended tick 3 with 29.5 minutes and 29.5 ft, and first Escalate at appended tick 7 with 9.5 minutes and 9.5 ft; no tick is appended after the selected stop tier. If fails: Stop rather than advance past an unclassified or inconsistent result.
7. [Decide] If 100 iterations finish without the selected stop tier, report the bound and last projection without inventing a crossing. Validate: The report says the stop tier did not occur and contains no fabricated tier. If fails: Report only the completed tick count and exact last script output.

</Workflow - Replay>

<Workflow - Scheduled Watch Offer description="Offer once to schedule a deduplicated exit-zone watch after an interactive decision review or warning." tools=[agent_management, memory_management] triggers=["Called after an interactive Decision Review", "Called after an interactive Zone-Exit Warning"]

1. [Decide] Confirm this call follows an interactive Decision Review or standalone Zone-Exit Warning, not Replay and not a scheduled run. Validate: Invocation context is interactive and eligible. If fails: Skip the offer and stop this workflow.
2. [Agent] Call agent_management list_scheduled_agents and look for an exit-zone watch for this wellbore. Call recall_memories with Exit Zone Geosteering watch decision for {wellbore_id} and check for a prior accept or decline. Validate: Both durable signals are checked before deciding. If fails: Do not offer because offer-once status cannot be proven.
3. [Decide] If a matching schedule exists or a prior decision is recorded, skip the offer. Otherwise continue to the offer. Validate: Absence is established in both sources before asking. If fails: Skip the offer.
4. [Ask user] Offer once: Want me to run a recurring read-only exit-zone check for {wellbore_id}? It will surface a card only on a new Warn or Escalate crossing. It fires only while the machine is on and Quick is running. Validate: The user explicitly accepts or declines. If fails: Leave the on-demand workflow in place and do not record a decision.
5. [Decide] If declined, state Noted: the owner declined the Exit Zone Geosteering watch for {wellbore_id} on the current date. so memory_management records the decline. If accepted, create a recurring scheduled agent with no condition. Its prompt must: validate the same wellbore_id and data_root; read persisted exit_alert observations before running; form the existing Warn/Escalate <Definition - Crossing key> set; run <Workflow - Zone-Exit Warning>; remain silent for no alert, Watch, or a key already in the pre-run set; surface one cited card only for a new Warn or Escalate key; preserve steer: null; and never alter source data or operational systems. Then state Noted: the owner accepted the Exit Zone Geosteering watch for {wellbore_id} on the current date. so memory_management records acceptance. Validate: Decline or acceptance is recorded; acceptance also returns a schedule id, has no condition, and contains the complete dedupe prompt. If fails: Report that the watch could not be created, record no acceptance, and leave on-demand checks available.
6. [Agent] On acceptance, confirm cadence, wellbore, delivery behavior, the machine-on and Quick-running caveat, and how to cancel under Settings, Scheduled tasks. Validate: Confirmation matches the created schedule and does not promise machine-off delivery. If fails: Re-read the schedule result and correct the confirmation.

</Workflow - Scheduled Watch Offer>

<Template - Decision Card>

# Exit-Zone Decision Review: {{wellbore_id}}

**Verification:** {{ACCEPTED_OR_REJECTED}} | confidence {{confidence}} against {{threshold}}
{{verification_reasoning}}
Sources: {{verification_sources}}

| Feature | Result |
| --- | --- |
| Correct now | {{correct_now_usd_or_UNKNOWN}} USD |
| Hold 3 stands | {{hold_3_stands_usd_or_UNKNOWN}} USD |
| Exit tier | {{Watch_Warn_Escalate_no_alert_or_UNKNOWN}} |
| ETA | {{eta_minutes_or_UNKNOWN}} min |
| Margin | {{margin_ft_or_UNKNOWN}} ft |
| Provenance | {{pass_failure_or_UNKNOWN}} |

Price figures are script-owned and generated text may not alter them.
Zone reasoning: {{zone_reasoning_or_UNKNOWN}}
Sources: {{price_and_zone_sources_or_UNKNOWN}}

**Operational boundary:** No steer is generated. Obtain steering direction from the geoscience system and qualified personnel.

</Template - Decision Card>