swmm-design-review — Design Review / Code-Compliance Checker

What this skill does

Evaluates a completed SWMM run against a configurable rulebook of design checks. Reads the run's existing artifacts (manifest.json + model.rpt + model.inp) — SWMM is never re-run. Classifies each rule as pass, fail, warn, or needs-data and writes 09_review/design_review.json + 09_review/design_review.md into the run directory.

This skill is decision-support only. It never certifies regulatory compliance.

CLI usage

# Standalone script
python3 skills/swmm-design-review/scripts/design_review.py \
    --run-dir <path>         # required: directory with model.rpt, manifest.json, model.inp
    [--rpt <path>]           # override: explicit model.rpt path
    [--inp <path>]           # override: explicit model.inp path
    [--manifest <path>]      # override: explicit manifest.json path
    [--rules <rulebook>]     # override rulebook YAML/JSON (repeatable for multiple books)
    [--out-dir <dir>]        # default: <run-dir>/09_review/
    [--no-inp]               # skip INP-derived metrics (slope, diameter)

# CLI verb (registered in aiswmm CLI)
aiswmm review --run-dir <path> [--rules <rulebook.yaml>] [--out-dir <dir>]

Exit codes: 0 = pass/warn/needs-data only; 1 = any FAIL; 2 = script/input error.

Agent tool: review_run

Registered in AgentToolRegistry. Direct handler (not MCP-routed) — writes 09_review/design_review.json + 09_review/design_review.md into the run dir.

review_run(run_dir="runs/my_run/")
review_run(run_dir="runs/my_run/", rules="skills/swmm-design-review/rulebooks/gb50014_template.yaml")

is_read_only=False — QUICK profile prompts the user (tool writes files).

Executed example

python3 skills/swmm-design-review/scripts/design_review.py \
    --run-dir tests/fixtures/design_review \
    --manifest tests/fixtures/design_review/sample_manifest.json \
    --rpt tests/fixtures/design_review/sample_mini.rpt \
    --inp tests/fixtures/design_review/sample_mini.inp \
    --rules tests/fixtures/design_review/sample_rules.yaml \
    --out-dir /tmp/design_review_out
# Exit 1 = FAIL (1 pass, 1 fail, 0 warn, 1 needs-data)
# Report: /tmp/design_review_out/design_review.md

Return-period adequacy workflow

To check return-period adequacy (RETURN_PERIOD_ADEQUACY rule):

1. generate_design_storm with the target return period P.
2. build_inp to integrate the design storm into the model.
3. run_swmm_inp --storm-return-period-yr P to propagate provenance to manifest.
4. design_review.py --run-dir <path> — extractor reads manifest.metadata.storm_return_period_yr.

Until step 3 is wired (separate PR), RETURN_PERIOD_ADEQUACY returns needs-data.

Metrics available today (PR1)

Metrics returning needs-data until PR2: node.surcharge_hours, node.max_depth_m, node.flooding_hours, node.flooding_volume_m3, junction.freeboard_m, run.return_period_yr.

Output files

• <run-dir>/09_review/design_review.json — machine-readable results (schema_version 1.0)
• <run-dir>/09_review/design_review.md — human report with disclaimer and sign-off table

What the agent MUST say

When presenting review results, the agent must:

1. Lead with the overall status (PASS / FAIL / WARN / NEEDS-DATA).
2. State the disclaimer: _"Findings are decision-support only and do NOT constitute

compliance with any drainage standard."_

1. Invite the engineer to inspect any FAIL or NEEDS-DATA finding before proceeding.
2. List NEEDS-DATA rules prominently with the reason they cannot produce a result.

What the agent MUST NOT say

• Do NOT say "the design is compliant with GB 50014" or any equivalent.
• Do NOT say "no issues found" when there are NEEDS-DATA rules — those are not passes.
• Do NOT paraphrase away the disclaimer.
• Do NOT imply the thresholds are authoritative — all template thresholds carry

verify: true precisely because they must be confirmed by the user.

Custom rulebooks

Write a YAML file following the schema in rulebooks/gb50014_template.yaml. Every rule must have:

• id (SCREAMING_SNAKE_CASE, unique)
• metric (named extractor from the table above)
• operator (lte / lt / gte / gt / eq / neq / between)
• threshold (float, SI) or threshold_low + threshold_high for between
• units: SI
• severity: FAIL or severity: WARN
• citation — clause reference or "TODO: cite local standard"
• verify: true unless you have personally confirmed the threshold against the

applicable edition of the standard

Honesty rule: a rule MUST NOT have verify: false while citation is still "TODO: cite local standard". The test suite enforces this invariant.

Part of

Issue #249 capability backlog — design-review / code-compliance checker. PR1: extractor layer + evaluator + rulebook + reports + tests. PR2 (upcoming): ToolSpec wiring, CLI verb, rpt_summary extensions.