| 1 |
--- |
| 2 |
name: create-mre |
| 3 |
description: > |
| 4 |
Create a Minimal Reproducible Example (MRE) from a third-party Fortran code |
| 5 |
failure in LFortran. Use this skill when third-party code fails to build or |
| 6 |
run with LFortran but works with other Fortran compilers (e.g. GFortran, |
| 7 |
Flang). Produces standalone .f90 file(s) and a run.sh script that |
| 8 |
reproduces the bug. Triggers: MRE, minimal reproducible example, reduce, |
| 9 |
reproduce, reproducer, third-party failure, compilation error, runtime |
| 10 |
failure, bug reduction, jupyterlite, browser lab, notebook cell. |
| 11 |
--- |
| 12 |
|
| 13 |
# Create MRE — Minimal Reproducible Example |
| 14 |
|
| 15 |
Reduce a third-party Fortran code failure into the smallest possible standalone |
| 16 |
example that reproduces the LFortran bug. The MRE must compile and run correctly |
| 17 |
with the reference compiler but fail with LFortran, exhibiting the same error as |
| 18 |
the original third-party code. |
| 19 |
|
| 20 |
## Prerequisites |
| 21 |
|
| 22 |
Before starting, confirm you have: |
| 23 |
|
| 24 |
- A built `lfortran` — `build/src/bin/lfortran` for a standard in-tree build |
| 25 |
(see `AGENTS.md`). Put it first on `PATH`, or set `$LFORTRAN` to its path. |
| 26 |
- A **reference Fortran compiler** on `PATH`. `gfortran` is the project |
| 27 |
default — it is what `integration_tests` uses via the `gfortran` label, so |
| 28 |
prefer it. `flang` works too if that is what you have. |
| 29 |
- Access to the failing third-party code and the exact error message |
| 30 |
|
| 31 |
## Inputs to Gather |
| 32 |
|
| 33 |
Ask the user for (if not already provided): |
| 34 |
|
| 35 |
1. **The third-party project** — name, repo URL, or local path |
| 36 |
2. **The exact error** — full error message or failure description from LFortran |
| 37 |
3. **How to reproduce** — the build command, test command, or steps that trigger |
| 38 |
the failure |
| 39 |
4. **Failure type** — compilation error, runtime crash, or wrong output |
| 40 |
5. **The file(s) involved** — which source file(s) trigger the error |
| 41 |
|
| 42 |
If the input is a GitHub issue rather than a third-party project, run the |
| 43 |
`repro-issue` skill first — it produces an RE that this skill then reduces. |
| 44 |
|
| 45 |
If the failure was seen in the browser (the JupyterLite lab at |
| 46 |
<https://lfortran.github.io/lfortran/lab/index.html>) or in a Jupyter notebook |
| 47 |
cell, read `doc/src/jupyterlite.md` first. It explains how to build and serve |
| 48 |
the lab locally, how to tell a genuine compiler bug from a stale |
| 49 |
service-worker/IndexedDB cache, and the three ways to reproduce a lab bug |
| 50 |
(C++ evaluator test, native xeus kernel, full WASM build). Its "Writing a test |
| 51 |
for a lab bug" section tells you whether the bug is interactive-mode specific: |
| 52 |
if the notebook cells rewritten as one ordinary program still fail, reduce it |
| 53 |
as a normal `.f90` MRE with the procedure below; if it only fails when split |
| 54 |
across cells, the reproducer is a `FortranEvaluator::evaluate2()` `TEST_CASE` |
| 55 |
in `src/lfortran/tests/test_llvm.cpp` instead of a `.f90` + `run.sh` pair — |
| 56 |
the reduction procedure below applies unchanged, with cells in place of the |
| 57 |
Fortran file. |
| 58 |
|
| 59 |
## Procedure |
| 60 |
|
| 61 |
### Phase 0: Read Project Guidelines |
| 62 |
|
| 63 |
Read `AGENTS.md` in the repository root for build commands and project |
| 64 |
conventions. Follow it, but this SKILL.md takes precedence where they conflict. |
| 65 |
|
| 66 |
### Phase 1: Understand the Failure |
| 67 |
|
| 68 |
1. Reproduce the original failure with LFortran to capture the exact error |
| 69 |
message and exit code. |
| 70 |
2. Identify the **error category**: |
| 71 |
- **Compilation error**: parser failure, semantic error, codegen crash |
| 72 |
- **Runtime failure**: crash, wrong output, hang |
| 73 |
3. Note the specific error text — the MRE must trigger this same error. |
| 74 |
|
| 75 |
### Phase 2: Isolate the Failing Construct |
| 76 |
|
| 77 |
Use a **systematic isolation** approach first: |
| 78 |
|
| 79 |
1. Read the error message carefully. Identify which Fortran construct is |
| 80 |
implicated (e.g. a specific intrinsic, derived type feature, array |
| 81 |
operation, module interaction, I/O statement). |
| 82 |
2. Identify the minimal source file(s) that contain this construct. |
| 83 |
3. If the failure involves modules, determine the minimum set of modules |
| 84 |
needed and their dependency order. |
| 85 |
|
| 86 |
If you are unable to reproduce the error this way, proceed to the next phase. |
| 87 |
|
| 88 |
### Phase 3: Reduce via Binary Search |
| 89 |
|
| 90 |
Apply **binary-search reduction** to shrink the code: |
| 91 |
|
| 92 |
1. Start with the isolated file(s) from Phase 2. If you failed to isolate in |
| 93 |
Phase 2, start with the whole third-party code. |
| 94 |
2. Remove approximately half of the code that is NOT related to the failing |
| 95 |
construct (unused subroutines, unrelated variables, comments, etc.). |
| 96 |
3. Test after each removal: |
| 97 |
- Does the reference compiler still compile/run it successfully? |
| 98 |
- Does `lfortran` still produce the **same error**? |
| 99 |
4. If the error disappears, undo the last removal and try removing a smaller |
| 100 |
portion. |
| 101 |
5. Repeat until no further code can be removed without losing the error. |
| 102 |
|
| 103 |
**Guard against false reduction.** A reduction step is only valid if the |
| 104 |
reference compiler still accepts the program. If you reduce until *both* |
| 105 |
compilers fail, you have most likely produced invalid Fortran rather than |
| 106 |
isolated an LFortran bug — back up to the last state where the reference |
| 107 |
compiler succeeded. |
| 108 |
|
| 109 |
### Phase 4: Minimize and Clean Up |
| 110 |
|
| 111 |
1. Remove all unused: |
| 112 |
- `use` statements and modules |
| 113 |
- Variables and parameters |
| 114 |
- Subroutines and functions |
| 115 |
- Arguments and dummy parameters |
| 116 |
2. Simplify compiler options: |
| 117 |
- Remove as many lfortran options as possible, while still reproducing the |
| 118 |
error |
| 119 |
3. Simplify remaining code: |
| 120 |
- Replace complex expressions with simple literals where possible |
| 121 |
- Reduce array sizes to the smallest that still triggers the bug |
| 122 |
- Shorten identifier names for clarity (but keep them meaningful) |
| 123 |
- Remove all comments, empty lines, etc. |
| 124 |
4. If multiple files are needed (modules), minimize the number of files. |
| 125 |
Prefer a single file if possible. |
| 126 |
|
| 127 |
### Phase 5: Verify the MRE |
| 128 |
|
| 129 |
Run the final verification: |
| 130 |
|
| 131 |
```bash |
| 132 |
# Must succeed with the reference compiler |
| 133 |
gfortran -o test_ref <mre_file>.f90 && ./test_ref |
| 134 |
echo "reference exit code: $?" |
| 135 |
|
| 136 |
# Must fail with lfortran with the SAME error as the original |
| 137 |
lfortran <mre_file>.f90 |
| 138 |
echo "lfortran exit code: $?" |
| 139 |
``` |
| 140 |
|
| 141 |
For **runtime failures**, both compilers must compile successfully, but the |
| 142 |
lfortran-compiled binary must produce wrong output or crash: |
| 143 |
|
| 144 |
```bash |
| 145 |
# Both compile |
| 146 |
gfortran -o test_ref <mre_file>.f90 |
| 147 |
lfortran <mre_file>.f90 -o test_lfortran |
| 148 |
|
| 149 |
# reference binary works |
| 150 |
./test_ref |
| 151 |
|
| 152 |
# lfortran binary fails |
| 153 |
./test_lfortran |
| 154 |
``` |
| 155 |
|
| 156 |
Confirm: |
| 157 |
- [ ] The reference compiler compiles and runs successfully |
| 158 |
- [ ] LFortran fails with the same (or closely related) error as the original |
| 159 |
- [ ] No code can be removed without losing the bug |
| 160 |
- [ ] All MRE files are in the repository root (`./`), not in any subdirectory |
| 161 |
|
| 162 |
### Phase 6: Produce Output Files |
| 163 |
|
| 164 |
**IMPORTANT: All output files MUST be created directly in the repository root |
| 165 |
directory (`./`). Do NOT create a subdirectory (e.g. `mre_dir/`, `mre/`, |
| 166 |
`output/`) for MRE files. Every file — `.f90` files, `run.sh` — goes in `./`.** |
| 167 |
|
| 168 |
These are scratch artifacts, not deliverables. They are ignored via |
| 169 |
`.gitignore` (see the `# repro-issue / create-mre scratch artifacts` block) so |
| 170 |
they never end up in a fix PR. The deliverable is the integration test that |
| 171 |
`fix-mre` adds under `integration_tests/`. Do not `git add -f` the MRE files. |
| 172 |
|
| 173 |
#### 1. The MRE Fortran file(s) |
| 174 |
|
| 175 |
Create the `.f90` file(s) directly in the repository root (`./`). |
| 176 |
Name the file descriptively based on the bug, e.g.: |
| 177 |
- `./mre_derived_type_alloc.f90` |
| 178 |
- `./mre_intrinsic_reshape.f90` |
| 179 |
|
| 180 |
If multiple files are needed (e.g. module dependencies), name them with a |
| 181 |
common prefix and number them in compilation order: |
| 182 |
- `./mre_mod1.f90` (module) |
| 183 |
- `./mre_main.f90` (program) |
| 184 |
|
| 185 |
#### 2. `./run.sh` — Reproduction script |
| 186 |
|
| 187 |
Create an executable bash script **`./run.sh`** in the repository root |
| 188 |
directory (the same directory as `CMakeLists.txt`). Replace any previous |
| 189 |
`./run.sh` if it exists. Do NOT place it inside any subdirectory: |
| 190 |
|
| 191 |
```bash |
| 192 |
#!/usr/bin/env bash |
| 193 |
set -e |
| 194 |
|
| 195 |
# MRE for: <brief description of the bug> |
| 196 |
# Original failure in: <third-party project name> |
| 197 |
# Error type: <compilation error | runtime failure | wrong output> |
| 198 |
# |
| 199 |
# Expected: compiles and runs with the reference compiler |
| 200 |
# Actual: fails with lfortran — <brief error description> |
| 201 |
|
| 202 |
LFORTRAN="${LFORTRAN:-lfortran}" |
| 203 |
REF="${REF:-gfortran}" |
| 204 |
|
| 205 |
echo "=== Verifying MRE ===" |
| 206 |
|
| 207 |
echo "" |
| 208 |
echo "--- $REF (should succeed) ---" |
| 209 |
$REF -o test_ref <file(s)> |
| 210 |
./test_ref |
| 211 |
echo "reference: OK" |
| 212 |
|
| 213 |
echo "" |
| 214 |
echo "--- lfortran (should fail) ---" |
| 215 |
echo "Expected error: <paste key part of the error message>" |
| 216 |
$LFORTRAN <file(s)> 2>&1 || true |
| 217 |
echo "" |
| 218 |
echo "Done. If lfortran showed the expected error above, the MRE is valid." |
| 219 |
|
| 220 |
# Cleanup |
| 221 |
rm -f test_ref test_lfortran a.out *.mod |
| 222 |
``` |
| 223 |
|
| 224 |
Make it executable: |
| 225 |
```bash |
| 226 |
chmod +x run.sh |
| 227 |
``` |
| 228 |
|
| 229 |
For **runtime failures**, adjust `run.sh` to compile with both compilers and |
| 230 |
run both binaries, comparing output. |
| 231 |
|
| 232 |
### Phase 7: Summary |
| 233 |
|
| 234 |
Print a summary for the user: |
| 235 |
|
| 236 |
``` |
| 237 |
MRE created successfully! |
| 238 |
|
| 239 |
Files (all in repository root ./): |
| 240 |
<list of .f90 files> |
| 241 |
./run.sh |
| 242 |
|
| 243 |
Bug: <one-line description> |
| 244 |
Error type: <compilation | runtime | wrong output> |
| 245 |
Original project: <name> |
| 246 |
|
| 247 |
To reproduce: |
| 248 |
./run.sh |
| 249 |
|
| 250 |
The MRE compiles with the reference compiler but fails with lfortran. |
| 251 |
|
| 252 |
Next step: run the `fix-mre` skill to fix the bug and add an integration test. |
| 253 |
``` |
| 254 |
|
| 255 |
## Tips |
| 256 |
|
| 257 |
- **Module files**: If lfortran fails during module compilation, the MRE may |
| 258 |
need separate files compiled in order. Reflect this in `run.sh`. |
| 259 |
- **Compiler flags**: If the bug only manifests with certain flags (e.g. |
| 260 |
`--fast`), include those flags in `run.sh` and document them. |
| 261 |
- **Multiple errors**: If the third-party code has multiple LFortran failures, |
| 262 |
create one MRE per distinct bug. Don't combine unrelated issues — `AGENTS.md` |
| 263 |
requires one bug = one MRE = one PR. |
| 264 |
- **Fixed-form Fortran**: If the original code is fixed-form (`.f` or `.f77`), |
| 265 |
the MRE can use fixed-form too. Adjust file extensions accordingly. |
| 266 |
- **Large codebases**: For very large projects, start by identifying which |
| 267 |
translation unit fails, then reduce that single unit first. |
| 268 |
- **JupyterLite / notebook bugs**: See `doc/src/jupyterlite.md`. Before |
| 269 |
reducing, confirm the bug is real and not stale browser cache (retry in a |
| 270 |
private window). The command-line REPL is not a substitute for a notebook — |
| 271 |
it evaluates line by line, so a multi-line cell behaves differently. Keep the |
| 272 |
original cell split when reducing: that split is often the reproducer. |