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