hecras_plan_execution

Analyze the Project Inspector output and generate an actionable execution plan. Select the optimal execution mode, recommend parameters, and identify blockers.

Primary Sources

Read the primary sources below; do not duplicate their content.

• .claude/rules/hec-ras/execution.md - Complete execution mode documentation
• .claude/agents/hecras-project-inspector.md - Project Intelligence Report schema
• .claude/skills/hecras_compute_rascontrol/SKILL.md - Legacy HEC-RAS (< 6.0)

---

Mode Selection Decision Tree

1. Is HEC-RAS version < 6.0?
   YES -> Use RasControl (hecras_compute_rascontrol skill)
   NO  -> Continue

2. How many runnable plans?
   ZERO    -> Report blockers, stop
   ONE     -> compute_plan() [+ stream_callback if monitoring needed]
   MULTIPLE -> Continue to step 3

3. Multiple Plan Decision:
   Debugging/diagnosing? -> compute_test_mode()
   Have remote workers?  -> compute_parallel_remote()
   Production/batch?     -> compute_parallel()

Mode Selection Matrix

| Context | Plans | Mode | Rationale | |---------|-------|------|-----------| | Debugging | Any | compute_test_mode() | Sequential, single folder | | Single plan, monitoring | 1 | compute_plan() + callback | Real-time output | | Single plan, quick | 1 | compute_plan() | Simplest API | | Multiple plans, production | 2+ | compute_parallel() | Fastest throughput | | Distributed infrastructure | 2+ | compute_parallel_remote() | Scale-out | | HEC-RAS < 6.0 | Any | RasControl | COM-based required | | Resume interrupted | 2+ | compute_parallel(skip_existing=True) | Skips completed |

---

Input: Project Intelligence Report

Expect this input format from the Project Inspector Agent:

## Plans Analysis
| Plan | Title | Status | Geometry | Flow | Issues |
|------|-------|--------|----------|------|--------|
| 01 | Baseline | Runnable | g01 | u01 | None |
| 02 | Future | Missing geom | g03 (MISSING) | u02 | Geometry file not found |

### Execution Readiness
- **Ready to Run**: 01, 03
- **Blocked**: 02 (missing geometry g03)

---

Output: Execution Plan

Generate structured execution plans in this format and return to the orchestrator:

# Execution Plan

## Recommended Mode
`compute_parallel()` - Multiple runnable plans, production context

## Execution Order
1. Plan 01 (Baseline) - Ready
2. Plan 03 (Modified) - Ready
   [Skip: Plan 02 - blocked by missing geometry g03]

## Parameters
```python
RasCmdr.compute_parallel(
    plans_to_run=["01", "03"],
    max_workers=2,
    num_cores=4,
    force_rerun=False,
    verify=True
)

Prerequisites

• None for runnable plans

Blockers (Cannot Run)

| Plan | Issue | Resolution | |------|-------|------------| | 02 | Missing geometry g03 | Create geometry file or fix reference |

Warnings

• Plan 02 blocked until g03 is created

---

## Parameter Recommendation

### Worker/Core Allocation

| System Cores | Model Type | `max_workers` | `num_cores` |
|--------------|------------|---------------|-------------|
| 4-8 | 1D | 2-4 | 2 |
| 8-16 | 2D | 2-4 | 4 |
| 16+ | Mixed | 4-6 | 4 |

**Formula**: `max_workers = min(num_plans, total_cores // num_cores)`

### Geometry Flags

| Scenario | `clear_geompre` | `force_geompre` |
|----------|-----------------|-----------------|
| Geometry unchanged | `False` | `False` |
| Minor edits (Manning's n) | `True` | `False` |
| Major changes (new mesh) | `False` | `True` |
| Geometry corruption | `False` | `True` |

### Skip/Rerun Flags

| Scenario | `force_rerun` | `skip_existing` |
|----------|---------------|-----------------|
| Normal (smart skip) | `False` | `False` |
| Force fresh results | `True` | `False` |
| Resume interrupted | `False` | `True` |

---

## Dependency Analysis

### Check for Blockers

```python
def get_runnable_plans(plan_df):
    """Identify which plans can execute."""
    runnable, blocked = [], {}

    for _, plan in plan_df.iterrows():
        plan_num = plan['plan_number']
        geom_ok = Path(plan['Geom Path']).exists() if plan.get('Geom Path') else True
        flow_ok = Path(plan['Flow Path']).exists() if plan.get('Flow Path') else True

        if geom_ok and flow_ok:
            runnable.append(plan_num)
        else:
            blocked[plan_num] = "Missing geometry" if not geom_ok else "Missing flow"

    return runnable, blocked

Dependencies to Consider

1. Shared Geometry - Plans using same geometry can run in parallel
2. Upstream/Downstream - Cascade models need sequential execution
3. DSS Dependencies - Plans reading same DSS may conflict

---

Context-Specific Templates

Debugging Context

RasCmdr.compute_test_mode(
    plans_to_run=["01", "02", "03"],
    dest_folder_suffix="[Debug]",
    num_cores=2,
    verify=True
)

Production Context

RasCmdr.compute_parallel(
    plans_to_run=["01", "02", "03"],
    max_workers=4,
    num_cores=4,
    verify=True
)

Monitoring Context

from ras_commander.callbacks import ConsoleCallback

RasCmdr.compute_plan(
    "01",
    stream_callback=ConsoleCallback(verbose=True),
    verify=True
)

---

Common Blockers

| Blocker | Resolution | |---------|------------| | Missing geometry file | Create geometry or fix .prj reference | | Missing flow file | Create flow file or fix reference | | Missing DSS file | Download/create DSS or update path | | Geometry HDF outdated | Run with force_geompre=True | | Results already current | Use force_rerun=True if needed | | HEC-RAS < 6.0 | Use RasControl skill instead |

---

Cross-References

Rules (follow these):

• .claude/rules/hec-ras/execution.md -- Detailed execution mode parameters
• .claude/rules/hec-ras/remote.md -- Read when remote execution is needed

Agents (delegate when needed):

• hecras-general-agent -- Full workflow coordinator
• hecras-project-inspector -- Project analysis to inform mode selection
• remote-executor -- Remote execution setup and management

Skills (related workflows):

• hecras_compute_plans -- Downstream: execute plans using the selected mode
• hecras_compute_remote -- Downstream: distributed execution across workers
• hecras_compute_rascontrol -- Downstream: legacy COM execution

Primary sources:

• ras_commander/AGENTS.md -- Execution modes overview
• ras_commander/RasCmdr.py -- compute_plan, compute_parallel, compute_test_mode