production-surveillance

Overview

Production Surveillance provides six operationally read-only analysis workflows for a synthetic deepwater-gas field. The Morning Field Report can add a self-contained Highcharts dashboard, and the Anomaly Investigation fans out three isolated domain checks in parallel before applying the safety veto. After either workflow, the skill can offer once to create an opt-in recurring surveillance watch. It produces evidence-bound analysis and proposed external handoffs, never field commands or claims of execution.

Workflow

<Definition - Synthetic fixture> All bundled data under references/ and evals/files/ is synthetic. references/tiger-data-sample-response.json contains the 27-well field snapshot, references/formation-tops.json contains two synthetic formation summaries, references/petrophysics-summary.json contains pre-computed results derived from synthetic well-log sidecars, and evals/files/ contains synthetic LAS 2.0 logs for SK-14 and SK-22. None represents a real field, customer, or operator. </Definition - Synthetic fixture>

<Definition - Signed scenario margin> The hydrate signed scenario margin is current temperature minus inhibited equilibrium temperature. A positive value means the synthetic temperature is above the inhibited hydrate curve. It is not a field-certified operating margin. </Definition - Signed scenario margin>

<Definition - Safety veto> A BLOCK from the Safety Compliance Check overrides every other finding. An UNKNOWN safety result also withholds the proposed handoff until the evidence gap is resolved. The agent must not offer APPROVE while either condition remains. </Definition - Safety veto>

<Definition - Domain result> Each isolated Anomaly Investigation task returns one status from PASS, CAUTION, BLOCK, or UNKNOWN. A failed, malformed, unavailable, or timed-out task is UNKNOWN for that domain, never PASS. The parent agent retains the failure reason in the recommendation card. </Definition - Domain result>

<Definition - Human decision> APPROVE records approval for an external handoff only. MODIFY changes assumptions or proposed parameters and requires the affected calculations and safety screen to run again. REJECT records the rejection reason and holds the current state. None executes a field command. </Definition - Human decision>

<Definition - Partial report> A report labeled PARTIAL contains only completed calculations, names every failed or missing input, and makes no conclusion that depends on unavailable evidence. </Definition - Partial report>

<Definition - Production Surveillance watch> An opt-in recurring local Quick scheduled task that runs the bundled well_deviations and alarms operations. A RED alarm invokes Anomaly Investigation and stops at the human decision boundary. The watch never auto-approves or executes an operational action. </Definition - Production Surveillance watch>

<Workflow - Well Log Ingestion description="Read a confined LAS 2.0 unwrapped well log, resolve curve aliases, normalize supported units, run the existing petrophysics sequence, and report evidence limits." tools=[file_read, run_python] triggers=["read this LAS file", "ingest well logs", "what curves are in SK-14", "parse a LAS 2.0 well log"]

1. [Agent] Read README.md ## Pre-requisites, references/analysis-basis.md, and references/script-interface.md. Verify run_python is available. Identify the requested path as bundled synthetic data under evals/files/ or user-supplied data, and ensure it resolves within WORKSPACE_DIR. Validate: The Python tool and references are available, the source label is explicit, and the path contains no parent traversal and stays within WORKSPACE_DIR. If fails: Stop, return UNKNOWN, and name the missing tool, reference, or confinement error. Never copy data outside the workspace to bypass confinement.

2. [Agent] Run scripts/run_las_reader.py operation read_metadata with the documented path argument. Validate: The response has status: success, version: 2.0, wrap: NO, a finite null value, a non-empty well section, and a curve inventory. If fails: Preserve the documented error code. Wrapped LAS, LAS 3.0, a missing ASCII section, or malformed metadata returns UNKNOWN and must not continue to petrophysics.

3. [Agent] Pass the returned curve mnemonics to operation resolve_aliases. Identify GR, NPHI, RHOB, and RT; also retain depth and every unresolved mnemonic in the inventory. Validate: The response has status: success; every input mnemonic appears once; the mapping source is recorded; required curves for each requested calculation are known. If fails: Return alias status UNKNOWN. Continue only calculations whose required canonical curves are unambiguous.

4. [Agent] Run operation read_curves with the same path and optional source-unit depth_min and depth_max. For bundled SK-14 and SK-22 reservoir calculations, use the intervals in references/analysis-basis.md. Remove any row containing null in a curve required by the next calculation, and report the removed-row count. Validate: Raw and canonical arrays have equal sample counts, JSON null represents the LAS null value, canonical units are FT for depth, GAPI for GR, V/V for NPHI, G/CC for RHOB, and OHMM for RT when those source curves exist. If fails: Preserve the error code and return curve data UNKNOWN. Never substitute, interpolate, or model a malformed or missing value.

