Debian Codegraph @

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

raw
1 ---
2 name: fix-mre
3 description: >
4 Fix an LFortran bug given an MRE (Minimal Reproducible Example) produced by
5 the create-mre skill. Reproduces the bug, diagnoses which compiler phase is
6 at fault, fixes it in the LFortran source, adds an integration test, and
7 runs the integration and reference test suites. Triggers: fix MRE, fix bug,
8 fix lfortran, fix reproducer, implement, resolve, patch, bugfix.
9 ---
10
11 # Fix MRE — Fix an LFortran Bug from a Minimal Reproducible Example
12
13 Given an MRE (produced by the `create-mre` skill or written by hand), reproduce
14 the LFortran bug, fix it in the compiler source, add an integration test, and
15 verify the full suites still pass.
16
17 ## Prerequisites
18
19 - The LFortran repository is the current working directory.
20 - A configured build directory. `AGENTS.md` documents the standard dev config:
21 ```bash
22 cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Debug -DWITH_LLVM=ON \
23 -DWITH_STACKTRACE=yes
24 ```
25 `./build1.sh` does this for you.
26 - `build/src/bin` first on `PATH`, so `lfortran` resolves to the in-tree build
27 you are about to modify. Verify with `which lfortran` before starting —
28 testing against a stale system `lfortran` wastes an entire debug cycle.
29 - A **reference Fortran compiler** on `PATH` (`gfortran` preferred; it is what
30 the `gfortran` integration-test label uses).
31
32 ## Inputs to Gather
33
34 Ask the user for (if not already provided):
35
36 1. **The MRE** — the `.f90` file(s) and `run.sh` that reproduce the bug. By the
37 `create-mre` convention these are in the repository root.
38
39 ## Procedure
40
41 ### Phase 0: Read Project Guidelines
42
43 Read `AGENTS.md` in the LFortran repository root to understand project
44 conventions, coding style, testing practices, and contribution guidelines.
45 Note especially the architecture rules — they determine where a fix belongs:
46
47 - Type coercion and casting belong in AST→ASR (semantics). The LLVM/codegen
48 backend must never infer or fix types; it only lowers what ASR gives it.
49 **If codegen appears to need a type workaround, the bug is upstream** — fix
50 it in semantics instead.
51 - `libasr` is frontend-independent. Never reference `_lfortran` or other
52 frontend-specific names there.
53 - No new C/C++ macros; use `constexpr`, templates, or inline functions.
54
55 Follow all instructions therein, but the instructions in this SKILL.md file
56 take precedence where they conflict.
57
58 ### Phase 1: Reproduce the Bug
59
60 1. Read `run.sh` to understand the bug.
61 2. Run it to confirm the failure:
62 ```bash
63 bash run.sh
64 ```
65 3. Note the **exact error message**, **error type** (compilation error, runtime
66 crash, wrong output), and the **Fortran construct** involved.
67
68 Do not proceed until you have reproduced the failure locally. A fix for a bug
69 you have not observed is a guess.
70
71 ### Phase 2: Diagnose the Root Cause
72
73 1. Analyze the error message to determine which compiler phase is failing:
74 - **Parser** (`src/lfortran/parser/`): syntax errors, tokenizer failures
75 - **Semantics** (`src/lfortran/semantics/`): type errors, symbol resolution
76 - **ASR passes** (`src/libasr/pass/`): transformation errors
77 - **Code generation** (`src/libasr/codegen/`): LLVM IR generation failures
78 2. Search the LFortran source for the error message text or error label to find
79 the code that produces it:
80 ```bash
81 grep -rn "error text" src/
82 ```
83 3. Inspect the intermediate representations to see where the tree first goes
84 wrong — this is usually faster than reading code:
85 ```bash
86 lfortran --show-ast <mre_file>.f90
87 lfortran --show-asr <mre_file>.f90
88 ```
89 4. Understand the code path that leads to the failure. Read surrounding code to
90 understand the intended behavior.
91 5. Identify the minimal fix needed. Fix the root cause, not the symptom.
92
93 ### Phase 3: Implement the Fix
94
95 1. Make the code change in the LFortran source. Keep changes minimal and
96 focused on the bug. Match the formatting of the file you are editing;
97 do not reformat surrounding code.
98 2. Rebuild:
99 ```bash
100 cmake --build build -j
101 ```
102 3. Re-run the MRE to verify the fix:
103 ```bash
104 bash run.sh
105 ```
106 4. The MRE should now succeed (compile and/or run correctly) with `lfortran`.
107
108 If the fix doesn't work, iterate: re-diagnose, adjust, rebuild, and re-test.
109
110 ### Phase 4: Add an Integration Test
111
112 The integration test — not the MRE — is the deliverable of this skill. The MRE
113 files stay untracked; the test is what gets committed.
114
115 1. Look at existing integration tests in `integration_tests/` to find similar
116 tests (same Fortran construct, similar naming pattern).
117 2. Create a new `.f90` file in `integration_tests/` following the naming
118 convention (e.g. `intrinsic_name_NN.f90`, `derived_type_feature_NN.f90`).
119 Pick the next available number.
120 3. The test should be based on the MRE but written as a proper integration test:
121 - Include runtime checks using `if (result /= expected) error stop` idioms.
122 - Keep it minimal but cover the bug scenario.
123 4. Register the test in `integration_tests/CMakeLists.txt`:
124 - Find the appropriate section (search for `macro(RUN` and existing
125 `RUN(NAME ...)` entries).
126 - Add a `RUN(NAME <test_name> LABELS gfortran llvm)` style entry.
127 - Use at least the labels `gfortran` and `llvm`. An unregistered test is
128 dead code.
129 5. Verify the test compiles with the reference compiler — this confirms the
130 test is valid Fortran and does not depend on LFortran-specific behavior:
131 ```bash
132 gfortran -o /tmp/test_ref integration_tests/<test_name>.f90 && /tmp/test_ref
133 rm -f /tmp/test_ref
134 ```
135 6. Verify the test compiles and runs with `lfortran`:
136 ```bash
137 cd integration_tests
138 ./run_tests.py -t <test_name>
139 ```
140
141 **Confirm the test actually captures the bug.** `AGENTS.md` requires that every
142 fix PR demonstrate the test fails on `main` and passes on the branch. Verify
143 this explicitly — `git stash` your source change, rebuild, confirm the new test
144 fails, then restore and rebuild. If the test passes without your fix, it does
145 not cover the bug and the fix is not understood well enough.
146
147 ### Phase 5: Run Integration Tests
148
149 Run the full integration test suite:
150
151 ```bash
152 cd integration_tests
153 ./run_tests.py -j16 &> log
154 tail -n30 log
155 ```
156
157 **Always redirect test output to a log file and then examine it.** Do not pipe
158 to `tail` directly — if you need more output than `tail` shows you have to
159 rerun the whole suite, which takes several minutes.
160
161 - If all tests pass, proceed to Phase 6.
162 - If any test fails:
163 1. Examine the log to identify which test failed and why.
164 2. Determine if the failure is caused by your change (a regression) or a
165 pre-existing issue.
166 3. If your change caused it, fix the regression, rebuild, and re-run tests.
167 4. Repeat until all integration tests pass.
168
169 ### Phase 6: Run Reference Tests
170
171 Return to the LFortran root and run reference tests:
172
173 ```bash
174 cd <lfortran-root>
175 ./run_tests.py &> log
176 ```
177
178 - If reference tests pass, proceed to Phase 7.
179 - If reference tests fail (expected when your fix changes compiler output):
180 1. Update reference results:
181 ```bash
182 ./run_tests.py -u
183 ```
184 2. Review the changes with `git diff` to ensure all reference updates are
185 correct and expected — they should all be consequences of your bug fix,
186 not regressions.
187 3. If any reference change looks wrong, investigate and fix before proceeding.
188
189 Never run `-u` blindly. An unreviewed reference update can silently bake a
190 regression into the expected output.
191
192 ### Phase 7: Report
193
194 Summarize the work and let the user decide whether to commit. Do not commit or
195 push without being asked — `AGENTS.md` requires PRs to go to a fork, never
196 upstream, and the user may want to review the diff first.
197
198 Before staging anything, confirm the MRE scratch files (`mre_*.f90`,
199 `re_*.f90`, `run.sh`, `run_re.sh`) are not included — they are ignored by
200 `.gitignore` and are not part of the fix.
201
202 Print a summary:
203
204 ```
205 Bug fixed!
206
207 Fix: <one-line description of what was changed>
208 Files modified:
209 <list of changed source files>
210 Integration test: integration_tests/<test_name>.f90
211 fails on main, passes on this branch — verified
212
213 Integration tests: pass
214 Reference tests: pass (<N> reference outputs updated, reviewed)
215
216 Not committed. Review the diff, then commit when ready.
217 ```
218
219 If the user asks you to commit, follow the `AGENTS.md` commit conventions:
220 small single-topic commits, imperative mood, one bug = one MRE = one PR, and
221 never mix refactoring or formatting with a bug fix.
222
223 ## Tips
224
225 - **Multiple errors**: The MRE may expose more than one bug. First fix the bug
226 that the MRE demonstrates. If you discover additional issues that block
227 compiling and running the newly added test, fix them as well — but keep
228 unrelated fixes to separate PRs.
229 - **ASR passes**: Many bugs live in ASR passes (`src/libasr/pass/`). These
230 transform the ASR tree and are a common source of codegen failures.
231 - **Semantic errors**: If the bug is "not yet implemented", the fix likely
232 involves adding a new case in the semantics or codegen visitor.
233 - **Error message style**: Per `AGENTS.md`, messages are lowercase, show
234 explicit kinds (e.g. `integer(4)` vs `integer(8)`), and never expose
235 internal ASR node names to users.
236 - **Modfile issues**: If you see "Incompatible format: LFortran Modfile...",
237 the module files are stale — rebuild from scratch (`ninja -C build clean &&
238 cmake --build build -j`) and ensure `build/src/bin` is first on `PATH`.
239 - **Rebuild quickly**: `cmake --build build -j` only recompiles changed files.
240 Use it frequently during iteration.
241 - **Test naming**: Look at nearby tests in `CMakeLists.txt` for naming
242 conventions. Usually it's `<feature>_<number>`.