magnus919_agent-skills/fpga-development/templates/rtl-contract.md

# RTL module contract and review

## Intent

- Module and purpose:
- Invariants:
- Clock/reset ownership:
- Input legal domain and illegal-input behavior:

## Interface

| Signal | Width/signedness | Clock domain | Meaning | Stability/handshake |
|---|---|---|---|---|
| | | | | |

- Latency:
- Throughput:
- Backpressure / loss policy:
- Overflow, saturation, rounding, and truncation policy:
- Fixed-point format, binary point, intermediate ranges, explicit casts:

## Synthesis hypothesis

- Expected LUT/FF/BRAM/DSP/PLL resources:
- Expected inferred structure:
- Simulation-only constructs excluded:
- Vendor-specific constructs and portability boundary:
- Parameter legality checks:

## Evidence and disposition

- Lint command/version/result:
- Elaboration command/version/result:
- Synthesis warnings and disposition:
- Resource report:
- Changes required before simulation or implementation:

## Review instructions

For each arithmetic expression record operand widths before evaluation, result width, cast point, rounding, and overflow policy. For each process record sensitivity/clock, reset behavior, assignment style, and driver owner. Compare the hypothesis with elaboration and synthesis reports. Treat a changed latency or inferred memory shape as an interface change.

## Example decision

`HOLD`: synthesis infers a latch for `data_valid`, while the contract requires a one-cycle registered pulse. Add complete combinational assignments or redesign the register boundary, then rerun lint and synthesis.