Investigating Hms Internals

---
name: investigating-hms-internals
description: |
  Investigates HEC-HMS internals through decompiled Java classes. Provides JythonHms
  API reference, CLI options, version-specific differences (3.x vs 4.x), and guides
  on-demand decompilation for new discoveries. Use when debugging HMS behavior,
  discovering undocumented features, understanding version differences, validating
  automation approaches, or investigating HMS API capabilities. Includes complete
  JythonHms method reference, Python 2 vs 3 syntax differences, and decompilation
  tooling. Complements hms_doc_query (official docs) with internal implementation details.

  Trigger keywords: decompile, HMS internals, JythonHms API, HMS version differences,
  CLI options, undocumented, HMS jar, HMS classes, debugging HMS, HMS source code,
  HMS 3.x support, Python 2 vs 3, HMS methods, HMS parameters.
---

# Investigating HMS Internals

**Purpose**: Understand HEC-HMS internal implementation through decompiled Java classes to support hms-commander development and debugging.

---

## Quick Start

### Check JythonHms Method
```
Q: "Does HMS support SetTimeWindow()?"
A: See hms_agents/hms_decompiler/knowledge/JYTHON_HMS_API.md
```

### Check Version Compatibility
```
Q: "Does HMS 3.3 support Jython?"
A: See hms_agents/hms_decompiler/knowledge/HMS_3x_SUPPORT.md
→ YES! Discovered via decompilation
```

### Decompile New Class
```
cd hms_agents/hms_decompiler/tools
decompile.bat "C:\...\hms.jar" "hms.model.ClassName" output
```

---

## Primary Sources

### Production Agent
**Location**: `hms_agents/hms_decompiler/`

**Quick access**:
- `QUICK_START.md` - 5-minute guide
- `AGENT.md` - Comprehensive documentation
- `knowledge/` - Curated API references
- `reference/` - Key decompiled classes
- `tools/` - Decompilation utilities (cfr.jar)
- `examples/` - Usage workflows

**This agent is self-contained** with all necessary reference data and tools.

---

## When to Use This Skill

### ✅ Use When

1. **Checking API Existence**
   - "Does JythonHms have method X?"
   - "What parameters does SetLossRateValue accept?"
   - "Is there a method to set time window?"

2. **Version Compatibility**
   - "Does HMS 3.x support Jython?"
   - "What's different between HMS 3.x and 4.x?"
   - "Will this API work in HMS 3.5?"

3. **Understanding Behavior**
   - "Why does this HMS call fail?"
   - "What error codes does HMS use?"
   - "How does HMS execute scripts?"

4. **Discovering Features**
   - "Are there undocumented JythonHms methods?"
   - "What CLI flags does HMS support?"
   - "Does HMS have an RMI command server?"

5. **Validating Automation**
   - "Can I automate optimization via Jython?"
   - "How should I structure my script?"
   - "What's the correct method signature?"

### ❌ Don't Use When

1. **Official Documentation Query**
   - Use **hms_doc_query** agent instead
   - hms_doc_query searches User's Manual, Technical Reference

2. **hms-commander API Questions**
   - Read hms-commander docstrings
   - Check examples/ notebooks
   - See hms-commander documentation

3. **Project File Parsing**
   - Use **parsing-basin-models** skill
   - Use HmsBasin, HmsMet, HmsControl classes

---

## Knowledge Files

### 1. JYTHON_HMS_API.md

**Location**: `hms_agents/hms_decompiler/knowledge/JYTHON_HMS_API.md`

**Contains**:
- Complete JythonHms method reference (HMS 4.x)
- Method signatures, parameters, exceptions
- Examples and usage notes
- Internal implementation details
- Deprecated/removed methods

**Example lookup**:
```
Q: "What parameters does SetLossRateValue accept?"
A: SetLossRateValue(elementName, parameterName, value)
   - elementName (String): Subbasin name
   - parameterName (String): e.g., "Curve Number"
   - value (double): Parameter value
```

