# Modeling Workflow Memory

## Purpose

This memory tells me how to guide a public repository user through a complete Agentic SWMM modelling and verification workflow in order. I use it after `operational_memory.md` and before `evidence_memory.md`.

## User-facing workflow order

When you ask me to build or verify a SWMM model, I'll guide the session in this order:

1. Define the modelling goal.
2. Inventory available input files.
3. Select the workflow mode.
4. Create a run directory.
5. Prepare or validate stage inputs.
6. Build the SWMM input file.
7. Run SWMM.
8. Run QA checks.
9. Create plots if requested or useful.
10. Run calibration only if observed data and intent exist.
11. Run fuzzy uncertainty only if uncertainty bounds or membership functions exist.
12. Run experiment audit.
13. Optionally run modeling-memory summarization.
14. Report readiness and evidence boundaries.

I won't skip directly to SWMM execution unless the required prepared inputs already exist.

## Step 1: Define the modelling goal

I'll ask or infer the narrow modelling goal:

- build only,
- build + run,
- build + run + QA,
- prepared-input benchmark,
- real-data smoke test,
- calibration,
- uncertainty propagation,
- audit or comparison of an existing run.

If you tell me you want a "complete modelling workflow", I'll default to build + run + QA.

## Step 2: Inventory available input files

Before selecting a path, I'll check for these input classes:

- subcatchment geometry or `subcatchments.csv`,
- network source files or `network.json`,
- rainfall input,
- land use input,
- soil input,
- existing SWMM `.inp`,
- observed flow file for calibration,
- fuzzy parameter space for uncertainty.

I'll report missing inputs by class and expected format — I won't ask for "all data" generically.

## Step 3: Select the workflow mode

I use this decision tree:

- If a complete external `.inp` already exists, I use prepared-input run/QA/audit.
- If `subcatchments.csv`, `network.json`, params, and rainfall artifacts exist, I use prepared-input build.
- If raw GIS, network, rainfall, land use, and soil inputs exist, I use the full modular build.
- If public examples are the only available data, I use an example or benchmark path.
- If you want real-data execution and Tod Creek fallback inputs exist, I use the minimal Tod Creek fallback.
- If only existing run artifacts exist, I use audit-only or comparison mode.

I'll explain the selected mode in one sentence before running tools.

## Step 4: Create a run directory

I use a stable run directory:

```text
runs/<case>/
```

If you didn't provide a case name, I'll choose a short, filesystem-safe name from the scenario or input source. I keep all generated stage outputs inside this directory.

## Step 5: Prepare or validate stage inputs

For full modular builds, I follow the stage order:

1. GIS or subcatchment preprocessing.
2. Land use and soil parameter mapping.
3. Rainfall formatting and raingage section generation.
4. Network import or network QA.

I stop if a critical input is missing. A full modular build requires a real network source or `network.json`; I won't invent one.

## Step 6: Build the SWMM input file

I use `swmm-builder` to create:

```text
runs/<case>/05_builder/model.inp
runs/<case>/05_builder/manifest.json
```

I treat builder validation failures as hard stops unless you explicitly ask for a diagnostic-only artifact.

## Step 7: Run SWMM

I use `swmm-runner` to execute the built or provided `.inp`.

Expected outputs:

```text
runs/<case>/06_runner/model.rpt
runs/<case>/06_runner/model.out
runs/<case>/06_runner/manifest.json
```

I do not treat the run as successful until the return code and output artifacts are checked.

## Step 8: Run QA checks

Minimum QA checks:

- continuity,
- mass balance when available,
- peak flow parsed from the correct report section,
- output artifact existence,
- manifest completeness.

Expected outputs:

```text
runs/<case>/07_qa/continuity.json
runs/<case>/07_qa/peak.json
```

If QA fails, I'll report the failed check and continue to audit the partial run.

## Step 9: Create plots

I'll create rainfall-runoff plots when you ask for visualization, reporting, or paper-facing artifacts. I keep plots in:

```text
runs/<case>/08_plot/
```

## Step 10: Calibration gate

I'll only run calibration when:

- you requested calibration or model fitting,
- an observed flow file exists,
- the observed series parses,
- the observed and simulated periods overlap.

If those conditions are not met, I'll explain what is missing and continue with run/QA/audit. I won't claim a model is calibrated unless these checks pass.

## Step 11: Fuzzy uncertainty gate

I'll only run fuzzy uncertainty when:

- you ask for uncertainty propagation, or
- a fuzzy/interval parameter space is provided, or
- the workflow explicitly includes scenario envelopes.

I use `skills/swmm-uncertainty/` and keep uncertainty artifacts in:

```text
runs/<case>/09_uncertainty/
```

## Step 12: Experiment audit

I always run the audit layer after success, failure, or early stop.

Expected outputs:

```text
runs/<case>/experiment_provenance.json
runs/<case>/comparison.json
runs/<case>/experiment_note.md
```

The audit record preserves partial evidence. I won't pretend missing stages were completed.

## Step 13: Optional modeling-memory summarization

I'll run modeling-memory summarization when multiple audited runs exist or when you want lessons learned, failure-pattern extraction, or skill-improvement proposals.

Use:

```bash
python3 skills/swmm-modeling-memory/scripts/summarize_memory.py \
  --runs-dir runs \
  --out-dir memory/modeling-memory
```

I treat generated skill update proposals as proposals only. I won't modify existing skills unless a human accepts the proposal after benchmark verification.

## Step 14: Final readiness report

I'll end with a concise readiness report:

- selected workflow mode,
- run directory,
- completed stages,
- produced artifacts,
- QA results,
- audit files,
- modeling-memory files if generated,
- missing inputs or failed checks,
- whether the result is runnable, checked, audited, calibrated, validated, or only a smoke test.

I use precise language. A completed SWMM run is not automatically a calibrated or validated model, and I'll keep the evidence boundary visible.
