neqsim-task-workflow · diff

git:20260919.77c34a0 to git:20260926.08d0028

2271 added, 2261 removed, shown as one replacement because the pair was too large to align, first 3,000 lines shown. Audit A to A.

---

name: neqsim-task-workflow

- description: "The full NeqSim engineering task workflow that @solve-task orchestrates. USE WHEN: executing any Standard or Comprehensive task end to end - Phase 0 setup and scale classification, Phase 1 scope and research, Phase 1.5 deep analysis, Phase 2 notebooks with benchmark validation and uncertainty/risk, the Phase 1.5->2 and 2->3 quality gates, independent checks, Phase 3 report and work record, Phase 4 knowledge capture, task-type guidance (A-G), delegation to specialist agents, NeqSim Improvement Proposals, engineering interpretation in reports, critical rules, delivery, and lessons learned from solved tasks. Quick tasks need only section 0 of the agent."

- last_verified: "2026-09-18"

- ---

- # NeqSim Task Workflow

- This is the detailed procedure behind `@solve-task`. The agent file holds the

- mandatory first action, the purpose, and the operating principles (section 0);

- sections 1-10 below are loaded on demand for Standard and Comprehensive work.

- Section numbers are kept so cross-references from the agent and from

- `docs/development/TASK_SOLVING_GUIDE.md` stay valid.

- ---

- ## 0.5 ── ALWAYS-ON OBLIGATIONS (moved from the agent)

- ### Keep `user_input.md` up to date through the whole conversation

- `user_input.md` is the **reproducibility log** — anyone re-running this task

- should be able to recover the exact starting input from it.

- **Whenever the user provides new information during the task, append it to

- `user_input.md` immediately and verbatim:**

- - Answers to your clarifying questions → append to **section 2 (Q&A)**

- - Mid-task corrections, scope changes, or new constraints → append to **section 3 (Follow-up)**

- - Any value you assume because the user did not specify it → record it in **section 4 (Inferred Assumptions)** with justification

- Do NOT paraphrase, summarise, or "clean up" the user's wording. Paste it as

- given. Never delete previous entries — only append.

- ### All downloaded documents go INSIDE the task folder

- **All documents retrieved during a task — STID drawings, PI historian exports,

- vendor datasheets, P&IDs, literature PDFs, downloaded standards — MUST be saved

- to `step1_scope_and_research/references/` within the task folder.**

- NEVER download or save task-related files to workspace-level directories like

- `output/`, `figures/`, or any path outside `task_solve/YYYY-MM-DD_slug/`.

- **For STID/document retrieval scripts:** Always pass the task's `references/`

- path as the output directory:

- ```python

- # CORRECT — saves inside the task folder:

- out_dir = os.path.join(TASK_DIR, "step1_scope_and_research", "references")

- # WRONG — saves outside the task folder:

- out_dir = os.path.join(os.path.dirname(__file__), "..", "figures", "stid_docs") # NEVER DO THIS

- ```

- **For PDF-to-PNG conversion:** Output converted images to the task's `figures/`:

- ```bash

- <python-executable> devtools/pdf_to_figures.py task_solve/YYYY-MM-DD_slug/step1_scope_and_research/references/ \

- --outdir task_solve/YYYY-MM-DD_slug/figures/

- ```

- This ensures every task is self-contained and portable — zip the task folder

- and everything needed is inside it.

- ### Extract every downloaded or supplied document before solving

- The `references/` folder is not passive storage. Before any document-derived

- value, topology, limit, requirement, or recommendation enters Step 2, route

- **every file** through `technical-document-intelligence-agent` using

- `neqsim-document-intelligence-extraction`, then through the applicable

- document-type/domain reader.

- For each file:

- 1. Preserve the original and record its hash, actual format, revision/date, and

- extraction-tool versions.

- 2. Run native text and structured-table extraction first. For spreadsheets,

- retain sheets, formulas, merged ranges, hidden rows/columns, headers, and units.

- 3. Render and assess every page that contains visual or spatial information.

- Use OCR for scans and multimodal vision for drawings, P&IDs, charts, maps,

- photographs, annotations, symbols, topology, and table layout. OCR alone is

- not sufficient for visual engineering content.

- 4. Extract comprehensively: body text, tables, title blocks, notes, legends,

- appendices, footnotes, figures, plots, revision clouds, and unexpected

- engineering constraints. Do not stop after finding the fields anticipated by

- the initial task description.

- 5. Package facts with original text/value/unit, page/cell/bounding-box locator,

- method, confidence, normalized value/unit, and review status. Reconcile

- native/OCR/vision outputs without silently resolving conflicts.

- 6. Record unsupported content, missing expected fields, conflicts, ambiguous

- facts, and safety-critical or confidence-below-0.85 facts as explicit gaps or

- `needs_review` items.

- Write `step1_scope_and_research/document_evidence_manifest.json` with one entry

- for every file under `references/`, its extraction operations and status, links

- to its evidence package(s), and counts of facts/conflicts/gaps/review items.

- Summarize the evidence in `notes.md` and preserve fact identifiers in downstream

- inputs/results. The number of manifest source entries MUST equal the recursive

- file inventory count, excluding generated evidence packages and the manifest

- itself. Do not begin Step 2 while any source is `not_started` or silently

- unprocessed; record a blocked/manual-review status when extraction cannot run.

- ---

- ## 0.6 ── OPERATING ENVIRONMENTS (what each step needs)

- The workflow below was written in the NeqSim source checkout. It also runs from