5. [Agent] Using only aligned non-null canonical arrays and the constants in references/analysis-basis.md, call scripts/run_petrophysics.py in this order: density_porosity from RHOB; shale_volume from GR; effective_porosity from density porosity and shale volume; archie_water_saturation from RT and effective porosity; then net_pay from depth, effective porosity, water saturation, and shale volume. Validate: Every response has status: success, arrays remain aligned, the input and output units match references/script-interface.md, and no model arithmetic replaces a failed operation. If fails: Mark the failed operation and all dependent operations UNKNOWN, retain independent successful outputs, and label the result PARTIAL.

6. [Agent] Report the source label, LAS version and wrap, well metadata, original curve inventory, canonical mapping, units, source and retained row counts, depth interval, each successful petrophysics result, constants and cutoffs, null-row handling, and evidence gaps. State the professional-review disclaimer from Rule 11. Validate: Bundled SK-14 or SK-22 is labeled synthetic, user-supplied data is not mislabeled synthetic, every number traces to script output or references/analysis-basis.md, and no field action or certified interpretation is claimed. If fails: Remove unsupported claims and rebuild the report only from successful script results and committed references.

</Workflow - Well Log Ingestion>

<Workflow - Morning Field Report description="Build a synthetic morning production report and optional self-contained dashboard with field status, anomalies, petrophysics context, economics, safety screening, and a human handoff decision." tools=[file_read, run_python, run_python_with_write, open_in_session_tab, get_current_time, agent_management, memory_management, list_scheduled_agents, create_scheduled_agent, recall_memories, save_to_memory] triggers=["generate a morning field report", "run production surveillance", "summarize the synthetic field", "review today's production anomalies"]

1. [Agent] Read README.md ## Pre-requisites. Verify run_python is available. Check whether the optional html_design, highcharts, agent_management, and memory_management built-ins are enabled. If the user supplied LAS, require LAS 2.0 unwrapped text within WORKSPACE_DIR; if the user supplied DLIS, require external conversion to validated JSON. Validate: The required Python tool is available, LAS input is supported and confined or DLIS input is validated JSON, and optional built-in availability is recorded. If fails: Stop for a missing required tool or unsupported well-log input. Continue without an unavailable optional capability, state the reduced scope, and keep the Markdown report available.

2. [Agent] Read references/analysis-basis.md and references/script-interface.md. Record the run time with get_current_time. Run scripts/run_tiger_fixture.py against references/tiger-data-sample-response.json using the documented {"operation": ..., "arguments": {...}} envelope for field_summary, well_deviations with threshold_pct: 10, and alarms with severity: all. Validate: Each result is valid JSON with status: success; the field summary contains 27 wells and the deviation and alarm outputs retain fixture timestamps. If fails: Retry only a malformed invocation once. Then label the report PARTIAL, name each failed operation, and omit dependent conclusions.

3. [Agent] Read references/formation-tops.json. When bundled or user-supplied LAS 2.0 unwrapped input is available, run <Workflow - Well Log Ingestion> through its calculation and reporting steps and use only successful outputs for petrophysics context. Otherwise read references/petrophysics-summary.json as the fallback. Confirm any fallback covers only SK-14 and SK-22 and identify its pre-computed calculation sequence and cutoffs. Validate: The selected source is labeled bundled synthetic or user-supplied, LAS output has status: success for every retained calculation, or the fallback JSON is valid and contains SK-14 and SK-22 without implying coverage of all 27 wells. If fails: Mark petrophysics context UNKNOWN, name the failed LAS operation or missing fallback, and continue the independent field and economics sections as a partial report.

4. [Agent] Run scripts/run_economics.py for daily_revenue with gas_rate_mmscfd: 1004, gas_price_per_mmbtu: 3.5, btu_per_scf: 1050, condensate_bpd: 68000, and condensate_price_per_bbl: 72.5. Run deferred_production twice with the same price and heating value: once with constrained_wells holding SK-14 at current_rate_mmscfd: 22 and potential_rate_mmscfd: 38, and once with shut_in_wells holding SK-14 at potential_rate_mmscfd: 38. Argument names are in references/script-interface.md. Validate: The script returns $58,800/day current deferral and $139,650/day full-well exposure, with all assumptions repeated in JSON. If fails: Mark economics UNKNOWN; do not calculate replacements or label any value as avoided savings.

5. [Agent] If the report proposes the external handoff in references/analysis-basis.md, run scripts/run_tiger_fixture.py operation safety_compliance for SK-14 with that proposed action and action class chemical. Validate: The result includes verdict, blocking, precedent_basis: active_alarm_set, and execution_status: not_executed. If fails: Treat safety as UNKNOWN, withhold the handoff, and do not offer APPROVE.

6. [Agent] Produce a Markdown report containing: synthetic-data disclosure; analysis and fixture timestamps; field summary; active alarms; deviations; SK-14 and SK-22 petrophysics status; explicit economics assumptions; separate current-deferral and full-exposure values; safety result; evidence gaps; exact script operations used; and the professional-review disclaimer. Validate: Every numeric claim traces to a successful result or committed reference, failed sections are labeled UNKNOWN or PARTIAL, and no operational action is described as executed. If fails: Remove unsupported claims and rebuild only from retained evidence.

