--- name: create-mre description: > Create a Minimal Reproducible Example (MRE) from a third-party Fortran code failure in LFortran. Use this skill when third-party code fails to build or run with LFortran but works with other Fortran compilers (e.g. GFortran, Flang). Produces standalone .f90 file(s) and a run.sh script that reproduces the bug. Triggers: MRE, minimal reproducible example, reduce, reproduce, reproducer, third-party failure, compilation error, runtime failure, bug reduction, jupyterlite, browser lab, notebook cell. --- # Create MRE — Minimal Reproducible Example Reduce a third-party Fortran code failure into the smallest possible standalone example that reproduces the LFortran bug. The MRE must compile and run correctly with the reference compiler but fail with LFortran, exhibiting the same error as the original third-party code. ## Prerequisites Before starting, confirm you have: - A built `lfortran` — `build/src/bin/lfortran` for a standard in-tree build (see `AGENTS.md`). Put it first on `PATH`, or set `$LFORTRAN` to its path. - A **reference Fortran compiler** on `PATH`. `gfortran` is the project default — it is what `integration_tests` uses via the `gfortran` label, so prefer it. `flang` works too if that is what you have. - Access to the failing third-party code and the exact error message ## Inputs to Gather Ask the user for (if not already provided): 1. **The third-party project** — name, repo URL, or local path 2. **The exact error** — full error message or failure description from LFortran 3. **How to reproduce** — the build command, test command, or steps that trigger the failure 4. **Failure type** — compilation error, runtime crash, or wrong output 5. **The file(s) involved** — which source file(s) trigger the error If the input is a GitHub issue rather than a third-party project, run the `repro-issue` skill first — it produces an RE that this skill then reduces. If the failure was seen in the browser (the JupyterLite lab at ) or in a Jupyter notebook cell, read `doc/src/jupyterlite.md` first. It explains how to build and serve the lab locally, how to tell a genuine compiler bug from a stale service-worker/IndexedDB cache, and the three ways to reproduce a lab bug (C++ evaluator test, native xeus kernel, full WASM build). Its "Writing a test for a lab bug" section tells you whether the bug is interactive-mode specific: if the notebook cells rewritten as one ordinary program still fail, reduce it as a normal `.f90` MRE with the procedure below; if it only fails when split across cells, the reproducer is a `FortranEvaluator::evaluate2()` `TEST_CASE` in `src/lfortran/tests/test_llvm.cpp` instead of a `.f90` + `run.sh` pair — the reduction procedure below applies unchanged, with cells in place of the Fortran file. ## Procedure ### Phase 0: Read Project Guidelines Read `AGENTS.md` in the repository root for build commands and project conventions. Follow it, but this SKILL.md takes precedence where they conflict. ### Phase 1: Understand the Failure 1. Reproduce the original failure with LFortran to capture the exact error message and exit code. 2. Identify the **error category**: - **Compilation error**: parser failure, semantic error, codegen crash - **Runtime failure**: crash, wrong output, hang 3. Note the specific error text — the MRE must trigger this same error. ### Phase 2: Isolate the Failing Construct Use a **systematic isolation** approach first: 1. Read the error message carefully. Identify which Fortran construct is implicated (e.g. a specific intrinsic, derived type feature, array operation, module interaction, I/O statement). 2. Identify the minimal source file(s) that contain this construct. 3. If the failure involves modules, determine the minimum set of modules needed and their dependency order. If you are unable to reproduce the error this way, proceed to the next phase. ### Phase 3: Reduce via Binary Search Apply **binary-search reduction** to shrink the code: 1. Start with the isolated file(s) from Phase 2. If you failed to isolate in Phase 2, start with the whole third-party code. 2. Remove approximately half of the code that is NOT related to the failing construct (unused subroutines, unrelated variables, comments, etc.). 3. Test after each removal: - Does the reference compiler still compile/run it successfully? - Does `lfortran` still produce the **same error**? 4. If the error disappears, undo the last removal and try removing a smaller portion. 5. Repeat until no further code can be removed without losing the error. **Guard against false reduction.** A reduction step is only valid if the reference compiler still accepts the program. If you reduce until *both* compilers fail, you have most likely produced invalid Fortran rather than isolated an LFortran bug — back up to the last state where the reference compiler succeeded. ### Phase 4: Minimize and Clean Up 1. Remove all unused: - `use` statements and modules - Variables and parameters - Subroutines and functions - Arguments and dummy parameters 2. Simplify compiler options: - Remove as many lfortran options as possible, while still reproducing the error 3. Simplify remaining code: - Replace complex expressions with simple literals where possible - Reduce array sizes to the smallest that still triggers the bug - Shorten identifier names for clarity (but keep them meaningful) - Remove all comments, empty lines, etc. 4. If multiple files are needed (modules), minimize the number of files. Prefer a single file if possible. ### Phase 5: Verify the MRE Run the final verification: ```bash # Must succeed with the reference compiler gfortran -o test_ref .f90 && ./test_ref echo "reference exit code: $?" # Must fail with lfortran with the SAME error as the original lfortran .f90 echo "lfortran exit code: $?" ``` For **runtime failures**, both compilers must compile successfully, but the lfortran-compiled binary must produce wrong output or crash: ```bash # Both compile gfortran -o test_ref .f90 lfortran .f90 -o test_lfortran # reference binary works ./test_ref # lfortran binary fails ./test_lfortran ``` Confirm: - [ ] The reference compiler compiles and runs successfully - [ ] LFortran fails with the same (or closely related) error as the original - [ ] No code can be removed without losing the bug - [ ] All MRE files are in the repository root (`./`), not in any subdirectory ### Phase 6: Produce Output Files **IMPORTANT: All output files MUST be created directly in the repository root directory (`./`). Do NOT create a subdirectory (e.g. `mre_dir/`, `mre/`, `output/`) for MRE files. Every file — `.f90` files, `run.sh` — goes in `./`.** These are scratch artifacts, not deliverables. They are ignored via `.gitignore` (see the `# repro-issue / create-mre scratch artifacts` block) so they never end up in a fix PR. The deliverable is the integration test that `fix-mre` adds under `integration_tests/`. Do not `git add -f` the MRE files. #### 1. The MRE Fortran file(s) Create the `.f90` file(s) directly in the repository root (`./`). Name the file descriptively based on the bug, e.g.: - `./mre_derived_type_alloc.f90` - `./mre_intrinsic_reshape.f90` If multiple files are needed (e.g. module dependencies), name them with a common prefix and number them in compilation order: - `./mre_mod1.f90` (module) - `./mre_main.f90` (program) #### 2. `./run.sh` — Reproduction script Create an executable bash script **`./run.sh`** in the repository root directory (the same directory as `CMakeLists.txt`). Replace any previous `./run.sh` if it exists. Do NOT place it inside any subdirectory: ```bash #!/usr/bin/env bash set -e # MRE for: # Original failure in: # Error type: # # Expected: compiles and runs with the reference compiler # Actual: fails with lfortran — LFORTRAN="${LFORTRAN:-lfortran}" REF="${REF:-gfortran}" echo "=== Verifying MRE ===" echo "" echo "--- $REF (should succeed) ---" $REF -o test_ref ./test_ref echo "reference: OK" echo "" echo "--- lfortran (should fail) ---" echo "Expected error: " $LFORTRAN 2>&1 || true echo "" echo "Done. If lfortran showed the expected error above, the MRE is valid." # Cleanup rm -f test_ref test_lfortran a.out *.mod ``` Make it executable: ```bash chmod +x run.sh ``` For **runtime failures**, adjust `run.sh` to compile with both compilers and run both binaries, comparing output. ### Phase 7: Summary Print a summary for the user: ``` MRE created successfully! Files (all in repository root ./): ./run.sh Bug: Error type: Original project: To reproduce: ./run.sh The MRE compiles with the reference compiler but fails with lfortran. Next step: run the `fix-mre` skill to fix the bug and add an integration test. ``` ## Tips - **Module files**: If lfortran fails during module compilation, the MRE may need separate files compiled in order. Reflect this in `run.sh`. - **Compiler flags**: If the bug only manifests with certain flags (e.g. `--fast`), include those flags in `run.sh` and document them. - **Multiple errors**: If the third-party code has multiple LFortran failures, create one MRE per distinct bug. Don't combine unrelated issues — `AGENTS.md` requires one bug = one MRE = one PR. - **Fixed-form Fortran**: If the original code is fixed-form (`.f` or `.f77`), the MRE can use fixed-form too. Adjust file extensions accordingly. - **Large codebases**: For very large projects, start by identifying which translation unit fails, then reduce that single unit first. - **JupyterLite / notebook bugs**: See `doc/src/jupyterlite.md`. Before reducing, confirm the bug is real and not stale browser cache (retry in a private window). The command-line REPL is not a substitute for a notebook — it evaluates line by line, so a multi-line cell behaves differently. Keep the original cell split when reducing: that split is often the reproducer.