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"]