Debian Codegraph @

.claude/skills/create-mre/SKILL.md

raw
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.