### 2. HMS_3x_SUPPORT.md

**Location**: `hms_agents/hms_decompiler/knowledge/HMS_3x_SUPPORT.md`

**Contains**:
- HMS 3.x Jython support discovery (✅ YES!)
- Python 2 vs 3 syntax differences
- API method availability (3.x vs 4.x)
- Example scripts for both versions
- Test results from hms-commander

**Key finding**:
```
HMS 3.3+ supports Jython scripting (undocumented)!
Requires Python 2 syntax: print "text" (not print("text"))
Use Compute() instead of ComputeRun()
```

### 3. HMS_CLI_OPTIONS.md

**Location**: `hms_agents/hms_decompiler/knowledge/HMS_CLI_OPTIONS.md`

**Contains**:
- Complete CLI arguments discovered via decompilation
- `-script`, `-lite`, `-debug`, `-info`, `CommandServer`
- Version compatibility (which flags in which HMS versions)
- Usage examples

**Example**:
```
Q: "How do I run HMS without GUI?"
A: HEC-HMS.cmd -lite -script path/to/script.py
```

---

## Reference Classes

**Location**: `hms_agents/hms_decompiler/reference/`

### HMS 3.3
- `HMS_3.3/hms/Hms.java` - Entry point, CLI parsing
- `HMS_3.3/hms/model/JythonHms.java` - Scripting API (3.x)
- `HMS_3.3/hec/map/hms/*.java` - GIS support

### HMS 4.13
- `HMS_4.13/hms/Hms.java` - Entry point, CLI parsing
- `HMS_4.13/hms/model/JythonHms.java` - Scripting API (4.x)
- `HMS_4.13/hms/command/HmsCommandServerImpl.java` - RMI server

**Use**: Review implementation details for specific methods

---

## Tools

### CFR Decompiler

**Location**: `hms_agents/hms_decompiler/tools/cfr.jar`

**Usage**:
```batch
cd hms_agents/hms_decompiler/tools
java -jar cfr.jar "C:\Program Files\HEC\HEC-HMS\4.13\java\hms.jar" --classfilter "hms.model.ClassName" --outputdir output
```

**Options**:
- `--classfilter <pattern>` - Filter classes to decompile
- `--outputdir <dir>` - Output directory for decompiled classes

---

## Common Use Cases

### Use Case 1: Query JythonHms API

**Example**: Check if `SetTimeWindow()` exists

**Steps**:
1. Open `knowledge/JYTHON_HMS_API.md`
2. Search for "SetTimeWindow"
3. Result: ✅ Found

**See**: `examples/query_jython_api.md`

### Use Case 2: Check Version Compatibility

**Example**: Verify HMS 3.3 supports Jython

**Steps**:
1. Open `knowledge/HMS_3x_SUPPORT.md`
2. Review "Supported Versions"
3. Result: ✅ HMS 3.3+ supports Jython (Python 2 syntax required)

**See**: `examples/version_compatibility.md`

### Use Case 3: Decompile New Class

**Example**: Investigate how optimization works

**Steps**:
1. Check if already in agent reference/
2. If not, use tools/cfr.jar to decompile
3. Review decompiled source
4. Document findings if high-value

**See**: `examples/decompile_new_class.md`

---

## Integration with hms-commander

### How This Skill Supports Development

**HmsJython.py implementation**:
- Uses JythonHms API reference from JYTHON_HMS_API.md
- Implements python2_compatible flag based on HMS_3x_SUPPORT.md
- Method signatures validated against decompiled source

**HmsCmdr.py execution**:
- CLI options discovered from HMS_CLI_OPTIONS.md
- Version detection patterns from decompiled Hms.java
- Direct Java invocation (bypasses batch file bugs)

**Error handling**:
- Error codes from decompiled source
- Exception handling patterns from JythonHms.java

---

## On-Demand Decompilation

The agent provides tools for decompiling any HMS class as needed:

**Included**:
- CFR decompiler (tools/cfr.jar)
- Essential reference classes (reference/)
- Curated knowledge files (knowledge/)