7. [Decide] Are both html_design and highcharts enabled? Validate: Availability is determined from step 1.

   • Yes: Continue to the dashboard location step.
   • No: Present the complete Markdown report, state which built-in is unavailable, skip the dashboard location and build steps, and continue to the human decision step. If fails: Preserve the Markdown report as the fallback, skip the dashboard location and build steps, and continue to the human decision step.

8. [Ask user] Ask where to save the optional HTML dashboard. Accept a user-confirmed location or the current session workspace. Validate: A writable destination is explicitly confirmed before any file is created. If fails: Keep the Markdown report in chat, skip the dashboard build step, and continue to the human decision step.

9. [Agent] Load the built-in highcharts and html_design skills. Build one self-contained HTML file using the vendored Highcharts from those skills, with no CDN or external dependency. Include a field-production column chart; an SK-14 rate, pressure, and temperature trend with the 14.22 degC inhibited hydrate curve as a separately labeled line; an active-alarm table; and separate cards for $58,800/day current deferral and $139,650/day full-well exposure. Generate the HTML only from successful prior results, write it to the confirmed location with run_python_with_write, and open it with open_in_session_tab. Validate: The file opens, contains all four requested views, uses only vendored Highcharts, labels the fixture synthetic, and keeps both economics figures in separate cards with their $3.50/MMBtu and 1,050 BTU/scf basis. If fails: State that dashboard rendering failed and present the complete Markdown report as the fallback. Do not replace Highcharts with a CDN.

10. [Ask user] If safety is not BLOCK or UNKNOWN, present the proposed handoff with execution_status: not_executed and ask for exactly one decision: APPROVE, MODIFY, or REJECT. If safety is BLOCK or UNKNOWN, present the withheld handoff and request MODIFY or REJECT instead. Validate: A blocked or unknown case offers no APPROVE path; otherwise the response matches one human decision. If fails: Re-state the safety result and decision boundary, then ask again without taking action.

11. [Decide] On APPROVE, record approval for external handoff only. On MODIFY, collect changed assumptions, rerun affected calculations, rebuild the report and dashboard if requested, and reapply safety. On REJECT, record the reason and hold current state. Then run <Workflow - Scheduled Surveillance Offer> unless this report was launched by the watch. Validate: The final record retains execution_status: not_executed; a modified case was recalculated and rescreened; the scheduling check was invoked once for an owner-initiated run. If fails: Reset the status to not executed, keep the report in chat, and state which decision, save, or scheduling step failed.

</Workflow - Morning Field Report>

<Workflow - Anomaly Investigation description="Investigate a synthetic well anomaly by dispatching flow assurance, reservoir constraints, and safety compliance in parallel, then synthesize one safety-gated recommendation card." tools=[file_read, run_python, get_current_time, start_task, create_task_group, get_task_group_result, inspect_task, agent_management, memory_management, list_scheduled_agents, create_scheduled_agent, recall_memories, save_to_memory] triggers=["SK-14 pressure is spiking and rate is dropping, run a full investigation", "investigate the RED alarm", "run a full investigation on a well", "review the production anomaly end to end"]

1. [Agent] Read README.md ## Pre-requisites, references/analysis-basis.md, and references/script-interface.md. Verify run_python, create_task_group, start_task, and get_task_group_result are available. Record the analysis time with get_current_time. Validate: Required tools and both references are available, and the script contract is loaded before any command is assembled. If fails: Stop, name the unavailable tool or reference, and do not simulate parallel results.

2. [Agent] Read current alarm evidence first by running run_tiger_fixture.run({"fixture":"references/tiger-data-sample-response.json","operation":"alarms","arguments":{"severity":"RED"}}. If the request names a well, rerun with well_id added. If no well is named and exactly one RED well is returned, select it; if multiple RED wells are returned, ask the user which well to investigate. Validate: Alarm output has status: success, every selected alarm is current fixture evidence, and exactly one well_id is selected. If fails: Return anomaly status UNKNOWN, preserve the script error, and request a well identifier or valid alarm evidence.

3. [Agent] Assemble isolated-task inputs for the selected well: complete active-alarm JSON; any user-supplied proposed action or rate; and aqueous MEG weight percent only when explicitly supplied or committed for that well in references/analysis-basis.md. For SK-14, use the committed proposed external handoff and 21.5 wt% basis. For another well without a supported proposal, use "hold current state and request qualified review" with action class other. Validate: Every value has a successful tool, user, or committed-reference source; volumetric MEG rate was not converted to weight percent. If fails: Set the unsupported input to null and require the affected task to return UNKNOWN rather than inventing it.