- the pip-installed toolkit (`neqsim-dev-setup`, installed automatically by the

- core agent plugin's SessionStart hook) and, degraded, from chat with only the

- MCP server. Detect the environment first (agent Step 0) and apply this table.

- |---|---|---|---|

- | `neqsim new-task`, `user_input.md`, `study_config.yaml` | yes | yes | create folder by hand from the template layout |

- | `recompile=True`, `mvnw`, Java classes + JUnit (NIP implementation) | yes | **no** - write the NIP, do not attempt | no |

- | NeqSim Runner (`AgentBridge`, `neqsim_runner`) | yes | yes | no - run scripts directly or use MCP |

- | `validate_task_results`, `consistency_checker`, `TaskResultValidator` | yes | yes (Python validators; the Java `TaskResultValidator` needs the JAR, available) | Python validators not installed - state results.json was not gate-checked |

- | `skill_search` / `agent_search`, `capability_assessment.md` | yes | yes | by reasoning over the skill catalogue only |

- When a row says **no**, the deliverable matrix in the agent's section 0 still

- applies: do the step by the strongest available means and record what was

- skipped in `results.json` `data_gaps` (or in the chat answer) so the reader knows

- the evidence level.

- ---

- ## 1 ── OVERVIEW

- You follow the **3-step AI-Supported Task Solving While Developing** workflow.

- "While Developing" is key — solving the task and improving NeqSim happen in

- the same session. The workflow is aligned with the IPA Front-End Loading (FEL)

- framework and Stage-Gate methodology:

- ```

- STEP 1 → Scope & Research (FEL-1: Identify) Define standards, methods, deliverables + gather background

- STEP 2 → Analysis & Eval (FEL-2: Evaluate) Build simulation, run, validate, iterate until accepted

- STEP 3 → Report (FEL-3: Define) Generate Word + HTML deliverables

- ```

- Each step transition is a **gate** (per Stage-Gate, Cooper 1990) — the quality

- gates in Section 2 define the go/no-go criteria before advancing.

- The framework also draws on:

- - **AACE 18R-97** — Cost estimate classification (Class 5→1 maturity)

- - **ISO 15288** — Systems engineering life cycle (needs → requirements → architecture → verification)

- - **VDI 2221** — Systematic engineering design (clarify → concept → embody → detail)

- - **NORSOK Z-013** — Risk and emergency preparedness (risk matrix, ALARP)

- - **DNV-RP-A203** — Technology qualification (TRL assessment for novel solutions)

- Your deliverable is a populated task folder under `task_solve/`.

- ### Post-Folder Preflight (mandatory before Step 1 work)

- After the task folder exists and `user_input.md` contains the prompt, do these

- checks before writing Step 1 content:

- 1. **Route check.** If the task spans multiple disciplines (e.g. process +

- economics + safety), invoke `@router` first to confirm which specialist

- agents to compose. For single-discipline tasks, skip.

- 2. **Agent & skill review (ALWAYS — thorough).** Before writing any analysis,

- do a deliberate review of the available **agents and skills** to find what

- can help solve this task instead of solving from scratch:

- - Run `<python-executable> devtools/skill_search.py "<task title>" --top 5` and load the

- top-3 SKILL.md files with `read_file`.

- - Scan the agent list (community + enterprise, e.g. `.github/agents/`,

- `neqsim-community-agents/`, `neqsim-enterprise-agents/`) for discipline

- specialists whose description matches the engineering question.

- - Record the shortlist in `step1_scope_and_research/notes.md`: which

- agents/skills you will use and why, and note explicitly where **no**

- suitable agent/skill exists (that gap is a candidate improvement in the

- Continuous Improvement Rule).

- 3. **NeqSim codebase review (ALWAYS).** Before writing custom code, review the

- NeqSim codebase to find existing functionality that solves the task:

- - Consult `neqsim-capability-map` and `CHANGELOG_AGENT_NOTES.md`, then use

- `semantic_search` / `grep_search` / `file_search` over

- `src/main/java/neqsim/` for the relevant classes (equipment, EOS,

- standards, mechanical design).

- - Prefer an existing NeqSim class over a simplified Python correlation.

- - Record in `notes.md` which NeqSim classes/methods will be used, and note

- any missing capability as a gap to be closed (NIP + Java implementation

- per Section 0 principle 2 and the Continuous Improvement Rule).

- 3b. **Data-acquisition screening (ALWAYS — before assuming stand-in data).**

- List the input data the task needs (equipment curves, geometry, fluid

- composition, operating point, etc.) and, for **each** input, screen for a

- retrieval tool/agent that can obtain the *real* value before falling back to

- a representative assumption. Do NOT proceed with stand-in data for an input

- that an available data-source agent could supply. Map each need to its

- source using this table (community names shown; use the `enterprise-` twin

- when on an enterprise task):

- | Data need | Retrieve with | Notes |

- |-----------|---------------|-------|

- | Compressor/pump curves, vendor performance maps, datasheets, P&IDs, mechanical drawings, line lists, material certs | `@stid.reader` / `stid-reader-agent` + `neqsim-stid-retriever` (STID doc download → PDF/OCR → `neqsim-technical-document-reading`) | Vendor "map"/curve docs live in STID; download then extract the map digitally |

- | Piping class, pipe internal diameter, wall thickness, valve (VDS/MDS) data, flange rating | `@tr2000` / `tr2000-agent` + `enterprise-tr2000-api` | Resolve line tag → PCS → internal Ø |

- | Live instrument data / operating point (P, T, flow, speed, valve %, current recycle) | `@plant-data` / `plant-data-agent` + `neqsim-plant-data` (tagreader PI/IP.21) or `@seeq.connect` / `enterprise-seeq-connect` | Resolve historian tag from STID tag; prefer `/PRIM` channel; check units |

- | Measured production volumes (well/field) | `rigga-production-agent` + `enterprise-rigga-production` | Measured production as feed / validation basis |

- | Equipment / maintenance / failure history | `@maintenance` / `maintenance-agent` + `enterprise-maintenance-api` | Read-only work orders, notifications |

- | Fluid composition / gas-sample molweight | STID/lab report via `@stid.reader`; else record as an explicit gap | A wrong MW mis-places compressor maps — always try to obtain it |

- | Public literature / standards | `@literature-scout` | See step 6 |

- Record in `notes.md`, for every required input: the source agent/skill you

- will use, or an explicit statement that the value is a documented **stand-in

- assumption** because no retrieval path is available (and why). "The data is a

- field unknown" is only acceptable **after** the relevant retrieval agent has

- been screened (and, where feasible, attempted). For governed enterprise

- sources (STID, TR2000, tagreader, Seeq, Rigga, Maintenance, PEPR), prefer the

- corresponding coordinator agent so authentication and read-only governance

- are handled correctly.

- 4. **Repo memory scan.** List `/memories/repo/*.md` via the `memory` tool.

- Read any whose filename contains a keyword from the task title — this

- surfaces prior solved tasks and known gotchas before you reinvent them.

- 5. **Capability assessment + agent/workflow and code discovery.** For

- Standard/Comprehensive tasks, invoke `@capability-scout` and write the result

- to `step1_scope_and_research/capability_assessment.md`. As part of this step

- you MUST run BOTH discovery tools and inspect the actual NeqSim implementation

- before selecting a method. Never rely only on the static routing table,

- capability-map prose, or mirrored task sources:

- ```bash

- <python-executable> devtools/skill_search.py "<task title>" --top 5

- <python-executable> devtools/agent_search.py "<task title>" --top 8 \

- --json --out step1_scope_and_research/agent_plan.json

- ```

- Then search `CHANGELOG_AGENT_NOTES.md`, `src/main/java/neqsim/`, neighboring

- JUnit tests, and the locally resolved NeqSim dependency/JAR for the required

- equipment, thermodynamics, standards, safety, mechanical-design, and utility

- functionality. Verify constructors, method signatures, units, limitations,

- and existing tests from source before writing analysis code. When local

- source may be stale, also check current upstream `equinor/neqsim`; do not

- classify a capability as missing from a skill description or mirrored tree

- alone.

- Then, in `capability_assessment.md`:

- - fill **§4 Skills to Load** from `skill_search.py`,

- - fill **§4b Agents to Delegate To** from `agent_search.py` (agent, repo, the

- skills it loads, and why it was picked),

- - fill **§4c Workflow Plan** — choose single-agent, a `router.agent.md`

- composition pattern, or a declarative workflow (MCP `composeWorkflow` /

- `composeMultiServerWorkflow`, or an `engineering-harness` study) when the

- task spans ≥3 disciplines. Prefer delegating to a specialist agent over

- re-loading its skills manually, so its governance and internal workflow are

- reused (this is how "all functionality gets utilized").

- - add a **NeqSim Code Functionality Reviewed** table containing each required

- capability, exact class and method signatures, source/test/JAR evidence,

- availability (`Available`/`Partial`/`Missing`), units/constraints, and how

- the task will use it.

- Persist the plan so it survives context loss and feeds the report:

- - keep `step1_scope_and_research/agent_plan.json` (raw ranking, audit trail),

- - checkpoint it via `progress.store_context("agent_workflow_plan", {...})`,

- - add an `agent_workflow_plan` object to `results.json` (see schema) and

- mention the agents/workflow used in the `approach` / `method_summary` text

- so the generated report documents *how* the task was solved.

- For Quick tasks, write a short manual capability + agent note in `notes.md`

- unless a capability gap is suspected.

- 6. **Literature scout** (Standard/Comprehensive only). Invoke

- `@literature-scout` to populate `step1_scope_and_research/references/`

- and the `## Literature & Reference Documents` section of `notes.md`.

- ### Autonomous investigation (when the symptom / cause is NOT given)

- For root-cause, deviation, under-performance, trip, or "why is this happening?"

- tasks where the user has **not** told you what to look for, do not ask them.

- Run the investigation loop from `neqsim-autonomous-investigation` BEFORE fixing a

- scope, and use **all** available data and tools, not just the one tag/unit named:

- 1. **Gather all data** — pull the full historian tag map (`@plant-data` /

- `neqsim-plant-data` / `@seeq.connect`), plus alarms/events, maintenance

- history, and STID design limits when available. Save snapshots to the task

- folder.

- 2. **Observe** — hand the whole tag map (no symptom) to

- `RootCauseAnalyzer.analyzeAutonomous(tagToEquipment)` (or MCP

- `runRootCauseAnalysis` with `symptom` omitted / `"AUTO"`). It auto-detects

- abnormal tags (`AnomalyScanner`), discovers lead-lag relationships

- (`RelationshipGraph`), and classifies them against the flowsheet topology

- (`CausalTopologyModel`).

- 3. **Hypothesize / test / discriminate** — form ≥3 competing hypotheses

- (including "data/instrument artifact"), verify with the NeqSim simulation, and

- report the **discovered relationships and the discriminating test**, not just a

- single conclusion. Treat any supplied classification as a hint to challenge.

- For operational plant tasks involving P&ID symbols, valve actions, live plant

- data, active train state, isolation, evacuation, or dynamic response, load

- `neqsim-pid-process-operations` together with `neqsim-technical-document-reading`,

- `neqsim-process-extraction`, `neqsim-plant-data`, `neqsim-controllability-operability`,

- and `neqsim-dynamic-simulation`. Keep public outputs plant-agnostic; use private

- prompt files or private skills for site-specific document sources, historian

- source names, tag maps, operator procedures, and company requirements.

- Use `neqsim.process.operations` for Java deliverables and MCP `runOperationalStudy`

- for tool-based tag-map validation, field-data application, valve scenarios, and

- controller-response metrics.

- For fast liquid-hammer cases, route the extracted STID geometry, tagreader event

- window, and valve closure schedule through `neqsim-water-hammer` and MCP

- `runWaterHammer` before deciding whether a detailed surge study is required.

- ---

- ## 1.5 ── CONTEXT WINDOW RESILIENCE (checkpoint & resume)

- Long-running tasks (Standard and Comprehensive) routinely exhaust the context

- window. When this happens, the agent starts a new conversation with no memory

- of previous work. The **progress checkpoint** system solves this.

- ### How it works

- A `progress.json` file in the task folder records every completed milestone,

- key decisions, derived context, and the next action. The file is updated after

- each significant step. When a fresh agent picks up the task, it reads

- `progress.json` first and knows exactly where to resume.

- ### MANDATORY: Checkpoint after every milestone

- After completing each numbered step in the workflow below, write a checkpoint:

- ```python

- import sys; sys.path.insert(0, "devtools")

- from neqsim_runner.progress import TaskProgress

- progress = TaskProgress("task_solve/YYYY-MM-DD_task_slug")

- # After Phase 0 (classification)

- progress.complete_milestone("phase0_classified",

- summary="Type B (Process), Standard scale. 3-stage compression, SRK EOS.",

- decisions={"type": "B", "scale": "Standard", "eos": "SRK",

- "task_title": "3-stage compression from 5 to 150 bara"})

- progress.set_next_action("Write task_spec.md with standards and acceptance criteria")

- # After Step 1 (research)

- progress.complete_milestone("step1_research_done",

- summary="Research complete. Using API 617 for compressor design, "

- "NORSOK P-001 for process. Feed: rich gas, 85% methane.",

- outputs=["step1_scope_and_research/task_spec.md",

- "step1_scope_and_research/notes.md"],

- decisions={"standards": ["API 617", "NORSOK P-001"],

- "feed_composition": {"methane": 0.85, "ethane": 0.07,

- "propane": 0.05, "nC4": 0.03}})

- progress.set_next_action("Create main notebook: 01_compression_analysis.ipynb")

- # Store expensive-to-derive context

- progress.store_context("api_methods", {

- "compressor_class": "neqsim.process.equipment.compressor.Compressor",

- "power_method": "getPower('kW')",

- "polytropicEff_method": "getPolytropicEfficiency()",

- })

- ```

- ### MANDATORY: Check for resume on every session start

- When the user asks to resume a task, check that task's `progress.json` before

- doing any new work. If it exists, you are **resuming** — do NOT repeat

- completed steps:

- ```python

- import sys, os; sys.path.insert(0, "devtools")

- from neqsim_runner.progress import TaskProgress

- # Find the most recent task folder

- import glob

- tasks = sorted(glob.glob("task_solve/20*"))

- if tasks:

- progress = TaskProgress(tasks[-1])

- if progress.is_resuming():

- print(progress.resume_summary())

- # READ THIS OUTPUT. It tells you:

- # - What has been done

- # - What decisions were made

- # - What to do next

- # DO NOT REDO completed milestones.

- ```

- ### What to store in checkpoints

- | Milestone | What to save in `decisions` | What to save in `context` |

- |-----------|---------------------------|--------------------------|

- | phase0_classified | type, scale, eos, task_title | — |

- | step1_spec_written | standards, acceptance_criteria | — |

- | step1_research_done | feed_composition, operating_envelope | api_methods, neqsim_classes_used |

- | step2_notebook_created | notebook_path, simulation_approach | cell_structure, import_patterns |

- | step2_notebook_executed | key_results (T, P, power, etc.) | job_ids, output_paths |

- | step2_validation_done | validation_method, max_deviation | benchmark_data_source |

- | step2_results_saved | results_json_path | figure_list, table_data |

- | step3_report_generated | report_paths | manual_sections_content |

- ### Resume rules

- 1. **Read progress.json FIRST for resume requests.** Before searching files or planning work.

- 2. **Trust completed milestones.** Don't re-validate or re-run them unless outputs are missing.

- 3. **Re-read decisions.** These were derived with full context — use them, don't re-derive.

- 4. **Check context store.** If API method names or class paths were saved, use those directly.

- 5. **Check for runner jobs.** If job_ids exist, check their status via the AgentBridge.

- 6. **Resume from next_action.** This is the exact instruction the previous agent left for you.

- 7. **If outputs are missing** despite milestone being marked done, re-do that milestone.

- ### Break large tasks into sub-conversations

- For Comprehensive tasks (multi-notebook, multi-day), proactively break the work

- into conversation-sized chunks. After Phase 0 + Step 1, checkpoint and tell the

- user: "Step 1 is complete. Please start a new conversation and say

- `@solve-task resume task_solve/YYYY-MM-DD_slug` to continue with Step 2."

- ### MANDATORY: Read `study_config.yaml` before planning notebooks

- Every new task folder contains `study_config.yaml`. It is the explicit input

- contract for task inputs, document sources, task depth, notebook plan, report

- detail, and quality gates.

- After creating the task folder and before writing `task_spec.md` or creating

- notebooks:

- 1. Read `task_solve/YYYY-MM-DD_slug/study_config.yaml`.

- 2. Apply the intake gate before continuing:

- - If `intake.pause_after_folder_creation` is `always`, pause and ask the

- user to add or confirm missing task inputs before Step 1 work.

- - If it is `auto`, pause for Standard/Comprehensive tasks when method-critical

- values, required documents, or a fully authored config are missing.

- - If it is `never`, continue with explicit assumptions unless a missing input

- would make the calculation method invalid.

- - When pausing, tell the user the task folder path, the `study_config.yaml`

- path, and the `step1_scope_and_research/references/` drop folder. Explicitly

- say that document input is possible, including PDFs, Word files, Excel

- stream tables, P&IDs, vendor data sheets, standards, and lab reports. Do

- not create notebooks until the user confirms to continue or the required

- files are present.

- 3. If `study.scale`, `report.depth`, `notebooks.plan`, `inputs.documents`, or

- `quality_gates` are set to anything other than `auto`, treat those values as

- higher priority than scale inferred from the prompt.

- 4. If `inputs.documents_required` is true or `inputs.documents` lists source

- files, verify the files are under `step1_scope_and_research/references/`,

- classify them, extract relevant engineering data, normalize units/component

- names, validate the values, and record the extraction in Step 1 notes or

- structured JSON before building notebooks.

- 5. For Comprehensive / Development tasks, do not invent a notebook plan until

- `notebooks.plan` has been read. Create or execute the configured notebooks in

- order, and checkpoint after each notebook.

- 6. If a required configured notebook, report section, benchmark, uncertainty

- analysis, risk register, figure discussion, or consistency check cannot be

- produced, record the reason in `progress.json`, `results.json` limitations,

- and the final report.

- 7. Before Step 3, run `<python-executable> step3_report/generate_report.py`; the report

- generator reads `study_config.yaml` and warns about missing configured

- deliverables. Fix warnings marked as required before finalizing unless the

- user explicitly accepts the limitation.

- ---

- ## 2 ── WORKFLOW (follow this exactly)

- ### Phase 0: Setup — Create, Classify, and Scale

- 1. **Create or identify the task folder first.**

- - For a new task, the mandatory first action above has already created the

- folder using `neqsim new-task ... --prompt ...`. If not, create it now.

- - For a resume request, use the existing folder named by the user or the

- latest task folder confirmed by `progress.json`.

- - Read `README.md`, `user_input.md`, and `study_config.yaml` before writing

- Step 1 content.

- 2. **Confirm the task type** into one of these categories:

- - **A** — Property (density, viscosity, JT coefficient, phase envelope, etc.)

- - **B** — Process (separation, compression, dehydration, distillation, etc.)

- - **C** — PVT (CME, CVD, swelling test, saturation pressure, etc.)

- - **D** — Standards (ISO 6976, AGA, hydrocarbon dew point, etc.)

- - **E** — Feature (add new NeqSim method/equipment/model)

- - **F** — Design (wall thickness, mechanical sizing, PSV, etc.)

- - **G** — Workflow (field development, design basis, technology screening — multi-discipline)

- 3. **Determine the task scale** — this controls how deep you go:

- |-------|-----------|-----|-----------|-----------|-----------|--------|

- **Scale auto-detection rules:**

- - User mentions specific standards (NORSOK, DNV, ISO) → at least Standard

- - User asks for multiple deliverables → at least Standard

- - User says "field development", "design basis", "concept selection", "Class A/B" → Comprehensive

- - User asks a single question with no standards → Quick

- - When in doubt, ask the user: "This looks like a [scale] task — should I go deeper or keep it light?"

- **Follow-up questions (ask only when method-critical data is missing):**

- Ask these scoping questions only when missing inputs would materially change

- the calculation method, acceptance criteria, or decision recommendation.

- Otherwise proceed with explicit assumptions and continue without blocking.

- 1. **Fluid / resource**: What is the reservoir fluid composition? If unavailable,

- what type (lean gas, rich gas, oil, condensate)? What is the estimated

- resource volume (GIP/STOIIP) and its uncertainty range?

- 2. **Operating envelope**: What are the design pressure, temperature, and flow

- rate ranges? Any constraints (backpressure limit, arrival temperature)?

- 3. **Standards & jurisdiction**: Which design codes apply (NORSOK, DNV, API,

- ASME)? Which fiscal/tax regime (Norwegian NCS, UK, generic)?

- 4. **Economics**: What gas/oil price range and currency? What discount rate?

- Are cost estimates needed (CAPEX breakdown, OPEX)?

- 5. **Uncertainty scope**: Which parameters are most uncertain? Should Monte

- Carlo use full NeqSim process simulations (slower, more accurate) or

- simplified correlations (faster)?

- 6. **Deliverables**: What output format — quick answer, notebook only, or full

- Word + HTML report? Are benchmarks against published data required?

- 7. **Risk categories**: Which risk categories matter most (market, technical,

- HSE, regulatory, schedule)?

- For Quick-scale tasks, skip questions and proceed directly.

- 4. **If the folder still does not exist, create it now — non-negotiable:**

- ```

- Run in terminal: neqsim new-task "TASK TITLE" --type X --author "Agent" --prompt "<verbatim user request>"

- ```

- For long requests, save the prompt to a file and use `--prompt-file`.

- Use explicit depth inputs when the user requests a deep study, for example:

- ```

- neqsim new-task "TASK TITLE" --type G --author "Agent" --prompt "<verbatim user request>" --scale comprehensive --report-depth detailed --notebooks 5 --intake-pause always

- ```

- Or pass a fully authored configuration:

- ```

- neqsim new-task "TASK TITLE" --type G --author "Agent" --prompt "<verbatim user request>" --config-file path/to/study_config.yaml

- ```

- This creates `task_solve/YYYY-MM-DD_task_slug/` with all subfolders.

- **ALL subsequent files MUST go inside this folder. Do NOT proceed without it.**

- Read the generated README and verify `user_input.md` captured the prompt

- before continuing.

- 5. **Run the intake gate before Step 1 work:**

- - Read `study_config.yaml`.

- - Tell the user the task folder exists.

- - Ask for missing method-critical values or invite them to add documents to

- `step1_scope_and_research/references/` and edit `study_config.yaml`.

- - Explicitly say that document input is possible for the task.

- - Continue only after confirmation when `--intake-pause always` was used or

- required inputs are missing.

- 6. **Run the post-folder preflight** described in Section 1, then checkpoint.

- **CHECKPOINT (Phase 0):** After creating the task folder and classifying:

- ```python

- import sys; sys.path.insert(0, "devtools")

- from neqsim_runner.progress import TaskProgress

- progress = TaskProgress("task_solve/YYYY-MM-DD_task_slug")

- progress.complete_milestone("phase0_classified",

- summary="[1 sentence: type, scale, method]",

- decisions={"type": "X", "scale": "Standard", "eos": "SRK",

- "task_title": "..."})

- progress.set_next_action("Write task_spec.md")

- ```

- ### Phase 1: Scope & Research (Step 1)

- 5. **Fill in the task specification** (`step1_scope_and_research/task_spec.md`).

- Adapt depth to the task scale:

- **Quick scale:** Fill only the essential fields — method/EOS, one-line acceptance

- criterion, and the specific condition to calculate. Leave other sections empty.

- **Standard scale:** Fill all sections — standards, methods, deliverables,

- acceptance criteria, operating envelope, input data.

- **Comprehensive scale:** Fill every section in detail. List ALL applicable

- standards with specific clause numbers. Define a complete work breakdown of

- deliverables. Set quantitative acceptance criteria for every output. Define

- the full operating envelope with min/design/max values.

- The task spec sections:

- **Design Basis Header** (Design/Development mode — per NORSOK P-001 practice):

- - **Document ID**: Auto-generated from task folder name

- - **Revision**: Rev 0 (initial), increment on significant parameter changes

- - **Status**: Draft → Issued for Review → Approved

- - **Design life**: e.g., 25 years (or N/A for property lookups)

- - **Design code**: Primary governing standard (e.g., ASME VIII Div.1, DNV-ST-F101)

- - **Design conditions**: Summary table of design P, T, flow rate with units

- **Core sections (all modes):**

- - **Applicable standards** (MANDATORY — see below): Which codes, standards, and

- company TRs govern this task (NORSOK, ISO, DNV, API, ASME, company TR documents).

- Load the `neqsim-standards-lookup` skill for equipment-to-standards mapping.

- - **Calculation methods/models**: Which EOS, correlations, pipe flow models to use

- - **Required deliverables**: What the final output must include

- - **Acceptance criteria**: Mass balance tolerance, design factors, safety margins

- - **Operating envelope**: Range of conditions to cover (P, T, flow, composition)

- - **Input data**: Reference fluid compositions, operating conditions, equipment data

- **Standards identification (MANDATORY — proportional to scale):**

- | Scale | Standards Requirement |

- |-------|---------------------|

- | Quick | 1-line note: "Per [STANDARD]" or "N/A — property lookup" |

- | Standard | Table listing each applicable standard with scope |

- | Comprehensive | Full table with clause numbers, design values, limits, compliance evidence |

- Use the equipment-to-standards mapping from `neqsim-standards-lookup` skill to

- automatically identify standards based on the equipment types in the simulation.

- Query `designdata/standards/standards_index.csv` for the mapping.

- **Scope limitations** (Design/Development mode):

- - **In scope**: What this analysis covers

- - **Out of scope**: What is explicitly excluded (e.g., "detailed fatigue analysis",

- "site-specific seismic loads", "control system design")

- - **Validity envelope**: Conditions under which results are valid (T range, P range,

- composition range, flow regime). Results outside this envelope require re-analysis.

- - **Model limitations**: Known EOS/correlation limitations at the operating conditions

- (e.g., "SRK accuracy degrades near critical point", "Beggs & Brill not validated

- above 90° inclination")

- If the user specifies standards or methods in their request (e.g., "per NORSOK P-001"),

- incorporate these directly into the task spec. If not specified, select appropriate

- standards based on the task type and engineering domain.

- 6. **Auto-search for similar past solutions (MANDATORY):**

- Before writing any new code, search for related prior work:

- - **Semantic search** `task_solve/` folder for keywords from the current task

- - **Keyword search** `docs/development/TASK_LOG.md` for task type, equipment, fluid, standards

- - **Search** `docs/development/CODE_PATTERNS.md` for relevant patterns

- - **Search** `src/test/java/neqsim/` for existing tests covering similar equipment/fluids

- - **Search** `examples/notebooks/` for related notebooks

- - If a similar task was solved before, **start from that solution** — adapt rather than rebuild

- - Document what prior work was found (or not found) in `notes.md`

- 6b. **Gather background knowledge** for the task:

- - Search the NeqSim codebase for existing classes/methods relevant to the task

- - Check `CHANGELOG_AGENT_NOTES.md` for any recent API changes affecting this task

- - Use web search if available for engineering reference data

- - **Retrieve vendor documents** if the task references specific equipment tags.

- Load the `neqsim-stid-retriever` skill for document retrieval patterns:

- relevance filtering, retrieval manifests, and backend configuration.

- If a retrieval backend is configured (via gitignored `devtools/doc_retrieval_config.yaml`),

- auto-fetch performance curves, mechanical drawings, and data sheets.

- Otherwise, expect documents in `step1_scope_and_research/references/`.

- Users can always **add documents manually** to `references/` alongside

- auto-retrieved ones — both sources coexist and are tracked in the manifest.

- Ask the user for additional documents only when the task is Standard or

- Comprehensive and the missing documents would materially change the method,

- constraints, or recommendation. For Quick tasks, proceed with documented

- assumptions unless the calculation is invalid without the document.

- For trapped-liquid fire rupture studies, load `neqsim-trapped-liquid-fire-rupture`

- and retrieve the full evidence pack before calculation: P&ID/STID isolation

- boundaries, line lists, piping specs, material certificates, flange/bolt/gasket

- data, fire-zone/PFP documents, relief/thermal relief basis, and acceptance

- criteria. Missing evidence must be written to `results.json` as assumptions/gaps.

- - **Extract figures from reference PDFs** placed in `step1_scope_and_research/references/`:

- ```bash

- <python-executable> devtools/pdf_to_figures.py step1_scope_and_research/references/ --outdir figures/

- ```

- Then use `view_image` on extracted PNGs to read engineering drawings, P&IDs,

- charts, data tables, and compressor maps. This makes PDF content available

- for AI analysis (diagram digitization, data extraction, layout understanding).

- - **Structured image analysis workflow** (for vendor drawings, P&IDs, datasheets):

- When reference documents contain engineering drawings or visual data, use the

- `neqsim-technical-document-reading` skill Section 3.7 patterns:

- 1. **P&IDs** → Extract equipment tags, valve tags, instrument tags, piping

- sizes/classes, line numbers, and connection topology using the

- `PID_EXTRACTION` format. This provides the flowsheet topology that

- informs the NeqSim `ProcessSystem` model.

- 2. **Vendor API datasheets** (e.g., API 692 seal datasheets, API 617

- compressor datasheets) → Extract operating conditions, design data,

- performance parameters, and material specs using the

- `VENDOR_DATASHEET_EXTRACTION` format. These values become simulation

- inputs and validation targets.

- 3. **Mechanical arrangement drawings** → Extract dimensions, nozzle

- schedules, standpipe geometry (lengths, bore sizes, volumes), piping

- run lengths using `MECHANICAL_ARRANGEMENT_EXTRACTION` format. Physical

- dimensions feed into volume calculations, heat transfer models, and

- residence time estimates.

- 4. **Performance maps / phase envelopes** → Digitize key points (rated

- point, surge line, cricondentherm, operating envelope boundaries)

- using `PERFORMANCE_MAP_EXTRACTION` or `PHASE_ENVELOPE_EXTRACTION`

- format. These validate simulation results against vendor/design data.

- 5. **Generate figure discussions** — for each image analyzed that informs

- the engineering analysis, produce a figure discussion block (observation,

- mechanism, implication, recommendation) and include it in

- `results.json["figure_discussion"]` for the report.

- 7. **Write comprehensive research notes** to `step1_scope_and_research/notes.md`.

- These notes must be **substantive** — not a skeleton template.

- The depth should be proportional to the task mode.

- **Screening mode:** A condensed version covering: sources consulted, key

- data / sanity-check values, NeqSim classes used, and assumptions made.

- **Design / Development mode (full sections):**

- - **Sources** (table): Every source consulted — NeqSim classes, papers, standards,

- web references, textbooks. Minimum 5 entries for Standard tasks, 10+ for Comprehensive.

- - **Literature & Reference Documents**: For each key reference, write a structured

- summary with: file location, relevance, key equations cited, key data extracted,

- limitations, and how it applies to this specific task.

- - **Background — Engineering Context**: Explain the real-world engineering problem

- in 2-3 paragraphs. Why does this matter? What goes wrong in practice? What are

- the consequences of getting it wrong? Include industry context.

- - **Background — Physical Mechanisms**: Describe the underlying physics. What

- thermodynamic, chemical, or transport phenomena are involved? Include governing

- equations with variable definitions.

- - **Key Data / Correlations**: Reference values, design rules of thumb, typical

- operating ranges. These are the "sanity check" values used during validation.

- - **Industry Experience / Case Studies**: Known field cases, operational incidents,

- lessons learned. This grounds the analysis in reality.

- - **Relevant Standards — Detailed Requirements**: For each standard in task_spec,

- extract the specific clauses, equations, tables, and design factors that apply.

- Don't just list the standard — quote the requirement.

- - **NeqSim API Coverage — Detailed Inventory**: For each capability needed, check

- if NeqSim has it. Search the Java source code. List class names, key methods,

- and any limitations found. This feeds directly into Phase 1.5.

- - **Open Questions**: Uncertainties, missing data, things to clarify with the user

- ### Phase 1.5: Deep Analysis & Solution Design (required for high-consequence work)

- Before writing simulation code for design, workflow, safety-critical, or

- high-value economics tasks, produce a **thorough engineering analysis document**

- that gives deep insight and a clear solution path. For smaller tasks, use a

- condensed analysis section in notes and proceed.

- 7b. **Write a detailed problem analysis** to `step1_scope_and_research/analysis.md`.

- Include the following sections (depth proportional to task consequence):

- #### 7b.1 — Physics & Theory Deep-Dive

- Explain the fundamental physics/engineering behind the problem at a level

- suitable for a senior engineer review:

- - **Governing equations** with derivations or references (use LaTeX notation)

- - **Physical mechanisms** — what causes the phenomenon, why it matters

- - **Thermodynamic basis** — which EOS is appropriate and why, phase behavior

- - **Transport phenomena** — heat/mass transfer, fluid mechanics if relevant

- - **Key assumptions** — what simplifications are being made and their impact

- - **Dimensional analysis** — key dimensionless groups if applicable

- - **Order-of-magnitude estimates** — quick hand calculations to set expectations

- (e.g., "JT coefficient ~0.5 K/bar → expect ~25°C drop across 50 bar valve")

- #### 7b.2 — Alternative Solution Approaches

- List at least 2-3 different ways to solve this problem, with pros/cons:

- |----------|-------------|------|------|--------------|

- | A | ... | ... | ... | ✓ / ✗ |

- | B | ... | ... | ... | ✓ / ✗ |

- | C | ... | ... | ... | ✓ / ✗ |

- Justify the chosen approach with engineering reasoning.

- #### 7b.3 — NeqSim Capability Assessment

- **Option A (recommended for Standard/Comprehensive):** Invoke the capability

- scout agent to perform a systematic assessment:

- ```

- @capability-scout [paste the task description here]

- ```

- The scout returns a structured Capability Assessment Report covering:

- - Full capability requirements matrix with NeqSim coverage status

- - NIPs for every ❌ Missing or ⚠️ Partial gap

- - Recommended skills to load

- - Recommended agent pipeline for the task

- - Implementation priority order

- **Option B (for Quick/simple tasks):** Manually assess by checking the

- `neqsim-capability-map` skill and searching the codebase:

- |-------------------|---------------------|--------|------------------|

- **For every ❌ Missing or ⚠️ Partial gap, write a NeqSim Improvement Proposal**

- (see Section 6 below). This is how the development flywheel turns: tasks

- surface gaps → gaps become proposals → proposals become implementations.

- #### 7b.4 — Solution Architecture

- Describe the simulation/calculation architecture:

- - **Flowsheet diagram** (text-based or markdown table showing equipment order)

- - **Data flow** — what feeds into what, what outputs are needed

- - **Iteration strategy** — recycles, adjusters, convergence approach

- - **Parametric studies** — what sensitivity sweeps to run and why

- - **Expected results** — what ranges you expect before running (from hand calcs)

- #### 7b.5 — Risk & Failure Mode Analysis

- Before building the simulation, anticipate what could go wrong:

- - **Numerical risks** — convergence failure, phase identification issues

- - **Physical risks** — conditions outside EOS validity, near-critical behavior

- - **Data risks** — missing BIPs, uncertain component properties

- - **Mitigation** — fallback approaches for each risk

- #### 7b.6 — Engineering Insight Questions

- List 5-10 engineering questions the analysis should answer. These go beyond

- "what is the answer" to "what does it mean and what should we do":

- - Example: "At what H2S level does sulfur deposition become operationally significant?"

- - Example: "Is pre-heating more cost-effective than chemical inhibition?"

- - Example: "How sensitive is the NPV to gas price vs. CAPEX uncertainty?"

- These questions drive the analysis and ensure the report provides actionable insight.

- **CHECKPOINT (Phase 1 complete):** This is a natural break point. Checkpoint

- before the context-heavy notebook creation and execution:

- ```python

- progress.complete_milestone("step1_research_done",

- summary="Research complete. [key method, standards, feed comp]",

- outputs=["step1_scope_and_research/task_spec.md",

- "step1_scope_and_research/notes.md",

- "step1_scope_and_research/analysis.md"],

- decisions={"standards": [...], "feed_composition": {...},

- "simulation_approach": "...", "acceptance_criteria": {...}})

- progress.store_context("neqsim_classes", {

- "main_class": "full.java.ClassName",

- "key_methods": ["method1(args)", "method2(args)"],

- })

- progress.set_next_action("Create analysis artifact: 01_XXXX.ipynb or run_XXXX.py with [approach]")

- ```

- For Comprehensive tasks, consider telling the user: "Step 1 is complete.

- Start a new conversation with `@solve-task resume task_solve/YYYY-MM-DD_slug`."

- ### Phase 2: Analysis & Evaluation (Step 2)

- 8. **Determine the right approach** (refined from Phase 1.5):

- - Use the solution architecture from the analysis document

- - Implement the recommended approach from the alternatives assessment

- - Address each engineering insight question in the executable analysis artifact

- - For every NeqSim gap: implement the proposed improvement or use a workaround

- - Choose reasonable engineering defaults for missing input data (document assumptions)

- - **Check for data gaps** — if analysis requires documents not yet retrieved

- (e.g., mechanical drawings, instrument datasheets, P&IDs, parallel train data):

- 1. Log the gap in the notebook with what's missing and why

- 2. If a retrieval backend is configured, auto-fetch the specific doc types needed

- 3. If not, ask the user to drop the file in `references/` or provide the values

- 4. Update the retrieval manifest with `iterative_retrievals` entries

- 5. Re-extract PNGs for any new PDFs and continue analysis

- See `neqsim-stid-retriever` skill § "Iterative Retrieval During Analysis"

- 9. **Create the executable analysis artifact** in `step2_analysis/`:

- - For Quick tasks, a short runner script is acceptable when it gives a clearer,

- faster answer than a notebook. The script must use `neqsim_dev_setup.py`,

- write or merge `results.json`, and be executed by `neqsim_runner` or a

- direct verified command.

- - For Standard and Comprehensive tasks, create notebooks with VS Code notebook

- tools, `nbformat`, or valid `.ipynb`

- JSON. Raw JSON notebooks must be nbformat v4, keep cells in the top-level

- `cells` array, and include `metadata.language` for every cell. When editing

- existing notebooks, preserve existing `metadata.id` values.

- - Use the devtools setup pattern from `neqsim-notebook-patterns`: import

- `neqsim_dev_setup`, call `neqsim_init(project_root=PROJECT_ROOT, ...)`,

- then use classes through `ns.*` or `ns.JClass(...)`

- - Do not use `from neqsim import jneqsim` in task notebooks or runner jobs;

- that can use the installed Python package instead of workspace Java classes

- - The first setup cell must set `NEQSIM_MODE = "devtools"` and fail if the

- project root cannot be found

- - Follow the notebook structure from the `@solve-process` agent when creating

- notebooks.

- - Include clear markdown cells explaining each step in notebooks; for runner

- scripts, include concise printed output and comments only where they clarify

- non-obvious engineering logic.

- - Avoid interactive prompts, hidden kernel state, and shell-specific commands;

- every code cell must run from a fresh kernel in order

- - Load existing task-level `results.json` before adding artifact-specific

- results so multi-artifact runner merge preserves prior outputs

- - **Results & Figures (proportional requirement):**

- - Quick: at least one clear results table and at least one informative figure when visualization adds value

- - Standard/Comprehensive: detailed results tables and typically 2-3+ informative figures

- - Development/design deliverables should include enough figures to support recommendations

- - A **results section** that extracts key numerical outputs into

- a formatted table (pandas DataFrame or formatted print) with units

- - Typically **2-3+ matplotlib figures** for Standard/Comprehensive tasks showing the most important relationships

- (e.g., production profile vs time, pressure vs distance, temperature vs stage,

- cost breakdown bar chart, sensitivity tornado chart)

- - All figures saved to `figures/` as PNG with descriptive filenames

- - Figure captions added to `results.json` under `figure_captions`

- - A **summary comparison table** when comparing cases or validating against

- reference data

- - **Figure Discussion Cells** — add discussion cells for all decision-critical

- figures (and for all major figures in Design/Development mode). This is the

- critical link between calculations and conclusions. Each discussion cell should

- follow this pattern:

- ```markdown

- ### Discussion: [Figure Title]

- **Observation:** [What does the figure show? State the key finding with numbers.]

- **Physical Mechanism:** [Why does this happen? Explain the underlying physics,

- chemistry, or engineering reason.]

- **Engineering Implication:** [What does this mean for the design or operation?

- Compare against design limits, typical values, or industry experience.]

- **Recommendation:** [What action should be taken based on this result?

- Be specific: material selection, operating limits, equipment sizing, etc.]

- > *Links to: [reference specific key_results entries], answers insight question Q[N]*

- ```

- **Example figure discussion cell:**

- ```markdown

- ### Discussion: Temperature Profile Along Pipeline

- **Observation:** The gas temperature drops from 45°C at the inlet to -12°C at

- the outlet (Figure 2). The temperature crosses the sulfur deposition onset

- temperature (0°C) at approximately 12 km from the inlet.

- **Physical Mechanism:** The temperature drop is driven by Joule-Thomson cooling

- across the letdown valve (ΔT = -35°C for this gas composition at 120→45 bara)

- combined with heat loss to the 4°C seabed. The JT coefficient of 0.45°C/bar

- is typical for lean gas with 85% methane.

- **Engineering Implication:** Solid S₈ will precipitate in the pipeline between

- 12 km and the outlet. The deposition rate peaks at approximately 25 km where

- the gas reaches maximum supersaturation. This represents a flow assurance risk

- requiring mitigation.

- **Recommendation:** Install direct electrical heating (DEH) between 10-30 km

- to maintain gas temperature above 5°C (with 5°C safety margin above deposition

- onset). Alternatively, pre-heat gas to minimum 60°C upstream of the valve to

- keep the entire pipeline above 0°C.

- > *Links to: outlet_temperature_C = -12°C, sulfur_deposition_onset_C = 0°C.

- > Answers insight question Q3: "At what distance does deposition begin?"*

- ```

- - **Traceability Chain** (Design/Development mode, recommended for all):

- 1. **Calculation** → produces numerical results

- 2. **Figure** → visualizes the results

- 3. **Discussion cell** → interprets the figure (observation, mechanism, implication)

- 4. **Recommendation** → specific action based on the discussion

- 5. **results.json** → captures the chain in `figure_discussion` entries

- For Design/Development deliverables, every conclusion should trace back to

- specific figures and discussion cells. For Screening tasks, a brief

- interpretation paragraph after key figures is sufficient.

- - For **Type G (Workflow)** tasks: create multiple notebooks, numbered sequentially

- (e.g., `01_reservoir_fluid.ipynb`, `02_pipeline_sizing.ipynb`, etc.)

- 10. **Execute notebooks and runner scripts with supervised runner by default.** Fix errors immediately.

- 10a. **Notebook execution method — default rule (MANDATORY):**

- The default execution engine for task notebooks and scripts is `neqsim_runner`, as

- configured by `notebooks.execution_engine: neqsim_runner` in

- `study_config.yaml`. This runs notebooks in isolated subprocesses with

- their own JVMs, retry handling, persisted job state, and no manual kernel

- restart loop.

- **Use `neqsim_runner` (headless/supervised) unless `study_config.yaml`

- explicitly sets `notebooks.execution_engine: interactive`.** This is

- mandatory when ANY of these are true:

- - Standard or Comprehensive scale

- - More than one notebook

- - Parametric sweep or Monte Carlo

- - Any notebook expected to run > 5 minutes

- - Benchmark validation, uncertainty, or risk notebooks are required

- - Prior JVM crash, kernel death, hanging cell, or `RuntimeError: JVM cannot be restarted`

- **Use `run_notebook_cell` (interactive) only for quick debugging** when ALL

- of these are true:

- - `study_config.yaml` sets `notebooks.execution_engine: interactive`, or the

- user explicitly asks for interactive notebook debugging

- - Quick or Screening scale

- - Single notebook, no sweep, no Monte Carlo

- - Expected runtime < 5 minutes

- - No prior JVM/kernel crash or hanging cell in this session

- **Escalation rule:** If interactive execution hits a JVM crash, kernel death,

- hanging cell, or `RuntimeError: JVM cannot be restarted`, immediately switch

- to `neqsim_runner` for all remaining notebooks. Do not keep restarting the

- VS Code kernel and retrying interactively.

- **Runner usage:**

- ```python

- # In a standalone script or notebook orchestration cell:

- import sys; sys.path.insert(0, str(TASK_DIR.parent.parent / "devtools"))

- from neqsim_runner.agent_bridge import AgentBridge

- bridge = AgentBridge(task_dir=str(TASK_DIR))

- planned_notebooks = [

- "step2_analysis/01_analysis.ipynb",

- "step2_analysis/02_benchmark_validation.ipynb",

- ]

- # Default mode="execute" produces an executed .ipynb with all cell outputs.

- # Each run happens in an isolated subprocess with its own JVM.

- job_ids = [

- bridge.submit_notebook(notebook_path, mode="execute",

- max_retries=3, timeout_seconds=3600)

- for notebook_path in planned_notebooks

- ]

- # Run all jobs (supervisor handles retry/recovery automatically).

- # Keep max_parallel=1 unless the task owner explicitly accepts parallel JVM load.

- bridge.run_all(max_parallel=1)

- summary = bridge.summary()

- print(summary)

- if summary["failed"] or summary["pending"]:

- raise RuntimeError("NeqSim Runner jobs did not all complete successfully")

- # Merge multi-notebook outputs instead of overwriting earlier results.

- bridge.merge_results_to_task(job_ids)

- # Get the executed notebook (only for mode="execute")

- executed_nb = bridge.get_executed_notebook(job_ids[0])

- ```

- For script-only workloads, use `bridge.submit_script()` or

- `bridge.submit_parametric_sweep()` instead of `submit_notebook()`. For

- lighter notebook jobs that do not need executed `.ipynb` outputs, set

- `mode="script"`, but keep the same success check and merge step.

- **When to use the runner vs interactive notebook:**

- | Signal | → Runner | → Interactive |

- |--------|----------|---------------|

- | Task scale | Standard / Comprehensive | Quick / Screening |

- | Notebooks in task | > 1 | 1 |

- | Monte Carlo iterations | N > 50 | N ≤ 50 or none |

- | Parametric sweep cases | > 3 | ≤ 3 or none |

- | Expected wall time | > 5 min | < 5 min |

- | Previous JVM crash this session | Always switch | N/A |

- | Need interactive debugging | No | Yes |

- | Need executed .ipynb with outputs | Yes (mode="execute") | Yes |

- The runner writes outputs to `task_dir/runner_output/` and job state to

- `task_dir/runner.db`. Use `bridge.merge_results_to_task(job_ids)` for

- multi-notebook workflows so later notebooks do not overwrite earlier

- `results.json` content. The report generator inspects `runner.db` and warns

- if planned notebooks have no successful runner job. When using

- `mode="execute"`, the original notebook is backed up and updated in place

- with cell outputs.

- 10b. **Equipment feasibility checks** — for any task involving compressors,

- heat exchangers, coolers, or heaters, run a Design Feasibility Report after

- the process simulation:

- ```python

- # Compressor feasibility

- CompressorFeasibility = ns.JClass(

- "neqsim.process.mechanicaldesign.compressor.CompressorDesignFeasibilityReport")

- report = CompressorFeasibility(compressor)

- report.setDriverType("gas-turbine")

- report.setCompressorType("centrifugal")

- report.generateReport()

- print("Verdict:", report.getVerdict())

- # Add to results.json:

- import json

- feasibility = json.loads(report.toJson())

- results["equipment_feasibility"] = {

- "compressor": {"verdict": feasibility["verdict"],

- "suppliers": feasibility.get("numberOfMatchingSuppliers", 0)}

- }

- # Heat exchanger / cooler / heater feasibility

- HXFeasibility = ns.JClass(

- "neqsim.process.mechanicaldesign.heatexchanger.HeatExchangerDesignFeasibilityReport")

- hx_report = HXFeasibility(heat_exchanger)

- hx_report.setExchangerType("shell-and-tube")

- hx_report.generateReport()

- print("HX Verdict:", hx_report.getVerdict())

- ```

- Feasibility reports provide:

- - Mechanical design validation (is the machine buildable?)

- - Cost estimation (CAPEX, OPEX, 10-year lifecycle)

- - Supplier matching (which OEMs can provide this equipment?)

- - Issues and warnings (what design limits are exceeded?)

- Include feasibility verdicts in the analysis discussion and results.json.

- 11. **Validate results** — check all of these against the acceptance criteria in task_spec.md:

- - Are temperatures, pressures, and densities in physically reasonable ranges?

- - Does mass balance close (within tolerance from task spec)?

- - Does energy balance close?

- - Do results compare reasonably against reference data from Step 1?

- - Are there any NaN, Inf, or negative density values?

- - Are all required deliverables from task spec produced?

- 12. **If results fail validation**, iterate immediately:

- - Adjust fluid composition, EOS, or equipment parameters

- - Rerun the notebook

- - Document the iteration in `step2_analysis/notes.md`

- **CHECKPOINT (Phase 2 core complete):** After notebook is executed and validated:

- ```python

- progress.complete_milestone("step2_validation_done",

- summary="Main notebook executed and validated. [key results summary]",

- outputs=["step2_analysis/01_XXXX.ipynb", "figures/..."],

- decisions={"key_results": {"outlet_T_C": -18.5, "power_kW": 3500, ...},

- "validation_passed": True, "max_deviation_pct": 2.1})

- progress.set_next_action("Create benchmark/uncertainty notebooks, save results.json")

- ```

- ### Benchmark Validation (required for Development; recommended for Design when benchmark data exists)

- 12b. Create benchmark validation evidence in one of these forms:

- - Separate notebook (`XX_benchmark_validation.ipynb`) for Standard/Comprehensive tasks

- - Section within the main notebook for Quick tasks

- Prefer the community skill `neqsim-benchmark-reference-data`

- (`equinor/neqsim-community-skills`, `skills/pvt/neqsim-benchmark-reference-data`)

- over hand-writing this block: it supplies the reference sources with their

- citation, authority tier and validated range, grades PASS/WARN/FAIL, refuses

- a reference that does not outrank the model basis, enforces the three-point

- minimum, and emits `benchmark_validation` in the shape the gate and the

- report generator expect.

- Use independent reference data when available. If no suitable benchmark

- exists, use cross-validation: hand calculations, limiting-case checks,

- conservation checks, prior NeqSim comparisons, and sensitivity sanity checks.

- The type of validation depends on the task:

- | Task Type | Benchmark Sources | What to Compare |

- |-----------|-------------------|------------------|

- | A — Property | NIST, DIPPR, experiment, literature correlations | Density, Cp, viscosity, JT coefficient at reference T,P |

- | B — Process | Published simulation cases, vendor datasheets, textbook examples | Outlet T, P, power, duty, recovery |

- | C — PVT | Lab PVT reports, ECLIPSE/PVTsim results | Saturation P, GOR, Bo, Z-factor, liquid dropout |

- | D — Standards | Standard worked examples, certified lab results | GCV, Wobbe, density to published precision |

- | E — Feature | Unit-test regression baselines, existing solver benchmarks | Convergence, residuals, iteration count |

- | F — Design | Hand calculations, vendor catalogs, published design tables | Wall thickness, weight, stress, safety factor |

- | G — Workflow | Industry benchmarks, analogous field data, public project reports | CAPEX ranges, production rates, NPV/IRR bands |

- **Benchmark notebook structure:**

- 1. **Introduction** — State what is being benchmarked and why

- 2. **Reference data** — Tabulate the benchmark values with source citations

- 3. **NeqSim calculation** — Reproduce the same conditions and extract results

- 4. **Comparison table** — Side-by-side: Benchmark vs NeqSim vs % deviation

- 5. **Deviation analysis** — Plot parity chart (benchmark vs calculated), explain any deviations > 5%

- 6. **Conclusion** — State whether results are within acceptable tolerance

- **Minimum requirements (when external benchmarking is used):**

- - At least 3 benchmark data points (different conditions, components, or cases)

- - A parity plot or deviation bar chart saved to `figures/`

- - A summary table with columns: Parameter | Benchmark Value | NeqSim Value | Deviation % | Source

- - Results recorded in `results.json` under `"benchmark_validation"` key

- ```python

- # Example benchmark comparison structure in results.json

- results["benchmark_validation"] = {

- "benchmark_source": "NIST Webbook / Experiment / Published case",

- "comparisons": [

- {"parameter": "density_kg_m3", "benchmark": 820.5, "neqsim": 818.3,

- "deviation_pct": 0.27, "condition": "25C, 60 bar"},

- {"parameter": "viscosity_cP", "benchmark": 0.45, "neqsim": 0.43,

- "deviation_pct": 4.4, "condition": "25C, 60 bar"},

- ],

- "max_deviation_pct": 4.4,

- "all_within_tolerance": True,

- "tolerance_pct": 5.0

- }

- ```

- 13. **Save figures** to `figures/` directory as PNG files. **CRITICAL: use absolute paths, NOT os.getcwd():**

- ```python

- import pathlib, os

- NOTEBOOK_DIR = pathlib.Path(globals().get(

- "__vsc_ipynb_file__", os.path.abspath("step2_analysis/notebook.ipynb")

- )).resolve().parent

- TASK_DIR = NOTEBOOK_DIR.parent

- FIGURES_DIR = TASK_DIR / "figures"

- FIGURES_DIR.mkdir(exist_ok=True)

- # Then save plots:

- fig.savefig(str(FIGURES_DIR / "my_plot.png"), dpi=150, bbox_inches="tight")

- ```

- **Figure count should be proportional to task scale and decision complexity.**

- Common figure types:

- - Process profiles (T, P, flow vs. position or time)

- - Sensitivity/parametric studies (property vs. variable)

- - Bar charts for cost breakdowns, composition, or comparisons

- - Phase envelopes, PVT curves, or equipment performance maps

- Figures must have axis labels with units, titles, legends, and grids.

- 14. **Write validation notes** to `step2_analysis/notes.md`:

- - What was tested and what passed

- - Comparison against reference data (quantitative where possible)

- - Whether acceptance criteria from task spec are met

- - Any sensitivity analysis performed

- 15. **Save results.json** in the task root folder. Add a final notebook cell:

- ```python

- import json, os, pathlib

- # Resolve task directory from the notebook's own location

- # (os.getcwd() is unreliable in VS Code notebooks — it returns workspace root)

- NOTEBOOK_DIR = pathlib.Path(globals().get(

- "__vsc_ipynb_file__", os.path.abspath("step2_analysis/notebook.ipynb")

- )).resolve().parent

- TASK_DIR = NOTEBOOK_DIR.parent

- FIGURES_DIR = TASK_DIR / "figures"

- FIGURES_DIR.mkdir(exist_ok=True)

- # ── results.json schema ──

- # TIER 1 — Always required (all modes)

- results = {

- "key_results": {

- # All key numerical outputs with units in the key name

- },

- "validation": {

- # Each check maps to True/False or a numeric value

- "mass_balance_error_pct": 0.01,

- "acceptance_criteria_met": True,

- },

- "approach": "Brief description of methodology used",

- "conclusions": "Key findings with engineering interpretation",

- "assumptions": [

- # Key engineering assumptions made during the analysis

- # {"assumption": "...", "impact": "low/medium/high",

- # "confidence": "low/medium/high", "replace_with": "project data X"}

- ],

- }

- # TIER 2 — Populate when relevant (Design/Development or when produced)

- # The report generator renders these sections only if present;

- # missing keys are silently skipped (graceful degradation).

- #

- # results["approach_justification"] = "Why this approach was chosen..."

- # results["engineering_insights"] = {"Q1: ...": "Answer..."}

- # results["design_recommendations"] = ["Recommendation 1", ...]

- # results["neqsim_gaps"] = [{"nip_id": "NIP-01", ...}]

- # results["remaining_uncertainties"] = ["Uncertainty 1", ...]

- # results["figure_discussion"] = [{"figure": "...", "title": "...",

- # "observation": "...", "mechanism": "...", "implication": "...",

- # "recommendation": "...", "linked_results": [...],

- # "insight_question_ref": "Q..."}]

- # results["figure_captions"] = {"plot.png": "Description"}

- # results["equations"] = [{"label": "...", "latex": "..."}]

- #

- # TIER 3 — Populate only when uncertainty/risk/benchmark work is performed

- # results["benchmark_validation"] = {"benchmark_source": "...", ...}

- # results["uncertainty"] = {"method": "...", "p10": ..., ...}

- # results["risk_evaluation"] = {"risks": [...], ...}

- #

- # TIER 2b — Standards compliance (MANDATORY for Standard/Comprehensive)

- # Load neqsim-standards-lookup skill for equipment-to-standards mapping.

- # results["standards_applied"] = [

- # {"code": "NORSOK P-001 Rev 5", "scope": "Separator sizing",

- # "status": "PASS", "design_value": 0.13,

- # "limit": "0.12-0.15 m/s", "unit": "m/s", "clause": "Table A-1"},

- # ]

- results_path = str(TASK_DIR / "results.json")

- with open(results_path, "w") as f:

- json.dump(results, f, indent=2)

- ```

- 15a. **Validate results.json with TaskResultValidator (MANDATORY quality gate).**

- Add a cell immediately after saving results.json. This calls the Java validator

- programmatically to catch schema errors before proceeding to report generation.

- ```python

- # ── Programmatic quality gate: validate results.json ──

- TaskResultValidator = ns.JClass("neqsim.util.agentic.TaskResultValidator")

- with open(str(TASK_DIR / "results.json"), "r") as f:

- json_str = f.read()

- report = TaskResultValidator.validate(json_str)

- print(f"Valid: {report.isValid()} | Errors: {report.getErrorCount()} | Warnings: {report.getWarningCount()}")

- if not report.isValid():

- print("\n❌ ERRORS (must fix before proceeding to report):")

- for err in report.getErrors():

- print(f" [{err.field}] {err.message}")

- if report.getWarningCount() > 0:

- print("\n⚠️ WARNINGS (fix for Standard/Comprehensive tasks):")

- for warn in report.getWarnings():

- print(f" [{warn.field}] {warn.message}")

- assert report.isValid(), "results.json failed validation — fix errors above before proceeding"

- ```

- **If validation fails:** Fix the results.json contents in the cell above and re-run

- both cells. Do NOT proceed to Step 3 (report generation) with a failing validation.

- ### Uncertainty & Risk Analysis (conditional)

- 15b. Create a dedicated uncertainty/risk notebook for workflow, economics,

- reserves/resource, concept selection, or when explicitly requested.

- For smaller design/process/property tasks, uncertainty can be a compact

- section in the main notebook unless deeper treatment is needed.

- **Core principle: use NeqSim process simulations, not simplified Python models.**

- Every Monte Carlo iteration should run the same NeqSim equipment classes used

- in the main analysis. Simplified correlations are only acceptable when NeqSim

- has no equivalent class for that calculation.

- #### Uncertain Input Parameters (7–10 parameters typical)

- Always include **resource/reserve estimates** as uncertain parameters:

- |----------------|---------|--------------|----------|

- #### Monte Carlo with NeqSim

- ```python

- # CORRECT: Full NeqSim process simulation per iteration

- def run_neqsim_production(gip_volume, reservoir_pres, plateau_rate):

- fluid = SystemSrkEos(273.15 + 75.0, reservoir_pres)

- fluid.addComponent("methane", 0.90)

- # ... add components, set mixing rule

- reservoir = SimpleReservoir("res")

- reservoir.setReservoirFluid(fluid.clone(), gip_volume, 1.0, 1e7)

- well = WellFlow("well")

- pipe = PipeBeggsAndBrills("export", well.getOutletStream())

- # ... configure and run

- return gas_rate_profile, gip_gsm3

- # WRONG: Simplified Python model

- def run_simple_decline(gip_volume, plateau_rate):

- return plateau_rate * np.exp(-decline_rate * years) # NO!

- ```

- #### Performance Optimisation Patterns

- | Pattern | How | Savings |

- |---------|-----|--------|

- | **Cache SURF cost** | Compute `base_surf = SURFCostEstimator(...)` once, scale by `capex_mult` | ~3–4 min per 200 iter |

- | **Smart tornado** | Only re-run NeqSim for technical params (GIP, Pres, Rate); reuse base profile for economic params (price, OPEX, discount) | ~50% fewer tornado runs |

- | **Bisection steps** | Use 20 steps instead of 30 for decline-phase rate search | ~30% faster per iter |

- | **Early exit** | Break production loop when rate < threshold (e.g., 0.5 MSm³/d) | Skip tail years |

- | **Seed RNG** | `np.random.seed(42)` for reproducibility | Deterministic reports |

- The community skill `neqsim-uncertainty-quantification`

- (`equinor/neqsim-community-skills`,

- `skills/process/neqsim-uncertainty-quantification`) implements these patterns

- directly: a `technical`/`economic` model split that caches the expensive

- stage (this is the "smart tornado" above), Latin-hypercube sampling,

- percentiles in the ascending `p10 ≤ p50 ≤ p90` convention the gate

- enforces, a scale-invariant convergence check, and optional SALib/chaospy

- backends for the interactions a tornado cannot see. Prefer it over

- re-implementing the loop.

- #### Minimum Simulation Count (when Monte Carlo is used)

- - **With NeqSim simulations:** N ≥ 200 (each takes ~0.5–1.0 sec)

- - **Simplified models only:** N ≥ 1000

- #### Tornado Sensitivity (Smart Classification)

- ```python

- NEQSIM_PARAMS = {"gip_volume", "reservoir_pres", "plateau_rate"}

- for param in all_params:

- if param in NEQSIM_PARAMS:

- # Re-run full NeqSim simulation with low/high value

- rate_low = run_neqsim_production(param_low, ...)

- rate_high = run_neqsim_production(param_high, ...)

- else:

- # Reuse base production profile, recalculate economics only

- rate_low = rate_high = base_rate

- npv_low = calc_npv(rate_low, economic_params_with_low)

- npv_high = calc_npv(rate_high, economic_params_with_high)

- ```

- #### Risk Register (ISO 31000 5×5 Matrix)

- Include 6–10 risks across categories: Market, Technical, Cost, Schedule, HSE,

- Regulatory. Use this risk level formula:

- ```python

- score = likelihood (1-5) × consequence (1-5)

- if score >= 17: "Very High"

- elif score >= 10: "High"

- elif score >= 5: "Medium"

- else: "Low"

- ```

- #### Results.json Schema for Uncertainty

- ```python

- results["uncertainty"] = {

- "method": "Monte Carlo with full NeqSim process simulation",

- "n_simulations": 200,

- "simulation_engine": "NeqSim (SRK EOS, SimpleReservoir, PipeBeggsAndBrills)",

- "input_parameters": [

- {"name": "GIP Volume", "unit": "m3",

- "low": 0.65e9, "base": 1.0e9, "high": 1.45e9,

- "distribution": "triangular"},

- # ... all 7-10 parameters

- ],

- "output_parameter": "NPV after tax (MNOK)",

- "p10": ..., "p50": ..., "p90": ...,

- "mean": ..., "std": ...,

- "prob_negative_pct": ...,

- "resource_estimate": {

- "gip_GSm3_p10": ..., "gip_GSm3_p50": ..., "gip_GSm3_p90": ...,

- "recovery_factor_pct_p10": ..., "recovery_factor_pct_p50": ...,

- "recovery_factor_pct_p90": ...,

- "total_production_GSm3_p10": ..., "total_production_GSm3_p50": ...,

- "total_production_GSm3_p90": ...

- },

- "capex_mnok": {"p10": ..., "p50": ..., "p90": ...},

- "tornado": [

- {"parameter": "Gas Price (0.8-2.5 NOK/Sm3)",

- "npv_low": ..., "npv_high": ..., "swing": ...},

- ]

- }

- results["risk_evaluation"] = {

- "risks": [

- {"id": "R1", "description": "...", "category": "Market",

- "likelihood": "Unlikely", "consequence": "Catastrophic",

- "risk_level": "High",

- "mitigation": "Long-term contracts, hedging"},

- ],

- "overall_risk_level": "High",

- "risk_matrix_used": "5x5 (ISO 31000)"

- }

- ```

- ### Quality Gate: Phase 1.5 → Phase 2

- **When Phase 1.5 applies (high-consequence / Design / Development), verify:**

- - [ ] `analysis.md` exists with sections populated proportionate to the task

- - [ ] Physics/Theory section has governing equations and order-of-magnitude estimates

- - [ ] At least 2-3 alternative approaches listed with justified selection

- - [ ] NeqSim Capability Assessment table completed for every needed capability

- - [ ] For material gaps: improvement noted (NIP or notes.md)

- - [ ] Solution architecture described with flowsheet and expected result ranges

- - [ ] 3-10 engineering insight questions (scale to task complexity)

- - [ ] Research notes (`notes.md`) are substantive — not empty templates

- **When Phase 1.5 is skipped (Screening mode):** verify that notes.md has

- at minimum: sources consulted, key assumptions, and NeqSim classes used.

- **Hold point (Design/Development mode):** Before proceeding to Phase 2,

- present the user with a brief summary of: (1) chosen approach and why,

- (2) key assumptions, (3) expected result ranges from hand calculations.

- Ask: "Ready to proceed with simulation, or adjust the approach?"

- For Screening mode, proceed without holding.

- ### Quality Gate: Phase 2 → Phase 3

- **Core checks (all modes):**

- - [ ] Every notebook cell executes without errors

- - [ ] `results.json` exists with Tier 1 keys (`key_results`, `validation`, `approach`, `conclusions`, `assumptions`)

- - [ ] Acceptance criteria checked — pass or documented fail

- - [ ] Results table printed in notebook with units

- - [ ] Some form of validation evidence documented (benchmark, hand calc, sanity check)

- - [ ] Key assumptions listed in results.json `assumptions` array

- - [ ] `standards_applied` populated (at minimum 1-line "Per [STANDARD]" for Quick; full table for Standard/Comprehensive)

- **Additional checks (Design / Development mode):**

- - [ ] Figures saved to `figures/` as PNG; `figure_captions` populated for each

- - [ ] `equations` populated with key equations used

- - [ ] Validation notes in `step2_analysis/notes.md`

- - [ ] If benchmark notebook used: `benchmark_validation` in results.json

- - [ ] If uncertainty/risk performed: `uncertainty` and `risk_evaluation` in results.json

- - [ ] If resource uncertainty in scope: P10/P50/P90 in `resource_estimate`

- - [ ] `figure_captions` covers figures from ALL notebooks

- - [ ] Numbers consistent across notebooks (re-run all after parameter changes)

- - [ ] Engineering insight questions answered in notebook and/or results.json

- - [ ] Discussion cells for decision-critical figures

- - [ ] `standards_applied` entries include clause numbers and design values vs limits

- - [ ] `figure_discussion` populated for discussed figures

- - [ ] `design_recommendations` traceable to figure discussions

- - [ ] Material NeqSim gaps documented (NIPs or notes)

- **If any gate fails, iterate on Step 2** — do NOT proceed to reporting with

- incomplete or unvalidated results.

- ### Cross-Discipline Consistency Check (multi-agent / Type G tasks)

- When a task involves multiple disciplines (e.g., process + mechanical + flow assurance),

- verify consistency across all sub-analyses before proceeding:

- - [ ] **Phase consistency:** If thermo model says 2 phases, all downstream equipment must handle 2 phases

- - [ ] **Temperature consistency:** Outlet T from one unit matches inlet T of the next (within 0.1 C)

- - [ ] **Pressure consistency:** Outlet P from one unit matches inlet P of the next

- - [ ] **Flow rate consistency:** Mass balance across all connection points (within 0.1%)

- - [ ] **Composition consistency:** Same fluid composition used across all notebooks/analyses

- - [ ] **Design conditions consistency:** Mechanical design pressure/temperature envelopes cover all process scenarios

- - [ ] **Standards consistency:** No contradictory requirements from different standards

- - [ ] **Unit consistency:** All sub-analyses use the same unit system (SI, not mixed with Imperial)

- If any inconsistency is found, resolve it before proceeding. Document the check

- in `step2_analysis/notes.md` under a "Cross-Discipline Consistency" heading.

- ### Step 15c: Independent Check (Design/Development mode)

- Before proceeding to Phase 3, perform a self-check using the "checker hat"

- principle (analogous to IEC 61508 independent verification):

- 1. **Re-read the task_spec.md** — are all acceptance criteria addressed?

- 2. **Verify units consistency** — trace a key value from input through

- calculation to output. Do the units cancel correctly?

- 3. **Boundary check** — do results behave correctly at extreme conditions?

- (zero flow, maximum pressure, pure component)

- 4. **Sign/direction check** — does each result move in the physically

- expected direction when inputs change? (higher P → higher density,

- lower T → higher viscosity)

- 5. **Order-of-magnitude check** — compare final results against the

- hand-calculation estimates from Phase 1.5. Flag deviations > 2×.

- Document the independent check in `step2_analysis/notes.md` under a

- "Verification" heading. For Screening mode, items 3-4 are sufficient.

- **CHECKPOINT (Phase 2 fully complete):** After all notebooks + results.json:

- ```python

- progress.complete_milestone("step2_results_saved",

- summary="All notebooks executed. results.json saved with key_results, "

- "validation, uncertainty, risk_evaluation, figure_captions.",

- outputs=["results.json", "step2_analysis/01_XXXX.ipynb",

- "step2_analysis/02_benchmark.ipynb"],

- decisions={"results_json_complete": True,

- "figures": ["fig1.png", "fig2.png", "fig3.png"]})

- progress.set_next_action("Generate Word + HTML report via step3_report/generate_report.py")

- ```

- ### Phase 3: Report (Step 3)

- 15d. **Analytical depth pass (MANDATORY before writing the report).**

- Everything from here on grades whether the deliverable is *well-formed*.

- This step decides whether it is *worth reading*. Apply Principle 0 of

- `neqsim-professional-reporting` — a report that restates the task, lists

- factors without ranking them, and ends in "further study is recommended"

- passes every other gate in this agent and still fails as engineering.

- Most of these moves cannot be added at write-up time, so if the analysis

- did not produce them, **go back to Phase 2 and produce them** rather than

- writing around the gap:

- 1. **Rank the contributors on one common basis** — one table, one metric,

- so the candidate causes/levers are directly comparable → `contributor_ranking`

- 2. **Adjudicate the source document's own recommendations** — a verdict

- (`SUPPORTED` / `SUPPORTED_WITH_CORRECTION` / `CHALLENGED`) per

- recommendation, each decided by a number → `source_recommendation_assessment`

- 3. **Rule out competing hypotheses quantitatively** — with a stated margin

- and any residual caveat → `ruled_out`

- 4. **Report what the source document missed** — a contributor, coupling, or

- second-order consequence not in the original scope

- 5. **Test robustness and name the crossover** — where the conclusion or the

- ranking order would flip → `robustness`

- 6. **State the direction of every conservatism** — each screening default

- labelled upper or lower bound on the reported quantity → `conservatism`

- 7. **Name the cheapest discriminating test** — the one measurement that

- separates the surviving hypotheses, with the meaning of each outcome

- → `discriminating_test`

- 8. **Report evidence that does not fit** — as a disagreement, not smoothed over

- 9. **Convert qualitative asks into specifications** — a rating, purity,

- limit, or setpoint with the mechanism that sets it

- Also: hunt for the **natural experiment** already in the data (near-identical

- units on different duty, a repair that failed again, a period with a barrier

- out of service); **bound** an unmeasurable value by computing what it would

- have to be for the conclusion to change; and report any CFD/FEM/transient/

- Monte-Carlo result as validation → convergence check → result → what it does

- and does not decide (a quantity still moving with refinement is an artefact).

- Record `depth_score` in `results.json` (target 9/9 for Comprehensive or

- root-cause work, ≥ 6/9 for Standard) with a reason for each move not

- achieved. Give each conclusion its own "what remains open" instead of one

- lumped gap register at the end.

- 16. **Update `generate_report.py`** in `step3_report/`:

- - The report **auto-reads** `task_spec.md` and `results.json` — verify both exist

- - Fill in the executive summary with actual findings

- - Add conclusions and recommendations to `MANUAL_SECTIONS` (or rely on `results.json`)

- - Ensure all figures from `figures/` will be embedded, **including benchmark plots**

- - The Scope/Standards, Results, Discussion, and Validation sections auto-populate from data files

- - **Discussion section** auto-populates from `results.json["figure_discussion"]` —

- renders each figure's observation, mechanism, implication, and recommendation

- with traceability links. This is the core analytic content of the report.

- - If benchmark validation is performed, include a benchmark section with

- comparison table and deviation analysis from `results.json["benchmark_validation"]`

- - If uncertainty analysis is performed, include uncertainty outputs

- (P10/P50/P90, resource estimate, tornado, probability metrics)

- - If risk evaluation is performed, include a risk section with risk register

- and overall risk level from `results.json["risk_evaluation"]`

- **Report generator behaviour:**

- The `generate_report.py` template renders sections from `results.json`

- automatically. Sections with populated keys render fully; missing keys are

- silently skipped (graceful degradation). At minimum, ensure Tier 1 keys are

- present (`key_results`, `validation`, `approach`, `conclusions`, `assumptions`).

- For Design/Development tasks, also populate `figure_discussion` — it provides

- the traceability chain from results to recommendations.

- Typical section numbering for a complete report:

- 0. Document Control (rev, date, status, author, checker) |

- 1. Executive Summary | 2. Problem Description | 3. Scope & Standards |

- 4. Approach | 5. Results | 6. Discussion | 7. Validation Summary |

- 8. Benchmark Validation | 9. Uncertainty Analysis | 10. Risk Evaluation |

- 11. Conclusions | 12. Assumptions Register | 13. References

- For a problem-solving / root-cause report, add the depth sections from

- step 15d after the Discussion: a **contributor ranking** table, a

- **robustness** section naming the crossover, a **ruled out** section with

- each eliminated hypothesis and its quantitative margin, and an **assessment

- of the originating document's recommendations** verdict table. Carry the

- ranking table into the executive summary — it is the result, and burying it

- in section 6 is why a reader concludes the report said nothing.

- **Document control block** (Design/Development mode — auto-populated

- from task folder metadata):

- - Document ID: `NEQSIM-{TASK_TYPE}-{DATE}-{SLUG}`

- - Revision: `Rev 0` (initial issue)

- - Date: task creation date

- - Author: from `--author` flag in `new_task.py`

- - Status: `Draft` (updated manually to `Issued for Review` / `Approved`)

- - Calculation tool: `NeqSim {version}, {EOS used}`

- - Scope limitations: from task_spec.md (in scope / out of scope / validity envelope)

- **Assumptions register** (new section 12 — Design/Development mode):

- Auto-populated from `results.json["assumptions"]`. Renders as a table:

- Each assumption is numbered and traceable to the results it affects.

- **Stale numbers trap:** MANUAL_SECTIONS text (executive_summary, conclusions)

- contains hardcoded numbers. When design parameters change (dimensions, flow rates),

- you MUST update these strings to match the latest results. Where possible, let

- conclusions come from `results.json["conclusions"]` instead of hardcoding.

- 17. **Run consistency checker** (MANDATORY before report generation):

- ```

- Run in terminal: <python-executable> devtools/consistency_checker.py task_solve/YYYY-MM-DD_slug/

- ```

- The consistency checker:

- - Extracts numerical values from all notebooks and results.json

- - Detects inconsistencies: numerical mismatches, scope mismatches (e.g., volumetric vs mass-based), contradictory claims

- - Produces `consistency_report.json` in the task folder

- - **Fix any CRITICAL issues before generating the report**

- - Common issue: external study data (e.g., Gudrun paper) measuring different quantities than notebook calculations — these need clarification in the report, not "fixing"

- 18. **Run the report generator** to produce the engineering report (Word + HTML):

- ```

- Run in terminal: <python-executable> step3_report/generate_report.py

- ```

- This is the **default and preferred output** — an engineering technical report.

- Only generate a scientific paper if the user explicitly requests it

- (`--paper` or `--paper-only`). The default workflow produces the Word and

- HTML report only.

- **File names are the report title.** A study titled "Hydrate margin for the

- export line" ships `step3_report/Hydrate_margin_for_the_export_line.docx`

- and `.html`, so the deliverable is identifiable outside its task folder. Set

- `study.title` in `study_config.yaml` (or pass `--title`) before generating.

- Files written under an earlier title are removed on regeneration — never

- leave a superseded report beside the current one.

- **Corporate Word template:** the Word report is automatically built from the

- template the user configured with `neqsim --set-report-template "PATH"`

- (or `NEQSIM_REPORT_TEMPLATE`), so it inherits their organisation's styles,

- fonts, headers, and footers. Do not pass `--no-template` or override the

- styling unless the user asks. If the generator exits with a missing-template

- error, report it — do not fall back to unbranded output silently. Tasks

- created before this support exists carry an older `generate_report.py`; copy

- `devtools/task_template/step3_report/generate_report.py` over the task copy

- to enable it.

- **Styled section formatting** (built into the template):

- - Risk Assessment: summary card with color-coded badges (High=red,

- Medium=orange, Low=green), professional table with risk levels,

- likelihood/consequence columns, and mitigation

- - Uncertainty Analysis: blue summary card, input parameters table,

- P10/P50/P90 output distribution table, tornado sensitivity table

- - Benchmark Validation: table with PASS/FAIL color coding and detail columns

- - All formatting renders automatically when corresponding keys exist in

- `results.json` — no custom rendering code needed per task

- 19. **Update the task README** (`README.md` in the task folder):

- - Fill in the Problem Statement

- - Check off completed steps

- - Write the Key Results section

- 19a. **The work record is generated with the report** (`step3_report/WORK_RECORD.md`)

- — step 18 writes it automatically. Rebuild it alone with:

- ```

- Run in terminal: neqsim work-record task_solve/YYYY-MM-DD_slug

- ```

- The report answers *what the conclusion is*; the work record answers *how it

- was produced* — every script and notebook with its purpose and outputs, every

- source system and collected document, the cached data files, the figures, an

- annotated folder map, and the commands to reproduce the study. It is built

- from the folder, so it cannot drift from the files it describes.

- **Then fill the three NARRATIVE blocks by hand** (`background`, `method`,

- `limitations`). They are the part a reader cannot reconstruct from a

- directory listing: why this approach over the alternatives, what each step

- established, which numbers are screening-level, and what evidence would

- change the answer. Text inside the blocks is preserved when the file is

- regenerated, so regenerate freely after adding scripts or data.

- Verify with `neqsim work-record <task> --check`, which fails while a

- narrative block still holds template text or a declared artifact is missing.

- **Two config keys make the auto-built half good** — set them in

- `study_config.yaml` as the analysis takes shape: `analysis.scripts`

- (file / purpose / produces) turns section 7 into the real reproduction

- sequence, and `inputs.data_sources` (system / scope / access / evidence)

- fills the source-system table with captured-vs-missing status. A one-line

- docstring on every analysis script becomes its purpose in section 3.

- Set `report.work_record: required` to make the report gate enforce it, or

- `skip` to opt out.

- 19b. **Pre-send review (MANDATORY — `consistency_checker.py` does not catch these).**

- A report assembled incrementally accumulates contradictions that are

- individually well-formed. Run the pre-send pass from

- `neqsim-professional-reporting`: sweep every quantity that appears more than

- once and reconcile it (or label its basis explicitly); count the items behind

- every "Three further findings"-style lead-in; list `^## ` headings and check

- for numbering gaps; re-read every "Open" / "not yet retrieved" status against

- what the study actually ended up doing; and confirm any quantity quoted on an

- alternative basis is also in `results.json`.

- ### Phase 4: Knowledge Capture & Contribution

- 20. **Identify reusable outputs**:

- - If the notebook is generally useful → mention it could go to `examples/notebooks/`

- - If a NeqSim API gap was found → document it for future development

- - If a new pattern was discovered → note it for `CODE_PATTERNS.md`

- 21. **Fix and improve documentation** encountered during the task:

- - If you found **errors** in existing docs (wrong API signatures, outdated

- patterns, incorrect examples), fix them and include the fixes in the PR.

- - If you discovered **missing documentation** (undocumented classes, missing

- cookbook recipes, gaps in guides), add it and include in the PR.

- - If you identified **improvements** (clearer explanations, better examples,

- additional warnings), make the changes and include in the PR.

- - Update index files (`REFERENCE_MANUAL_INDEX.md`, section `index.md`)

- when adding new doc pages.

- - Documentation fixes go in the **same PR** as the task outputs.

- 22. **Draft a task log entry** (but don't write to the file directly):

- - Treat `TASK_LOG.md` as public/reusable memory. Redact company/operator names,

- field/facility/asset names, equipment tag numbers, internal document names,

- private system names, access diagnostics, and task folder slugs containing

- those details. Use generic descriptors and `private task folder (redacted)`

- for confidential task outputs.

- ```

- ### YYYY-MM-DD — Task Title

- **Type:** X (TypeName)

- **Keywords:** comma, separated, search, terms

- **Solution:** task_solve/YYYY-MM-DD_task_slug/step2_analysis/notebook.ipynb

- **Notes:** Key findings, API gaps discovered, recommendations

- ```

- Show this to the user for them to add to `docs/development/TASK_LOG.md`.

- 23. **Create a Pull Request** (if the user asks, or if reusable outputs were produced):

- When the task produces reusable code (tests, notebooks, docs, API extensions),

- offer to create a PR. If the user confirms, execute these steps:

- ```bash

- # Create a feature branch from the current branch

- git checkout -b task/TASK_SLUG

- # Stage reusable outputs (only files that should be contributed)

- git add src/test/java/neqsim/... # tests

- git add examples/notebooks/... # notebooks

- git add docs/... # documentation

- git add docs/development/TASK_LOG.md # task log entry

- # Commit with descriptive message

- git commit -m "Add [description] from task: [TITLE]"

- # Push and create PR

- git push -u origin task/TASK_SLUG

- gh pr create --title "Add [description]" --body "From task-solving workflow: [TITLE]

- ## What was added

- - [list of files/features contributed]

- ## Task context

- - Task type: [X] ([TypeName])

- - Standards applied: [list]

- - Key finding: [brief summary]"

- ```

- **Important PR rules:**

- - **Never commit `task_solve/` contents** — it's gitignored for a reason.

- Only commit files copied to their proper locations (src/, examples/, docs/).

- - **Copy first, then stage** — copy notebooks to `examples/notebooks/`,

- copy tests to `src/test/java/`, etc. before `git add`.

- - **Ask before pushing** — creating a PR is visible to others. Confirm with

- the user before `git push` and `gh pr create`.

- - **One PR per task** — keep the scope focused.

- ---

- ## 3 ── TASK TYPE SPECIFIC GUIDANCE

- ### Type A — Property Tasks

- - Use `ThermodynamicOperations` for flash calculations

- - Always call `fluid.initProperties()` after flash before reading properties — `init(3)` alone does NOT initialize transport properties (viscosity, thermal conductivity will return zero)

- - Compare against NIST, DIPPR, or experimental data where possible

- - Plot property vs. T or P curves for validation

- ### Type B — Process Tasks

- - Build with `ProcessSystem` — add all equipment in topological order

- - Single `process.run()` after building the full flowsheet

- - Check mass balance: compare inlet and outlet flow rates

- - Use `@solve-process` agent patterns for notebook structure

- ### Type C — PVT Tasks

- - Use classes from `neqsim.pvtsimulation.simulation`

- - Common: `ConstantMassExpansion`, `ConstantVolumeDepletion`, `SaturationPressure`

- - Plot PVT curves and compare against lab data if available

- ### Type D — Standards Tasks

- - Use `neqsim.standards.gasquality` classes

- - Verify against published standard examples/test cases

- - Report all required standard outputs (GCV, NCV, Wobbe, density, etc.)

- ### Type E — Feature Tasks

- - Search existing source code first to avoid duplication

- - **Implement the Java class** with complete JavaDoc (Java 8 compatible)

- - Write JUnit 5 tests that validate against known physical results

- - Build with `mvnw.cmd package -DskipTests` to verify compilation

- - Write a notebook showing the new feature in action

- - Include a NIP documenting the design rationale

- ### Type F — Design Tasks

- - Use `MechanicalDesign` classes where they exist

- - Reference the applicable standard (ASME, DNV, API, etc.)

- - Include safety factors and corrosion allowances

- - Report in engineering units with clear margin-of-safety

- ### Type G — Workflow Tasks (Multi-Discipline)

- - These are large, multi-step engineering studies (field development, design basis,

- technology screening, concept selection)

- - **Step 1 (Scope) is critical** — define ALL standards, methods, and deliverables

- upfront in `task_spec.md` before any analysis

- - **Create multiple notebooks** in `step2_analysis/`, numbered sequentially:

- - `01_reservoir_fluid.ipynb` — fluid characterization

- - `02_process_train.ipynb` — topside process design

- - `03_pipeline_sizing.ipynb` — pipeline hydraulics

- - `04_flow_assurance.ipynb` — hydrate, wax, corrosion assessment

- - `05_mechanical_design.ipynb` — wall thickness, sizing

- - (add/remove as needed for the specific workflow)

- - Each notebook should be self-contained but reference shared fluid definitions

- - **HTML report is especially valuable** for Type G — it provides a navigable,

- multi-section document linking all sub-analyses

- - Consider creating a summary notebook that imports results from all sub-analyses

- ### Economics & NPV Calculations (applies to Type G and any task with economics)

- When a task involves economic evaluation (NPV, IRR, cash flow, breakeven):

- 1. **Tax model must match the jurisdiction's actual law.** Do not guess tax rules:

- - **Norwegian petroleum tax**: Corporate tax (22%) and special petroleum tax (56%)

- are calculated on **independent** taxable incomes (NOT cascaded). Uplift is 5.5%/yr

- for 4 years on qualifying CAPEX. Depreciation is straight-line over 6 years.

- Loss carry-forward is per tax pool (no interest on carried losses).

- - For other jurisdictions, research the actual regime before implementing.

- - Common error: cascading taxes (applying petroleum tax to income after corporate tax)

- gives wrong effective rate. The correct marginal rate is 22% + 56% = 78%.

- 2. **Use component-level CAPEX, not lump-sum estimates.** For subsea field development:

- - Use `SURFCostEstimator` for field-level SURF CAPEX breakdown (Subsea, Umbilicals, Risers, Flowlines)

- - Use `SubseaCostEstimator` for individual component costs (trees, manifolds, PLETs, jumpers)

- - Use `PipeMechanicalDesignCalculator` for pipeline wall thickness and material costs

- - Report CAPEX breakdown by category with pie charts

- 3. **Production profile must be realistic.** Use plateau + decline model with:

- - Ramp-up period (1-2 years typical)

- - Plateau at nameplate capacity

- - Exponential or hyperbolic decline when reserves deplete

- - Recovery factor typically 40-60% for gas, 20-40% for oil (NCS)

- 4. **Cash flow time indexing:** Year 0 = investment year (CAPEX only, no revenue).

- Revenue starts Year 1. Do not double-count CAPEX in both the investment schedule

- and the operating cost line.

- 5. **Sensitivity analysis is mandatory** for economic evaluations:

- - Oil/gas price: ±20-30%

- - CAPEX: ±20%

- - Production rate: ±15%

- - Discount rate: 0%, 5%, 8%, 10%

- - Plot tornado chart or spider plot showing NPV sensitivity to each parameter

- 6. **Include breakeven analysis:** Calculate breakeven price (oil/gas price at NPV=0)

- using bisection or scipy optimization. Report alongside NPV and IRR.

- ---

- ## 4 ── NOTEBOOK SETUP PATTERN

- See the `neqsim-notebook-patterns` skill for the complete devtools setup cell,

- `ns.*`/`ns.JClass(...)` import patterns, and notebook structure template.

- ### Loading Custom Java Classes in Notebooks

- When using newly created NeqSim Java classes from Python notebooks, do not rely

- on the installed Python `neqsim` package. Use the task setup cell to load local

- workspace classes, then resolve additional classes through `ns.JClass(...)`:

- ```python

- MyClass = ns.JClass("neqsim.process.mechanicaldesign.subsea.SURFCostEstimator")

- ```

- **Common classpath issues:**

- - Old JAR versions in Python site-packages can shadow workspace changes when using `jneqsim`

- - Task notebooks should call `neqsim_init(project_root=PROJECT_ROOT, recompile=False, ...)`

- - Use `ns.JClass()` for explicit class loading when `neqsim_classes(ns)` does not preload the class

- ---

- ## 5 ── DELEGATE TO SPECIALIST AGENTS

- For complex sub-tasks within your workflow, you may delegate to specialist agents:

- | Sub-task | Agent | When to use |

- |----------|-------|-------------|

- | Fluid setup | `@thermo-fluid` | Complex oil characterization, CPA systems |

- | Process simulation | `@solve-process` | Large flowsheets with recycles/adjusters |

- | PVT experiments | `@pvt-simulation` | Multi-point PVT studies |

- | Gas quality | `@gas-quality` | ISO 6976, AGA calculations |

- | Mechanical design | `@mechanical-design` | Wall thickness, vessel sizing |

- | Flow assurance | `@flow-assurance` | Hydrate curves, wax, corrosion |

- | Safety | `@safety-depressuring` | Blowdown, PSV sizing |

- | Field development | `@field-development` | Concept selection, subsea tieback, NPV/IRR, production forecasting |

- | Document / image reading | `@read technical documents` | Extract data from PDFs, vendor datasheets, P&IDs, mechanical drawings, performance maps, API datasheets |

- You don't have to delegate — you can handle everything yourself. But for deep

- specialist work, the dedicated agents have more detailed instructions.

- For **Type G (Workflow)** tasks, you will likely need multiple specialist agents

- in sequence. Coordinate them through the task_spec.md requirements.

- ---

- ## 6 ── NEQSIM IMPROVEMENT PROPOSALS (when material gaps are found)

- When capability assessment identifies material NeqSim gaps (❌ Missing or ⚠️ Partial),

- write concrete improvement proposals. Use proportionality:

- - Required for Development mode and high-impact Design/Workflow tasks

- - Recommended for recurring or high-value gaps

- - Optional for one-off low-impact gaps (document limitation and workaround in notes)

- ### 6.1 — When to Write Proposals

- Write a NeqSim Improvement Proposal (NIP) when the gap:

- - Blocked or limited the analysis quality

- - Required a Python workaround that should be in Java

- - Would make future similar tasks significantly easier

- - Represents a commonly needed engineering capability

- Proposals go into `step1_scope_and_research/neqsim_improvements.md`.

- ### 6.2 — Proposal Structure (for each gap)

- ```markdown

- ### NIP-XX: [Short Title]

- **Gap:** [What NeqSim cannot do today]

- **Impact on task:** [How this limited the current analysis]

- **Priority:** Critical / High / Medium / Low

- #### Proposed Implementation

- **Package:** `neqsim.process.equipment.[package]` (or `thermo`, `pvtsimulation`, etc.)

- **Class name:** `ProposedClassName`

- **Extends:** `[BaseClass]`

- **Key methods:**

- |--------|-----------|---------|-------------|

- **Constructor:**

- ```java

- public ProposedClassName(String name, StreamInterface inletStream) {

- super(name, inletStream);

- }

- ```

- **Governing equations:**

- $$ [key equation in LaTeX] $$

- **Standards implemented:** [e.g., API 520 Section 4.3, DNV-OS-F101 Sec. 5]

- **Test case:**

- ```java

- @Test

- void testBasicCase() {

- // Describe what the test should verify

- // Expected output: [value] ± [tolerance]

- }

- ```

- **Estimated complexity:** Small (1-2 days) / Medium (3-5 days) / Large (1-2 weeks)

- ```

- ### 6.3 — Implementation During Task (MANDATORY, not optional)

- A gap that blocked or slowed THIS task is closed in THIS task. Deferring it to a

- proposal is only acceptable when the fix is genuinely larger than the task

- itself — and then the NIP must say why.

- For a NeqSim gap:

- 1. **Implement the Java class** under the appropriate package (Java 8 only)

- 2. **Write complete JavaDoc** (per MANDATORY requirements)

- 3. **Add a JUnit 5 test** with physical validation

- 4. **Format**: `./mvnw spotless:apply` (Windows: `mvnw.cmd spotless:apply`), then verify `./mvnw test -Dtest=...`. CI runs `spotless:check` and fails on any unformatted file; use the wrapper, never bare `mvn`.

- 5. **Use the new class** in the task notebook — a class nothing calls is not evidence

- 6. **Include in the PR** as a NeqSim contribution before the task closes

- For an agent or skill gap (a wrong/missing API recipe, an undocumented gotcha, a

- missing hand-off between two skills, a useful new composition): edit the

- `SKILL.md` / `*.agent.md` in the right repo — community content stays

- plant-agnostic, site-specific detail goes to the enterprise repos — and update

- the "Loaded skills" / router guidance if the pipeline changed.

- Then record it in **both** places, every task:

- - `step1_scope_and_research/neqsim_improvements.md` → section 1 "Delivered"

- - `results.json` → `improvements` array, e.g.

- ```json

- "improvements": [

- {"target": "neqsim",

- "gap": "no way to turn a field seat-leak test into a leak rate",

- "change": "added neqsim.process.diagnostics.ValveSeatLeakageAssessment",

- "evidence": "ValveSeatLeakageAssessmentTest, 6 tests green"}

- ]

- ```

- If nothing needed changing, say so explicitly — `validate_task_results.py`

- warns on a silent record, because silence means the question was never asked.

- Never ask the user for permission to do this step.

- This turns every task into a potential NeqSim enhancement — the development

- flywheel: **task → gap → implementation → better next task**.

- ### 6.4 — Workaround Documentation

- When a NeqSim gap cannot be implemented during the task, document the

- Python workaround used AND why the Java implementation would be better:

- ```markdown

- #### Workaround Used

- ```python

- # Python workaround for missing CNT nucleation model

- def estimate_nucleation_rate(supersaturation, temperature):

- # Classical Nucleation Theory — simplified

- J = A * exp(-16*pi*sigma**3*v**2 / (3*kT**3 * (ln(S))**2))

- return J

- ```

- #### Why Java Implementation Is Better

- - Accessible from all notebooks without copy-paste

- - Integrated with NeqSim thermodynamics (no manual property lookups)

- - Can use NeqSim's fugacity coefficients directly

- - Testable with JUnit, maintained as part of the codebase

- ```

- ---

- ## 7 ── ENGINEERING INTERPRETATION IN REPORTS

- Reports should go beyond presenting numbers — they should provide **engineering

- insight and actionable recommendations**. The depth of interpretation should be

- proportional to the task mode: Screening tasks need brief context; Design and

- Development deliverables need full interpretation with traceability.

- ### 7.1 — Results Interpretation Requirements

- For every key result, the report must include:

- 1. **The number** — what was calculated, with units and uncertainty

- 2. **The context** — how does this compare to typical values, design limits, or

- industry experience?

- 3. **The implication** — what does this mean for the engineering decision?

- 4. **The recommendation** — what should the engineer do based on this result?

- **Example (bad — numbers only):**

- > The JT outlet temperature is -20.8°C. The corrosion rate is 0.037 mm/yr.

- **Example (good — with engineering interpretation):**

- > The JT outlet temperature of -20.8°C is well below the sulfur deposition

- > onset temperature (0°C), confirming that S8 desublimation will occur across

- > the letdown valve under all operating scenarios. This temperature is also

- > below the MDMT (-29°C for carbon steel per ASME B31.3 Table A-1), so material

- > selection must account for low-temperature service.

- >

- > The combined corrosion rate of 0.037 mm/yr (CO2 + H2S + S8 mechanisms) is

- > classified as "Low" per NORSOK M-001 Table A.1 (<0.1 mm/yr). However, the

- > presence of non-protective mackinawite FeS at this temperature means the

- > rate may accelerate under high-velocity or two-phase conditions. **Recommendation:**

- > specify CRA material (22Cr duplex) for the first 3 pipe diameters downstream

- > of the valve, and carbon steel with 3 mm corrosion allowance beyond.

- ### 7.2 — Conclusions Should Be Actionable

- For Design/Development deliverables, the conclusions section should contain:

- 1. **Summary of key findings** — 3-5 bullet points with numbers

- 2. **Engineering recommendations** — specific, actionable advice

- 3. **Design implications** — what parameters should be used in detailed design

- 4. **Remaining uncertainties** — what the analysis could not resolve

- 5. **Suggested follow-up** — next steps, additional studies needed

- ### 7.3 — Figure-by-Figure Discussion (Traceability Chain)

- For Design/Development deliverables, decision-critical figures should have a

- corresponding discussion that creates a traceable chain from calculation

- to recommendation. For Screening tasks, brief inline comments suffice:

- ```

- Calculation → Figure → Discussion → Conclusion → Recommendation

- ↓ ↓ ↓ ↓ ↓

- results.json figures/ figure_discussion conclusions design_recommendations

- ```

- #### In the Notebook

- After decision-critical figure cells, add a **markdown discussion cell** with:

- 1. **Observation** — what the figure shows (with numbers)

- 2. **Physical Mechanism** — why it happens

- 3. **Engineering Implication** — what it means for design/operation

- 4. **Recommendation** — specific action to take

- 5. **Traceability** — which results.json entries and insight questions this addresses

- (See Section 2 step 9 for the full template and example.)

- #### In results.json

- Populate the `figure_discussion` array — schema shown in the results.json

- template (Section 2, step 15, Tier 2).

- #### In the Report

- The report generator auto-renders `figure_discussion` entries as a structured

- "Discussion" section between Results and Validation.

- #### Quality Check (Design / Development mode)

- - Decision-critical figures should have matching entries in `figure_discussion`

- - `design_recommendations` entries should trace back to figure discussions

- ### 7.4 — Report Section Enhancement

- Add these sections to the report (in `generate_report.py` MANUAL_SECTIONS):

- - **Engineering Context**: Why this analysis matters, what problem it solves,

- consequences of the wrong answer (1-2 paragraphs)

- - **Solution Approach Justification**: Why the chosen method/EOS/model is

- appropriate — with reference to alternatives considered in Phase 1.5

- - **Results Discussion**: Auto-populated from `figure_discussion` entries —

- shows observation, mechanism, implication, and recommendation for each figure

- - **Design Recommendations**: Specific actionable recommendations with

- reference values, material selections, operating limits

- - **NeqSim Capabilities & Gaps**: Summary of what NeqSim enabled, what

- workarounds were needed, and proposed improvements (from NIPs)

- ---

- ## 8 ── CRITICAL RULES

- 0. **NeqSim API first.** Every thermodynamic property, flash calculation, process simulation, and equipment sizing must use NeqSim Java classes (via `neqsim_dev_setup.py`/`ns.*` in task notebooks, runner scripts, or JUnit tests). Never substitute a simplified Python correlation, regression, or hand-formula when a NeqSim class exists for the same calculation. Search the Java source first. If no class exists, that is a gap — see Rule 21.

- 1. **Create the `task_solve/` folder FIRST for new tasks — this is non-negotiable.** Always run `neqsim new-task "TITLE" --type X --author "Agent" --prompt "<verbatim user request>"` before writing any files. For resume requests, read the existing task's `progress.json` first instead of creating a duplicate. ALL deliverables (task_spec.md, executable calculations, notes.md, results.json, figures/) MUST be placed inside the generated `task_solve/YYYY-MM-DD_task_slug/` folder. Never write analysis files to the workspace root, `examples/`, or any other location. If the folder was not created for a new task, STOP and create it now.

- 2. **Scale to the task.** Quick tasks get minimal ceremony. Comprehensive tasks get full documentation. Don't over-engineer a simple property lookup or under-deliver a field development study.

- 3. **Fill in the task spec.** Standards, methods, and deliverables must be defined in `task_spec.md` before analysis. For Quick scale, only essential fields.

- 4. **Deep analysis before code (when applicable).** For high-consequence Design/Development tasks, write `analysis.md` before coding. For Screening tasks, a condensed analysis in notes.md is sufficient.

- 5. **Run every executable artifact.** Do not deliver unexecuted notebooks or untested runner scripts. Fix errors immediately.

- 6. **Verify physics.** Mass balance, energy balance, reasonable ranges. Flag anything suspicious.

- 7. **Check acceptance criteria.** Results must meet the criteria defined in `task_spec.md`.

- 8. **Document assumptions.** Every engineering default you choose must be stated explicitly.

- 9. **Save figures.** All plots go to `figures/` as PNG for reports. **NEVER use `os.getcwd()` or `pathlib.Path.cwd()` to resolve figure paths** — VS Code notebooks set cwd to the workspace root, not the notebook directory. Always use the absolute path pattern from the notebook template.

- 10. **Write all required notes.** Research notes, analysis documents, and validation notes required by the selected scale must be populated — not left as templates.

- 11. **API verification.** If unsure about a NeqSim method, search the Java source to confirm it exists. Do NOT guess method names.

- 12. **Doc code verification.** When producing code that will appear in documentation or examples, write a JUnit test (append to `DocExamplesCompilationTest.java`) that exercises every API call shown, and run it to confirm it passes. See `neqsim-api-patterns` skill.

- 13. **Verify every formula against domain standards.** Do not assume a formula from memory is correct — look up the governing equation in the applicable standard or textbook. Common errors: cascaded vs independent tax bases, missing terms (uplift, depreciation), wrong operator precedence in compound expressions. After implementing, verify with a manual hand-calculation for at least one data point.

- 14. **Use NeqSim Java classes for cost/design — never flat estimates.** When CAPEX or mechanical design values are needed, search for existing classes in `neqsim.process.mechanicaldesign` (e.g., `SubseaCostEstimator`, `SURFCostEstimator`, `PipeMechanicalDesignCalculator`). Use component-level estimates, not a single lump-sum number. If a needed class doesn't exist, implement it with proper JavaDoc and unit tests before using it in notebooks or runner scripts.

- 15. **Cross-check results against industry benchmarks.** Every key output should be sanity-checked: typical SURF costs are 40-60% of total field development CAPEX; Norwegian petroleum tax is ~78% marginal; subsea tree costs are $5-15M; pipeline costs for NCS are $1,500-5,000/m. If results diverge significantly from benchmarks, investigate before accepting.

- 16. **Currency and unit conversions must be explicit and parameterized.** Never hardcode exchange rates inside formulas. Define them as named variables (e.g., `USD_TO_NOK = 10.5`) at the top of the notebook and reference throughout. State the assumed rate in `results.json` and report text.

- 17. **Notebooks used for teaching must have theory cells.** When the task has educational value, include: (a) governing equations with LaTeX rendering, (b) explanation of why each parameter matters, (c) 2-3 exercises for the reader, (d) academic references. This applies especially to Type G workflow tasks.

- 18. **After first draft, always self-review calculations.** Before delivering, re-read every formula cell and check: correct signs (revenue positive, cost negative in cash flow), no double-counting (CAPEX in both investment and operating cost), correct time indexing (year-0 vs year-1), tax model matches the jurisdiction's actual law.

- 19. **Units matter.** Kelvin for constructors, unit strings for setters. Always state units in output.

- 20. **No `pip install neqsim` for local task notebooks or runner scripts.** Use `neqsim_dev_setup.py` and `ns.*`/`ns.JClass(...)` so runner jobs use workspace Java classes.

- 21. **Extend NeqSim when gaps are found.** When a task needs a capability NeqSim lacks, don't just work around it — write a NIP in `neqsim_improvements.md`, and when feasible within the session, implement the new Java class with complete JavaDoc and JUnit tests. This is a primary output of the agent, not a side activity. For minor one-off gaps, document the limitation and Python workaround used.

- 22. **Engineering interpretation matters.** Reports should explain what results mean, not just what the numbers are. In Design/Development mode, every key result needs context, implication, and recommendation. In Screening mode, brief interpretation of key findings is sufficient.

- 23. **Answer the insight questions.** When Phase 1.5 was performed, engineering insight questions should be explicitly answered in the report conclusions.

- 24. **Discuss key figures proportionately.** Provide discussion cells for all decision-critical figures, and for all figures in Design/Development mode deliverables. Populate `figure_discussion` accordingly.

- 25. **Traceability supports credibility.** In Design/Development mode, design recommendations should trace back through: recommendation ← figure discussion ← figure ← calculation ← results.json. For Screening, direct citation of key results is sufficient.

- 26. **PR safety.** Never commit `task_solve/` contents. Copy reusable files to proper locations first. Always ask before `git push`.

- 27. **Management of Change.** When the user requests a parameter change mid-task

- (dimensions, flow rate, composition, EOS), document the change in

- `step2_analysis/notes.md` under a \"Changes\" heading (what changed, why,

- impact on prior results). Then re-run all affected notebooks in order

- and update `results.json`, figures, and report text. Increment the

- revision in the Design Basis Header if one exists.

- ---

- ## 9 ── DELIVERING THE TASK

- After completing all phases, present an executive summary to the user.

- The delivery message should read like a **consultant's briefing note** —

- the reader should understand the problem, the approach, the answer, and what

- to do next, without opening any files.

- **Required elements (all modes):**

- 1. **Task folder**: `task_solve/YYYY-MM-DD_task_slug/`

- 2. **Task scale**: Quick / Standard / Comprehensive (with rationale)

- 3. **Engineering answer**: 3-5 sentences answering the core engineering question

- with specific numbers, context, and recommendations

- 4. **Key results table**: Critical outputs with units

- 5. **Deliverables produced**: List of populated files (task_spec, notebooks,

- results.json, reports)

- 6. **Standards applied**: Governing codes and methods used

- **Additional elements (Design / Development mode):**

- 7. **Design recommendations**: Specific actionable engineering advice

- 8. **Remaining uncertainties**: What the analysis could not resolve

- 9. **NeqSim gaps**: Summary of NIPs or workarounds used

- 10. **Suggested next steps**: promote notebook, implement NIPs, log the task

- 11. **Task log entry**: Draft entry for `TASK_LOG.md`

- 12. **PR opportunity**: Offer to contribute reusable outputs back to the repo

- ---

- ## 10 ── LESSONS LEARNED (from solved tasks)

- These are practical pitfalls discovered while solving real engineering tasks.

- Review before starting any Standard or Comprehensive task.

- ### 10.1 Report Generator Pitfalls

- L1. **The `generate_report.py` template now includes built-in styled formatting**

- for Benchmark Validation, Uncertainty Analysis, and Risk Evaluation sections.

- These render automatically when the corresponding keys exist in `results.json`

- (`benchmark_validation`, `uncertainty`, `risk_evaluation`). You do NOT need to

- add custom rendering logic per task — just populate the results.json correctly.

- The formatters produce color-coded risk badges, P10/P50/P90 tables, tornado

- tables, and PASS/FAIL benchmark tables in all four outputs (the Word and HTML

- report — and the Word/HTML paper when `--paper` is used).

- L2. **Four layers must stay synchronised for every report section:**

- - `build_sections()` — defines the section with heading, content, and flags

- - `build_word_report()` — renders Word-specific content (tables, figures)

- - `build_html_report()` — renders HTML-specific content (styled tables, base64 images)

- - `build_paper_docx()` / `build_paper_html()` — paper equivalents (only used with `--paper`)

- The template has these pre-wired for standard section types. Only add

- custom handling if you need task-specific rendering beyond the built-in formatters.

- If any one layer is missing, that section will render as plain text or be blank.

- **Default output is report only** — do not generate papers unless the user asks.

- L3. **Hardcoded numbers in MANUAL_SECTIONS go stale.** When equipment dimensions,

- flow rates, or other design parameters change during iterative design, the

- executive summary and conclusions text must be updated manually. The report

- generator does not auto-update these strings from results.json.

- **Best practice:** Write conclusions in `results.json["conclusions"]` and let

- the generator read from there. Only use MANUAL_SECTIONS as a fallback.

+ description: "The full NeqSim engineering task workflow that @solve-task orchestrates. USE WHEN: executing any Standard or Comprehensive task end to end - setup and scale classification, scope and research, deep analysis, notebooks with benchmark validation and uncertainty/risk, quality gates, report and work record, knowledge capture, task-type guidance, delegation, NeqSim Improvement Proposals and lessons learned. Load one phase section at a time."

+ last_verified: "2026-09-18"

+ ---

+ # NeqSim Task Workflow

+ This is the detailed procedure behind `@solve-task`. The agent file holds the

+ mandatory first action, the purpose, and the operating principles (section 0);

+ sections 1-10 below are loaded on demand for Standard and Comprehensive work.

+ Section numbers are kept so cross-references from the agent and from

+ `docs/development/TASK_SOLVING_GUIDE.md` stay valid.

+ ---

+ ## 0.5 ── ALWAYS-ON OBLIGATIONS (moved from the agent)

+ ### Keep `user_input.md` up to date through the whole conversation

+ `user_input.md` is the **reproducibility log** — anyone re-running this task

+ should be able to recover the exact starting input from it.

+ **Whenever the user provides new information during the task, append it to

+ `user_input.md` immediately and verbatim:**

+ - Answers to your clarifying questions → append to **section 2 (Q&A)**

+ - Mid-task corrections, scope changes, or new constraints → append to **section 3 (Follow-up)**

+ - Any value you assume because the user did not specify it → record it in **section 4 (Inferred Assumptions)** with justification

+ Do NOT paraphrase, summarise, or "clean up" the user's wording. Paste it as

+ given. Never delete previous entries — only append.

+ ### All downloaded documents go INSIDE the task folder

+ **All documents retrieved during a task — STID drawings, PI historian exports,

+ vendor datasheets, P&IDs, literature PDFs, downloaded standards — MUST be saved

+ to `step1_scope_and_research/references/` within the task folder.**

+ NEVER download or save task-related files to workspace-level directories like

+ `output/`, `figures/`, or any path outside `task_solve/YYYY-MM-DD_slug/`.

+ **For STID/document retrieval scripts:** Always pass the task's `references/`

+ path as the output directory:

+ ```python

+ # CORRECT — saves inside the task folder:

+ out_dir = os.path.join(TASK_DIR, "step1_scope_and_research", "references")

+ # WRONG — saves outside the task folder:

+ out_dir = os.path.join(os.path.dirname(__file__), "..", "figures", "stid_docs") # NEVER DO THIS

+ ```

+ **For PDF-to-PNG conversion:** Output converted images to the task's `figures/`:

+ ```bash

+ <python-executable> devtools/pdf_to_figures.py task_solve/YYYY-MM-DD_slug/step1_scope_and_research/references/ \

+ --outdir task_solve/YYYY-MM-DD_slug/figures/

+ ```

+ This ensures every task is self-contained and portable — zip the task folder

+ and everything needed is inside it.

+ ### Extract every downloaded or supplied document before solving

+ The `references/` folder is not passive storage. Before any document-derived

+ value, topology, limit, requirement, or recommendation enters Step 2, route

+ **every file** through `technical-document-intelligence-agent` using

+ `neqsim-document-intelligence-extraction`, then through the applicable

+ document-type/domain reader.

+ For each file:

+ 1. Preserve the original and record its hash, actual format, revision/date, and

+ extraction-tool versions.

+ 2. Run native text and structured-table extraction first. For spreadsheets,

+ retain sheets, formulas, merged ranges, hidden rows/columns, headers, and units.

+ 3. Render and assess every page that contains visual or spatial information.

+ Use OCR for scans and multimodal vision for drawings, P&IDs, charts, maps,

+ photographs, annotations, symbols, topology, and table layout. OCR alone is

+ not sufficient for visual engineering content.

+ 4. Extract comprehensively: body text, tables, title blocks, notes, legends,

+ appendices, footnotes, figures, plots, revision clouds, and unexpected

+ engineering constraints. Do not stop after finding the fields anticipated by

+ the initial task description.

+ 5. Package facts with original text/value/unit, page/cell/bounding-box locator,

+ method, confidence, normalized value/unit, and review status. Reconcile

+ native/OCR/vision outputs without silently resolving conflicts.

+ 6. Record unsupported content, missing expected fields, conflicts, ambiguous

+ facts, and safety-critical or confidence-below-0.85 facts as explicit gaps or

+ `needs_review` items.

+ Write `step1_scope_and_research/document_evidence_manifest.json` with one entry

+ for every file under `references/`, its extraction operations and status, links

+ to its evidence package(s), and counts of facts/conflicts/gaps/review items.

+ Summarize the evidence in `notes.md` and preserve fact identifiers in downstream

+ inputs/results. The number of manifest source entries MUST equal the recursive

+ file inventory count, excluding generated evidence packages and the manifest

+ itself. Do not begin Step 2 while any source is `not_started` or silently

+ unprocessed; record a blocked/manual-review status when extraction cannot run.

+ ---

+ ## 0.6 ── OPERATING ENVIRONMENTS (what each step needs)

+ The workflow below was written in the NeqSim source checkout. It also runs from

+ the pip-installed toolkit (`neqsim-dev-setup`, installed automatically by the

+ core agent plugin's SessionStart hook) and, degraded, from chat with only the

+ MCP server. Detect the environment first (agent Step 0) and apply this table.

+ |---|---|---|---|

+ | `neqsim new-task`, `user_input.md`, `study_config.yaml` | yes | yes | create folder by hand from the template layout |

+ | `recompile=True`, `mvnw`, Java classes + JUnit (NIP implementation) | yes | **no** - write the NIP, do not attempt | no |

+ | NeqSim Runner (`AgentBridge`, `neqsim_runner`) | yes | yes | no - run scripts directly or use MCP |

+ | `validate_task_results`, `consistency_checker`, `TaskResultValidator` | yes | yes (Python validators; the Java `TaskResultValidator` needs the JAR, available) | Python validators not installed - state results.json was not gate-checked |

+ | `skill_search` / `agent_search`, `capability_assessment.md` | yes | yes | by reasoning over the skill catalogue only |

+ When a row says **no**, the deliverable matrix in the agent's section 0 still

+ applies: do the step by the strongest available means and record what was

+ skipped in `results.json` `data_gaps` (or in the chat answer) so the reader knows

+ the evidence level.

+ ---

+ ## 1 ── OVERVIEW

+ You follow the **3-step AI-Supported Task Solving While Developing** workflow.

+ "While Developing" is key — solving the task and improving NeqSim happen in

+ the same session. The workflow is aligned with the IPA Front-End Loading (FEL)

+ framework and Stage-Gate methodology:

+ ```

+ STEP 1 → Scope & Research (FEL-1: Identify) Define standards, methods, deliverables + gather background

+ STEP 2 → Analysis & Eval (FEL-2: Evaluate) Build simulation, run, validate, iterate until accepted

+ STEP 3 → Report (FEL-3: Define) Generate Word + HTML deliverables

+ ```

+ Each step transition is a **gate** (per Stage-Gate, Cooper 1990) — the quality

+ gates in Section 2 define the go/no-go criteria before advancing.

+ The framework also draws on:

+ - **AACE 18R-97** — Cost estimate classification (Class 5→1 maturity)

+ - **ISO 15288** — Systems engineering life cycle (needs → requirements → architecture → verification)

+ - **VDI 2221** — Systematic engineering design (clarify → concept → embody → detail)

+ - **NORSOK Z-013** — Risk and emergency preparedness (risk matrix, ALARP)

+ - **DNV-RP-A203** — Technology qualification (TRL assessment for novel solutions)

+ Your deliverable is a populated task folder under `task_solve/`.

+ ### Post-Folder Preflight (mandatory before Step 1 work)

+ After the task folder exists and `user_input.md` contains the prompt, do these

+ checks before writing Step 1 content:

+ 1. **Route check.** If the task spans multiple disciplines (e.g. process +

+ economics + safety), invoke `@router` first to confirm which specialist

+ agents to compose. For single-discipline tasks, skip.

+ 2. **Agent & skill review (ALWAYS — thorough).** Before writing any analysis,

+ do a deliberate review of the available **agents and skills** to find what

+ can help solve this task instead of solving from scratch:

+ - Run `<python-executable> devtools/skill_search.py "<task title>" --top 5` and load the

+ top-3 SKILL.md files with `read_file`.

+ - Scan the agent list (community + enterprise, e.g. `.github/agents/`,

+ `neqsim-community-agents/`, `neqsim-enterprise-agents/`) for discipline

+ specialists whose description matches the engineering question.

+ - Record the shortlist in `step1_scope_and_research/notes.md`: which

+ agents/skills you will use and why, and note explicitly where **no**

+ suitable agent/skill exists (that gap is a candidate improvement in the

+ Continuous Improvement Rule).

+ 3. **NeqSim codebase review (ALWAYS).** Before writing custom code, review the

+ NeqSim codebase to find existing functionality that solves the task:

+ - Consult `neqsim-capability-map` and `CHANGELOG_AGENT_NOTES.md`, then use

+ `semantic_search` / `grep_search` / `file_search` over

+ `src/main/java/neqsim/` for the relevant classes (equipment, EOS,

+ standards, mechanical design).

+ - Prefer an existing NeqSim class over a simplified Python correlation.

+ - Record in `notes.md` which NeqSim classes/methods will be used, and note

+ any missing capability as a gap to be closed (NIP + Java implementation

+ per Section 0 principle 2 and the Continuous Improvement Rule).

+ 3b. **Data-acquisition screening (ALWAYS — before assuming stand-in data).**

+ List the input data the task needs (equipment curves, geometry, fluid

+ composition, operating point, etc.) and, for **each** input, screen for a

+ retrieval tool/agent that can obtain the *real* value before falling back to

+ a representative assumption. Do NOT proceed with stand-in data for an input

+ that an available data-source agent could supply. Map each need to its

+ source using this table (community names shown; use the `enterprise-` twin

+ when on an enterprise task):

+ | Data need | Retrieve with | Notes |

+ |-----------|---------------|-------|

+ | Compressor/pump curves, vendor performance maps, datasheets, P&IDs, mechanical drawings, line lists, material certs | `@stid.reader` / `stid-reader-agent` + `neqsim-stid-retriever` (STID doc download → PDF/OCR → `neqsim-technical-document-reading`) | Vendor "map"/curve docs live in STID; download then extract the map digitally |

+ | Piping class, pipe internal diameter, wall thickness, valve (VDS/MDS) data, flange rating | `@tr2000` / `tr2000-agent` + `enterprise-tr2000-api` | Resolve line tag → PCS → internal Ø |

+ | Live instrument data / operating point (P, T, flow, speed, valve %, current recycle) | `@plant-data` / `plant-data-agent` + `neqsim-plant-data` (tagreader PI/IP.21) or `@seeq.connect` / `enterprise-seeq-connect` | Resolve historian tag from STID tag; prefer `/PRIM` channel; check units |

+ | Measured production volumes (well/field) | `rigga-production-agent` + `enterprise-rigga-production` | Measured production as feed / validation basis |

+ | Equipment / maintenance / failure history | `@maintenance` / `maintenance-agent` + `enterprise-maintenance-api` | Read-only work orders, notifications |

+ | Fluid composition / gas-sample molweight | STID/lab report via `@stid.reader`; else record as an explicit gap | A wrong MW mis-places compressor maps — always try to obtain it |

+ | Public literature / standards | `@literature-scout` | See step 6 |

+ Record in `notes.md`, for every required input: the source agent/skill you

+ will use, or an explicit statement that the value is a documented **stand-in

+ assumption** because no retrieval path is available (and why). "The data is a

+ field unknown" is only acceptable **after** the relevant retrieval agent has

+ been screened (and, where feasible, attempted). For governed enterprise

+ sources (STID, TR2000, tagreader, Seeq, Rigga, Maintenance, PEPR), prefer the

+ corresponding coordinator agent so authentication and read-only governance

+ are handled correctly.

+ 4. **Repo memory scan.** List `/memories/repo/*.md` via the `memory` tool.

+ Read any whose filename contains a keyword from the task title — this

+ surfaces prior solved tasks and known gotchas before you reinvent them.

+ 5. **Capability assessment + agent/workflow and code discovery.** For

+ Standard/Comprehensive tasks, invoke `@capability-scout` and write the result

+ to `step1_scope_and_research/capability_assessment.md`. As part of this step

+ you MUST run BOTH discovery tools and inspect the actual NeqSim implementation

+ before selecting a method. Never rely only on the static routing table,

+ capability-map prose, or mirrored task sources:

+ ```bash

+ <python-executable> devtools/skill_search.py "<task title>" --top 5

+ <python-executable> devtools/agent_search.py "<task title>" --top 8 \

+ --json --out step1_scope_and_research/agent_plan.json

+ ```

+ Then search `CHANGELOG_AGENT_NOTES.md`, `src/main/java/neqsim/`, neighboring

+ JUnit tests, and the locally resolved NeqSim dependency/JAR for the required

+ equipment, thermodynamics, standards, safety, mechanical-design, and utility

+ functionality. Verify constructors, method signatures, units, limitations,

+ and existing tests from source before writing analysis code. When local

+ source may be stale, also check current upstream `equinor/neqsim`; do not

+ classify a capability as missing from a skill description or mirrored tree

+ alone.

+ Then, in `capability_assessment.md`:

+ - fill **§4 Skills to Load** from `skill_search.py`,

+ - fill **§4b Agents to Delegate To** from `agent_search.py` (agent, repo, the

+ skills it loads, and why it was picked),

+ - fill **§4c Workflow Plan** — choose single-agent, a `router.agent.md`

+ composition pattern, or a declarative workflow (MCP `composeWorkflow` /

+ `composeMultiServerWorkflow`, or an `engineering-harness` study) when the

+ task spans ≥3 disciplines. Prefer delegating to a specialist agent over

+ re-loading its skills manually, so its governance and internal workflow are

+ reused (this is how "all functionality gets utilized").

+ - add a **NeqSim Code Functionality Reviewed** table containing each required

+ capability, exact class and method signatures, source/test/JAR evidence,

+ availability (`Available`/`Partial`/`Missing`), units/constraints, and how

+ the task will use it.

+ Persist the plan so it survives context loss and feeds the report:

+ - keep `step1_scope_and_research/agent_plan.json` (raw ranking, audit trail),

+ - checkpoint it via `progress.store_context("agent_workflow_plan", {...})`,

+ - add an `agent_workflow_plan` object to `results.json` (see schema) and

+ mention the agents/workflow used in the `approach` / `method_summary` text

+ so the generated report documents *how* the task was solved.

+ For Quick tasks, write a short manual capability + agent note in `notes.md`

+ unless a capability gap is suspected.

+ 6. **Literature scout** (Standard/Comprehensive only). Invoke

+ `@literature-scout` to populate `step1_scope_and_research/references/`

+ and the `## Literature & Reference Documents` section of `notes.md`.

+ ### Autonomous investigation (when the symptom / cause is NOT given)

+ For root-cause, deviation, under-performance, trip, or "why is this happening?"

+ tasks where the user has **not** told you what to look for, do not ask them.

+ Run the investigation loop from `neqsim-autonomous-investigation` BEFORE fixing a

+ scope, and use **all** available data and tools, not just the one tag/unit named:

+ 1. **Gather all data** — pull the full historian tag map (`@plant-data` /

+ `neqsim-plant-data` / `@seeq.connect`), plus alarms/events, maintenance

+ history, and STID design limits when available. Save snapshots to the task

+ folder.

+ 2. **Observe** — hand the whole tag map (no symptom) to

+ `RootCauseAnalyzer.analyzeAutonomous(tagToEquipment)` (or MCP

+ `runRootCauseAnalysis` with `symptom` omitted / `"AUTO"`). It auto-detects

+ abnormal tags (`AnomalyScanner`), discovers lead-lag relationships

+ (`RelationshipGraph`), and classifies them against the flowsheet topology

+ (`CausalTopologyModel`).

+ 3. **Hypothesize / test / discriminate** — form ≥3 competing hypotheses

+ (including "data/instrument artifact"), verify with the NeqSim simulation, and

+ report the **discovered relationships and the discriminating test**, not just a

+ single conclusion. Treat any supplied classification as a hint to challenge.

+ For operational plant tasks involving P&ID symbols, valve actions, live plant

+ data, active train state, isolation, evacuation, or dynamic response, load

+ `neqsim-pid-process-operations` together with `neqsim-technical-document-reading`,

+ `neqsim-process-extraction`, `neqsim-plant-data`, `neqsim-controllability-operability`,

+ and `neqsim-dynamic-simulation`. Keep public outputs plant-agnostic; use private

+ prompt files or private skills for site-specific document sources, historian

+ source names, tag maps, operator procedures, and company requirements.

+ Use `neqsim.process.operations` for Java deliverables and MCP `runOperationalStudy`

+ for tool-based tag-map validation, field-data application, valve scenarios, and

+ controller-response metrics.

+ For fast liquid-hammer cases, route the extracted STID geometry, tagreader event

+ window, and valve closure schedule through `neqsim-water-hammer` and MCP

+ `runWaterHammer` before deciding whether a detailed surge study is required.

+ ---

+ ## 1.5 ── CONTEXT WINDOW RESILIENCE (checkpoint & resume)

+ Long-running tasks (Standard and Comprehensive) routinely exhaust the context

+ window. When this happens, the agent starts a new conversation with no memory

+ of previous work. The **progress checkpoint** system solves this.

+ ### How it works

+ A `progress.json` file in the task folder records every completed milestone,

+ key decisions, derived context, and the next action. The file is updated after

+ each significant step. When a fresh agent picks up the task, it reads

+ `progress.json` first and knows exactly where to resume.

+ ### MANDATORY: Checkpoint after every milestone

+ After completing each numbered step in the workflow below, write a checkpoint:

+ ```python

+ import sys; sys.path.insert(0, "devtools")

+ from neqsim_runner.progress import TaskProgress

+ progress = TaskProgress("task_solve/YYYY-MM-DD_task_slug")

+ # After Phase 0 (classification)

+ progress.complete_milestone("phase0_classified",

+ summary="Type B (Process), Standard scale. 3-stage compression, SRK EOS.",

+ decisions={"type": "B", "scale": "Standard", "eos": "SRK",

+ "task_title": "3-stage compression from 5 to 150 bara"})

+ progress.set_next_action("Write task_spec.md with standards and acceptance criteria")

+ # After Step 1 (research)

+ progress.complete_milestone("step1_research_done",

+ summary="Research complete. Using API 617 for compressor design, "

+ "NORSOK P-001 for process. Feed: rich gas, 85% methane.",

+ outputs=["step1_scope_and_research/task_spec.md",

+ "step1_scope_and_research/notes.md"],

+ decisions={"standards": ["API 617", "NORSOK P-001"],

+ "feed_composition": {"methane": 0.85, "ethane": 0.07,

+ "propane": 0.05, "nC4": 0.03}})

+ progress.set_next_action("Create main notebook: 01_compression_analysis.ipynb")

+ # Store expensive-to-derive context

+ progress.store_context("api_methods", {

+ "compressor_class": "neqsim.process.equipment.compressor.Compressor",

+ "power_method": "getPower('kW')",

+ "polytropicEff_method": "getPolytropicEfficiency()",

+ })

+ ```

+ ### MANDATORY: Check for resume on every session start

+ When the user asks to resume a task, check that task's `progress.json` before

+ doing any new work. If it exists, you are **resuming** — do NOT repeat

+ completed steps:

+ ```python

+ import sys, os; sys.path.insert(0, "devtools")

+ from neqsim_runner.progress import TaskProgress

+ # Find the most recent task folder

+ import glob

+ tasks = sorted(glob.glob("task_solve/20*"))

+ if tasks:

+ progress = TaskProgress(tasks[-1])

+ if progress.is_resuming():

+ print(progress.resume_summary())

+ # READ THIS OUTPUT. It tells you:

+ # - What has been done

+ # - What decisions were made

+ # - What to do next

+ # DO NOT REDO completed milestones.

+ ```

+ ### What to store in checkpoints

+ | Milestone | What to save in `decisions` | What to save in `context` |

+ |-----------|---------------------------|--------------------------|

+ | phase0_classified | type, scale, eos, task_title | — |

+ | step1_spec_written | standards, acceptance_criteria | — |

+ | step1_research_done | feed_composition, operating_envelope | api_methods, neqsim_classes_used |

+ | step2_notebook_created | notebook_path, simulation_approach | cell_structure, import_patterns |

+ | step2_notebook_executed | key_results (T, P, power, etc.) | job_ids, output_paths |

+ | step2_validation_done | validation_method, max_deviation | benchmark_data_source |

+ | step2_results_saved | results_json_path | figure_list, table_data |

+ | step3_report_generated | report_paths | manual_sections_content |

+ ### Resume rules

+ 1. **Read progress.json FIRST for resume requests.** Before searching files or planning work.

+ 2. **Trust completed milestones.** Don't re-validate or re-run them unless outputs are missing.

+ 3. **Re-read decisions.** These were derived with full context — use them, don't re-derive.

+ 4. **Check context store.** If API method names or class paths were saved, use those directly.

+ 5. **Check for runner jobs.** If job_ids exist, check their status via the AgentBridge.

+ 6. **Resume from next_action.** This is the exact instruction the previous agent left for you.

+ 7. **If outputs are missing** despite milestone being marked done, re-do that milestone.

+ ### Break large tasks into sub-conversations

+ For Comprehensive tasks (multi-notebook, multi-day), proactively break the work

+ into conversation-sized chunks. After Phase 0 + Step 1, checkpoint and tell the

+ user: "Step 1 is complete. Please start a new conversation and say

+ `@solve-task resume task_solve/YYYY-MM-DD_slug` to continue with Step 2."

+ ### MANDATORY: Read `study_config.yaml` before planning notebooks

+ Every new task folder contains `study_config.yaml`. It is the explicit input

+ contract for task inputs, document sources, task depth, notebook plan, report

+ detail, and quality gates.

+ After creating the task folder and before writing `task_spec.md` or creating

+ notebooks:

+ 1. Read `task_solve/YYYY-MM-DD_slug/study_config.yaml`.

+ 2. Apply the intake gate before continuing:

+ - If `intake.pause_after_folder_creation` is `always`, pause and ask the

+ user to add or confirm missing task inputs before Step 1 work.

+ - If it is `auto`, pause for Standard/Comprehensive tasks when method-critical

+ values, required documents, or a fully authored config are missing.

+ - If it is `never`, continue with explicit assumptions unless a missing input

+ would make the calculation method invalid.

+ - When pausing, tell the user the task folder path, the `study_config.yaml`

+ path, and the `step1_scope_and_research/references/` drop folder. Explicitly

+ say that document input is possible, including PDFs, Word files, Excel

+ stream tables, P&IDs, vendor data sheets, standards, and lab reports. Do

+ not create notebooks until the user confirms to continue or the required

+ files are present.

+ 3. If `study.scale`, `report.depth`, `notebooks.plan`, `inputs.documents`, or

+ `quality_gates` are set to anything other than `auto`, treat those values as

+ higher priority than scale inferred from the prompt.

+ 4. If `inputs.documents_required` is true or `inputs.documents` lists source

+ files, verify the files are under `step1_scope_and_research/references/`,

+ classify them, extract relevant engineering data, normalize units/component

+ names, validate the values, and record the extraction in Step 1 notes or

+ structured JSON before building notebooks.

+ 5. For Comprehensive / Development tasks, do not invent a notebook plan until

+ `notebooks.plan` has been read. Create or execute the configured notebooks in

+ order, and checkpoint after each notebook.

+ 6. If a required configured notebook, report section, benchmark, uncertainty

+ analysis, risk register, figure discussion, or consistency check cannot be

+ produced, record the reason in `progress.json`, `results.json` limitations,

+ and the final report.

+ 7. Before Step 3, run `<python-executable> step3_report/generate_report.py`; the report

+ generator reads `study_config.yaml` and warns about missing configured

+ deliverables. Fix warnings marked as required before finalizing unless the

+ user explicitly accepts the limitation.

+ ---

+ ## 2 ── WORKFLOW (follow this exactly)

+ ### Phase 0: Setup — Create, Classify, and Scale

+ 1. **Create or identify the task folder first.**

+ - For a new task, the mandatory first action above has already created the

+ folder using `neqsim new-task ... --prompt ...`. If not, create it now.

+ - For a resume request, use the existing folder named by the user or the

+ latest task folder confirmed by `progress.json`.

+ - Read `README.md`, `user_input.md`, and `study_config.yaml` before writing

+ Step 1 content.

+ 2. **Confirm the task type** into one of these categories:

+ - **A** — Property (density, viscosity, JT coefficient, phase envelope, etc.)

+ - **B** — Process (separation, compression, dehydration, distillation, etc.)

+ - **C** — PVT (CME, CVD, swelling test, saturation pressure, etc.)

+ - **D** — Standards (ISO 6976, AGA, hydrocarbon dew point, etc.)

+ - **E** — Feature (add new NeqSim method/equipment/model)

+ - **F** — Design (wall thickness, mechanical sizing, PSV, etc.)

+ - **G** — Workflow (field development, design basis, technology screening — multi-discipline)

+ 3. **Determine the task scale** — this controls how deep you go:

+ |-------|-----------|-----|-----------|-----------|-----------|--------|

+ **Scale auto-detection rules:**

+ - User mentions specific standards (NORSOK, DNV, ISO) → at least Standard

+ - User asks for multiple deliverables → at least Standard

+ - User says "field development", "design basis", "concept selection", "Class A/B" → Comprehensive

+ - User asks a single question with no standards → Quick

+ - When in doubt, ask the user: "This looks like a [scale] task — should I go deeper or keep it light?"

+ **Follow-up questions (ask only when method-critical data is missing):**

+ Ask these scoping questions only when missing inputs would materially change

+ the calculation method, acceptance criteria, or decision recommendation.

+ Otherwise proceed with explicit assumptions and continue without blocking.

+ 1. **Fluid / resource**: What is the reservoir fluid composition? If unavailable,

+ what type (lean gas, rich gas, oil, condensate)? What is the estimated

+ resource volume (GIP/STOIIP) and its uncertainty range?

+ 2. **Operating envelope**: What are the design pressure, temperature, and flow

+ rate ranges? Any constraints (backpressure limit, arrival temperature)?

+ 3. **Standards & jurisdiction**: Which design codes apply (NORSOK, DNV, API,

+ ASME)? Which fiscal/tax regime (Norwegian NCS, UK, generic)?

+ 4. **Economics**: What gas/oil price range and currency? What discount rate?

+ Are cost estimates needed (CAPEX breakdown, OPEX)?

+ 5. **Uncertainty scope**: Which parameters are most uncertain? Should Monte

+ Carlo use full NeqSim process simulations (slower, more accurate) or

+ simplified correlations (faster)?

+ 6. **Deliverables**: What output format — quick answer, notebook only, or full

+ Word + HTML report? Are benchmarks against published data required?

+ 7. **Risk categories**: Which risk categories matter most (market, technical,

+ HSE, regulatory, schedule)?

+ For Quick-scale tasks, skip questions and proceed directly.

+ 4. **If the folder still does not exist, create it now — non-negotiable:**

+ ```

+ Run in terminal: neqsim new-task "TASK TITLE" --type X --author "Agent" --prompt "<verbatim user request>"

+ ```

+ For long requests, save the prompt to a file and use `--prompt-file`.

+ Use explicit depth inputs when the user requests a deep study, for example:

+ ```

+ neqsim new-task "TASK TITLE" --type G --author "Agent" --prompt "<verbatim user request>" --scale comprehensive --report-depth detailed --notebooks 5 --intake-pause always

+ ```

+ Or pass a fully authored configuration:

+ ```

+ neqsim new-task "TASK TITLE" --type G --author "Agent" --prompt "<verbatim user request>" --config-file path/to/study_config.yaml

+ ```

+ This creates `task_solve/YYYY-MM-DD_task_slug/` with all subfolders.

+ **ALL subsequent files MUST go inside this folder. Do NOT proceed without it.**

+ Read the generated README and verify `user_input.md` captured the prompt

+ before continuing.

+ 5. **Run the intake gate before Step 1 work:**

+ - Read `study_config.yaml`.

+ - Tell the user the task folder exists.

+ - Ask for missing method-critical values or invite them to add documents to

+ `step1_scope_and_research/references/` and edit `study_config.yaml`.

+ - Explicitly say that document input is possible for the task.

+ - Continue only after confirmation when `--intake-pause always` was used or

+ required inputs are missing.

+ 6. **Run the post-folder preflight** described in Section 1, then checkpoint.

+ **CHECKPOINT (Phase 0):** After creating the task folder and classifying:

+ ```python

+ import sys; sys.path.insert(0, "devtools")

+ from neqsim_runner.progress import TaskProgress

+ progress = TaskProgress("task_solve/YYYY-MM-DD_task_slug")

+ progress.complete_milestone("phase0_classified",

+ summary="[1 sentence: type, scale, method]",

+ decisions={"type": "X", "scale": "Standard", "eos": "SRK",

+ "task_title": "..."})

+ progress.set_next_action("Write task_spec.md")

+ ```

+ ### Phase 1: Scope & Research (Step 1)

+ 5. **Fill in the task specification** (`step1_scope_and_research/task_spec.md`).

+ Adapt depth to the task scale:

+ **Quick scale:** Fill only the essential fields — method/EOS, one-line acceptance

+ criterion, and the specific condition to calculate. Leave other sections empty.

+ **Standard scale:** Fill all sections — standards, methods, deliverables,

+ acceptance criteria, operating envelope, input data.

+ **Comprehensive scale:** Fill every section in detail. List ALL applicable

+ standards with specific clause numbers. Define a complete work breakdown of

+ deliverables. Set quantitative acceptance criteria for every output. Define

+ the full operating envelope with min/design/max values.

+ The task spec sections:

+ **Design Basis Header** (Design/Development mode — per NORSOK P-001 practice):

+ - **Document ID**: Auto-generated from task folder name

+ - **Revision**: Rev 0 (initial), increment on significant parameter changes

+ - **Status**: Draft → Issued for Review → Approved

+ - **Design life**: e.g., 25 years (or N/A for property lookups)

+ - **Design code**: Primary governing standard (e.g., ASME VIII Div.1, DNV-ST-F101)

+ - **Design conditions**: Summary table of design P, T, flow rate with units

+ **Core sections (all modes):**

+ - **Applicable standards** (MANDATORY — see below): Which codes, standards, and

+ company TRs govern this task (NORSOK, ISO, DNV, API, ASME, company TR documents).

+ Load the `neqsim-standards-lookup` skill for equipment-to-standards mapping.

+ - **Calculation methods/models**: Which EOS, correlations, pipe flow models to use

+ - **Required deliverables**: What the final output must include

+ - **Acceptance criteria**: Mass balance tolerance, design factors, safety margins

+ - **Operating envelope**: Range of conditions to cover (P, T, flow, composition)

+ - **Input data**: Reference fluid compositions, operating conditions, equipment data

+ **Standards identification (MANDATORY — proportional to scale):**

+ | Scale | Standards Requirement |

+ |-------|---------------------|

+ | Quick | 1-line note: "Per [STANDARD]" or "N/A — property lookup" |

+ | Standard | Table listing each applicable standard with scope |

+ | Comprehensive | Full table with clause numbers, design values, limits, compliance evidence |

+ Use the equipment-to-standards mapping from `neqsim-standards-lookup` skill to

+ automatically identify standards based on the equipment types in the simulation.

+ Query `designdata/standards/standards_index.csv` for the mapping.

+ **Scope limitations** (Design/Development mode):

+ - **In scope**: What this analysis covers

+ - **Out of scope**: What is explicitly excluded (e.g., "detailed fatigue analysis",

+ "site-specific seismic loads", "control system design")

+ - **Validity envelope**: Conditions under which results are valid (T range, P range,

+ composition range, flow regime). Results outside this envelope require re-analysis.

+ - **Model limitations**: Known EOS/correlation limitations at the operating conditions

+ (e.g., "SRK accuracy degrades near critical point", "Beggs & Brill not validated

+ above 90° inclination")

+ If the user specifies standards or methods in their request (e.g., "per NORSOK P-001"),

+ incorporate these directly into the task spec. If not specified, select appropriate

+ standards based on the task type and engineering domain.

+ 6. **Auto-search for similar past solutions (MANDATORY):**

+ Before writing any new code, search for related prior work:

+ - **Semantic search** `task_solve/` folder for keywords from the current task

+ - **Keyword search** `docs/development/TASK_LOG.md` for task type, equipment, fluid, standards

+ - **Search** `docs/development/CODE_PATTERNS.md` for relevant patterns

+ - **Search** `src/test/java/neqsim/` for existing tests covering similar equipment/fluids

+ - **Search** `examples/notebooks/` for related notebooks

+ - If a similar task was solved before, **start from that solution** — adapt rather than rebuild

+ - Document what prior work was found (or not found) in `notes.md`

+ 6b. **Gather background knowledge** for the task:

+ - Search the NeqSim codebase for existing classes/methods relevant to the task

+ - Check `CHANGELOG_AGENT_NOTES.md` for any recent API changes affecting this task

+ - Use web search if available for engineering reference data

+ - **Retrieve vendor documents** if the task references specific equipment tags.

+ Load the `neqsim-stid-retriever` skill for document retrieval patterns:

+ relevance filtering, retrieval manifests, and backend configuration.

+ If a retrieval backend is configured (via gitignored `devtools/doc_retrieval_config.yaml`),

+ auto-fetch performance curves, mechanical drawings, and data sheets.

+ Otherwise, expect documents in `step1_scope_and_research/references/`.

+ Users can always **add documents manually** to `references/` alongside

+ auto-retrieved ones — both sources coexist and are tracked in the manifest.

+ Ask the user for additional documents only when the task is Standard or

+ Comprehensive and the missing documents would materially change the method,

+ constraints, or recommendation. For Quick tasks, proceed with documented

+ assumptions unless the calculation is invalid without the document.

+ For trapped-liquid fire rupture studies, load `neqsim-trapped-liquid-fire-rupture`

+ and retrieve the full evidence pack before calculation: P&ID/STID isolation

+ boundaries, line lists, piping specs, material certificates, flange/bolt/gasket

+ data, fire-zone/PFP documents, relief/thermal relief basis, and acceptance

+ criteria. Missing evidence must be written to `results.json` as assumptions/gaps.

+ - **Extract figures from reference PDFs** placed in `step1_scope_and_research/references/`:

+ ```bash

+ <python-executable> devtools/pdf_to_figures.py step1_scope_and_research/references/ --outdir figures/

+ ```

+ Then use `view_image` on extracted PNGs to read engineering drawings, P&IDs,

+ charts, data tables, and compressor maps. This makes PDF content available

+ for AI analysis (diagram digitization, data extraction, layout understanding).

+ - **Structured image analysis workflow** (for vendor drawings, P&IDs, datasheets):

+ When reference documents contain engineering drawings or visual data, use the

+ `neqsim-technical-document-reading` skill Section 3.7 patterns:

+ 1. **P&IDs** → Extract equipment tags, valve tags, instrument tags, piping

+ sizes/classes, line numbers, and connection topology using the

+ `PID_EXTRACTION` format. This provides the flowsheet topology that

+ informs the NeqSim `ProcessSystem` model.

+ 2. **Vendor API datasheets** (e.g., API 692 seal datasheets, API 617

+ compressor datasheets) → Extract operating conditions, design data,

+ performance parameters, and material specs using the

+ `VENDOR_DATASHEET_EXTRACTION` format. These values become simulation

+ inputs and validation targets.

+ 3. **Mechanical arrangement drawings** → Extract dimensions, nozzle

+ schedules, standpipe geometry (lengths, bore sizes, volumes), piping

+ run lengths using `MECHANICAL_ARRANGEMENT_EXTRACTION` format. Physical

+ dimensions feed into volume calculations, heat transfer models, and

+ residence time estimates.

+ 4. **Performance maps / phase envelopes** → Digitize key points (rated

+ point, surge line, cricondentherm, operating envelope boundaries)

+ using `PERFORMANCE_MAP_EXTRACTION` or `PHASE_ENVELOPE_EXTRACTION`

+ format. These validate simulation results against vendor/design data.

+ 5. **Generate figure discussions** — for each image analyzed that informs

+ the engineering analysis, produce a figure discussion block (observation,

+ mechanism, implication, recommendation) and include it in

+ `results.json["figure_discussion"]` for the report.

+ 7. **Write comprehensive research notes** to `step1_scope_and_research/notes.md`.

+ These notes must be **substantive** — not a skeleton template.

+ The depth should be proportional to the task mode.

+ **Screening mode:** A condensed version covering: sources consulted, key

+ data / sanity-check values, NeqSim classes used, and assumptions made.

+ **Design / Development mode (full sections):**

+ - **Sources** (table): Every source consulted — NeqSim classes, papers, standards,

+ web references, textbooks. Minimum 5 entries for Standard tasks, 10+ for Comprehensive.

+ - **Literature & Reference Documents**: For each key reference, write a structured

+ summary with: file location, relevance, key equations cited, key data extracted,

+ limitations, and how it applies to this specific task.

+ - **Background — Engineering Context**: Explain the real-world engineering problem

+ in 2-3 paragraphs. Why does this matter? What goes wrong in practice? What are

+ the consequences of getting it wrong? Include industry context.

+ - **Background — Physical Mechanisms**: Describe the underlying physics. What

+ thermodynamic, chemical, or transport phenomena are involved? Include governing

+ equations with variable definitions.

+ - **Key Data / Correlations**: Reference values, design rules of thumb, typical

+ operating ranges. These are the "sanity check" values used during validation.

+ - **Industry Experience / Case Studies**: Known field cases, operational incidents,

+ lessons learned. This grounds the analysis in reality.

+ - **Relevant Standards — Detailed Requirements**: For each standard in task_spec,

+ extract the specific clauses, equations, tables, and design factors that apply.

+ Don't just list the standard — quote the requirement.

+ - **NeqSim API Coverage — Detailed Inventory**: For each capability needed, check

+ if NeqSim has it. Search the Java source code. List class names, key methods,

+ and any limitations found. This feeds directly into Phase 1.5.

+ - **Open Questions**: Uncertainties, missing data, things to clarify with the user

+ ### Phase 1.5: Deep Analysis & Solution Design (required for high-consequence work)

+ Before writing simulation code for design, workflow, safety-critical, or

+ high-value economics tasks, produce a **thorough engineering analysis document**

+ that gives deep insight and a clear solution path. For smaller tasks, use a

+ condensed analysis section in notes and proceed.

+ 7b. **Write a detailed problem analysis** to `step1_scope_and_research/analysis.md`.

+ Include the following sections (depth proportional to task consequence):

+ #### 7b.1 — Physics & Theory Deep-Dive

+ Explain the fundamental physics/engineering behind the problem at a level

+ suitable for a senior engineer review:

+ - **Governing equations** with derivations or references (use LaTeX notation)

+ - **Physical mechanisms** — what causes the phenomenon, why it matters

+ - **Thermodynamic basis** — which EOS is appropriate and why, phase behavior

+ - **Transport phenomena** — heat/mass transfer, fluid mechanics if relevant

+ - **Key assumptions** — what simplifications are being made and their impact

+ - **Dimensional analysis** — key dimensionless groups if applicable