**For New Classes**:
1. Use cfr.jar to decompile the class
2. Analyze the decompiled source
3. Add to agent reference/ if high-value
4. Document findings in knowledge/ if commonly needed

**This agent contains all necessary tools** for HMS internal investigation.

---

## Examples

### Example 1: query_jython_api.md
**Demonstrates**: Checking if JythonHms method exists and understanding parameters

**Workflow**:
1. Open JYTHON_HMS_API.md
2. Search for method
3. Review signature and parameters
4. Check hms-commander integration status

### Example 2: version_compatibility.md
**Demonstrates**: Understanding HMS 3.x vs 4.x differences

**Key findings**:
- HMS 3.x DOES support Jython (Python 2)
- API differences (Compute vs ComputeRun)
- Architecture (32-bit vs 64-bit)

### Example 3: decompile_new_class.md
**Demonstrates**: Complete workflow from question to decompilation to documentation

**Steps**:
1. Identify target class
2. Check if already decompiled
3. Decompile using tools
4. Analyze findings
5. Document in library

---

## Skill Workflow

### Standard Investigation Flow

```
User Question
    ↓
Check Agent Knowledge
    ├─ JYTHON_HMS_API.md → Found? → Answer
    ├─ HMS_3x_SUPPORT.md → Found? → Answer
    └─ HMS_CLI_OPTIONS.md → Found? → Answer
    ↓ (Not Found)
Check Library INDEX.md
    ├─ Class listed? → Read decompiled source → Answer
    └─ Not listed? → Decompile on-demand → Document → Answer
```

### Adding New Knowledge

```
Decompile Class (tools/cfr.jar)
    ↓
Analyze Source
    ↓
High-Value Finding?
    ├─ YES → Add to agent reference/
    └─ NO → Keep in local output/
    ↓
Update AGENT.md if commonly needed
    ↓
Document in knowledge/ if API-relevant
```

---

## Limitations

### What This Skill CAN Do
- ✅ Provide JythonHms API reference
- ✅ Show version differences (3.x vs 4.x)
- ✅ List CLI options
- ✅ Decompile any HMS class on-demand using included tools
- ✅ Explain HMS internal behavior

### What This Skill CANNOT Do
- ❌ Replace official HMS documentation (use hms_doc_query)
- ❌ Modify HMS source code
- ❌ Guarantee 100% decompilation accuracy
- ❌ Explain "why" design decisions were made (only "how" implementation works)

---

## Related Skills & Agents

### hms_doc_query Agent
**Purpose**: Search official HMS documentation

**Complementary use**:
- hms_doc_query → What's documented
- investigating-hms-internals → How it works internally

### update_3_to_4 Agent
**Purpose**: Migrate HMS projects from 3.x to 4.x

**Uses**: HMS_3x_SUPPORT.md for version differences

### managing-hms-versions Skill
**Purpose**: Detect and work with multiple HMS versions

**Uses**: Version detection patterns from decompilation

---

## Quality Checklist

Before answering user questions:

- [ ] Checked agent `knowledge/` files first
- [ ] If not found, checked agent `reference/` classes
- [ ] Decompiled on-demand using tools/cfr.jar if necessary
- [ ] Documented findings in agent if high-value
- [ ] Pointed to primary sources (not duplicated content)
- [ ] Clarified limitations of decompiled code

---

## Quick Reference

**Common questions → Files**:

| Question | File |
|----------|------|
| "What JythonHms methods exist?" | knowledge/JYTHON_HMS_API.md |
| "Does HMS 3.x support Jython?" | knowledge/HMS_3x_SUPPORT.md |
| "What CLI options are available?" | knowledge/HMS_CLI_OPTIONS.md |
| "How do I decompile a class?" | Use tools/cfr.jar directly |
| "What classes are available?" | reference/ directory + on-demand decompilation |

---

**Status**: Production skill
**Version**: 1.0
**Created**: 2025-12-12
**Agent**: hms_decompiler