| 1 |
--- |
| 2 |
name: repro-issue |
| 3 |
description: > |
| 4 |
Create a Reproducible Example (RE) from a GitHub issue filed against |
| 5 |
lfortran/lfortran. Fetches the issue, extracts the Fortran code as-posted, |
| 6 |
minimally extends it if necessary so it can be compiled and run, and produces |
| 7 |
a standalone .f90 file (or files) plus a run_re.sh script that reproduces |
| 8 |
the bug with `lfortran` and shows that the same program compiles/runs with |
| 9 |
a reference compiler. The output is intentionally as close to the issue's |
| 10 |
original code as possible — reduction/minimization is the job of the |
| 11 |
create-mre skill, which consumes this skill's output. Triggers: repro issue, |
| 12 |
reproduce issue, RE, reproducible example, github issue, lfortran issue, |
| 13 |
issue reproducer. |
| 14 |
--- |
| 15 |
|
| 16 |
# Repro Issue — Reproducible Example from a GitHub Issue |
| 17 |
|
| 18 |
Turn a GitHub issue filed at `lfortran/lfortran` into a local **Reproducible |
| 19 |
Example (RE)**. The RE is a standalone Fortran program that: |
| 20 |
|
| 21 |
1. Uses the code from the issue **as closely as possible** — ideally |
| 22 |
byte-for-byte identical — with only the smallest additions needed to make it |
| 23 |
compile/run. |
| 24 |
2. **Fails** when compiled/run with `lfortran` (matching the error reported in |
| 25 |
the issue). |
| 26 |
3. **Succeeds** when compiled/run with the reference compiler (confirming the |
| 27 |
issue is an LFortran bug, not invalid Fortran). |
| 28 |
|
| 29 |
An RE is **not** a minimized MRE. Do not shrink, rename, or rewrite the issue's |
| 30 |
code. The downstream `create-mre` skill will consume this RE and reduce it. |
| 31 |
The downstream `fix-mre` skill will then fix the bug using the MRE. |
| 32 |
|
| 33 |
Pipeline: **repro-issue → create-mre → fix-mre** |
| 34 |
|
| 35 |
## Prerequisites |
| 36 |
|
| 37 |
Before starting, confirm you have: |
| 38 |
|
| 39 |
- A built `lfortran` — `build/src/bin/lfortran` for a standard in-tree build |
| 40 |
(see `AGENTS.md`). Put it first on `PATH`, or set `$LFORTRAN` to its path. |
| 41 |
- A **reference Fortran compiler** on `PATH`. `gfortran` is the project |
| 42 |
default — it is what `integration_tests` uses via the `gfortran` label, so |
| 43 |
prefer it. `flang` works too if that is what you have. |
| 44 |
- `gh` CLI available on `PATH` and authenticated (`gh auth status`) |
| 45 |
- Working directory is the lfortran repository root (same dir as |
| 46 |
`CMakeLists.txt`) — output files go here |
| 47 |
|
| 48 |
## Inputs to Gather |
| 49 |
|
| 50 |
Ask the user for (if not already provided): |
| 51 |
|
| 52 |
1. **The issue** — a GitHub issue number (e.g. `1234`) or URL |
| 53 |
(e.g. `https://github.com/lfortran/lfortran/issues/1234`). Default repo |
| 54 |
is `lfortran/lfortran`. |
| 55 |
|
| 56 |
## Procedure |
| 57 |
|
| 58 |
### Phase 0: Read Project Guidelines |
| 59 |
|
| 60 |
Read `AGENTS.md` in the repository root. It is the single point of reference |
| 61 |
for build commands, test layout, and contribution rules. Follow it, but the |
| 62 |
instructions in this SKILL.md take precedence where they conflict. |
| 63 |
|
| 64 |
### Phase 1: Fetch the Issue |
| 65 |
|
| 66 |
Use the `gh` CLI to fetch the issue body and title: |
| 67 |
|
| 68 |
```bash |
| 69 |
gh issue view <N> --repo lfortran/lfortran --json number,title,body,labels,url |
| 70 |
``` |
| 71 |
|
| 72 |
Also fetch comments if the body alone is insufficient: |
| 73 |
|
| 74 |
```bash |
| 75 |
gh issue view <N> --repo lfortran/lfortran --comments |
| 76 |
``` |
| 77 |
|
| 78 |
Extract: |
| 79 |
|
| 80 |
- **Title** (used in the RE header comment) |
| 81 |
- **URL** (used in the RE header comment) |
| 82 |
- **Fortran code blocks** from the body (and comments, if body is incomplete) |
| 83 |
- **Reported error / expected vs actual behavior** |
| 84 |
- **Any reproduction command** the reporter used (e.g. specific `lfortran` |
| 85 |
flags). Record these verbatim — they must be preserved in `run_re.sh`. |
| 86 |
|
| 87 |
### Phase 2: Extract the Code As-Posted |
| 88 |
|
| 89 |
1. Copy the Fortran code out of the issue **verbatim**. Do not: |
| 90 |
- Rename identifiers |
| 91 |
- Reformat, reindent, or reflow the code |
| 92 |
- Remove comments or unused declarations |
| 93 |
- "Fix" anything in the user's code |
| 94 |
2. If the issue contains multiple code blocks (e.g. a module plus a program), |
| 95 |
preserve each as its own file when they are clearly separate compilation |
| 96 |
units. Otherwise concatenate in the order they appear. |
| 97 |
3. If the issue links to a gist, pastebin, or external repo file, fetch that |
| 98 |
content and treat it as the code block. |
| 99 |
|
| 100 |
### Phase 3: Minimal Extension (Only If Required) |
| 101 |
|
| 102 |
The goal is that the RE compiles/runs end-to-end. If — and only if — the code |
| 103 |
as-posted cannot compile or run on its own, add the **smallest possible** |
| 104 |
wrapper around it. Permitted additions, in order of preference: |
| 105 |
|
| 106 |
1. Wrap free-standing statements in `program repro ... end program` if no |
| 107 |
program unit is present. |
| 108 |
2. Add `implicit none` only if the original code already relies on it |
| 109 |
implicitly; otherwise leave implicit typing as the user wrote it. |
| 110 |
3. Add `use <module>` lines only if the issue clearly depends on them. |
| 111 |
4. Provide trivially obvious sample inputs (e.g. initialize an integer used |
| 112 |
uninitialized) only when needed to reach the failing construct. |
| 113 |
|
| 114 |
Every addition you make must be marked with a comment: |
| 115 |
|
| 116 |
```fortran |
| 117 |
! [RE-ADDED] wrapper program so the snippet can be compiled standalone |
| 118 |
``` |
| 119 |
|
| 120 |
If the issue cannot be reasonably reproduced without substantial invention |
| 121 |
(e.g. it depends on a third-party library, or the code is a tiny fragment |
| 122 |
with no clear surrounding context), **stop and report this to the user** |
| 123 |
rather than guessing. |
| 124 |
|
| 125 |
### Phase 4: Verify the RE |
| 126 |
|
| 127 |
Run both compilers and confirm the RE fails with LFortran and passes with the |
| 128 |
reference compiler. |
| 129 |
|
| 130 |
For a **compilation error** reported in the issue: |
| 131 |
|
| 132 |
```bash |
| 133 |
# Must succeed with the reference compiler |
| 134 |
gfortran -o test_ref <re_file>.f90 && ./test_ref |
| 135 |
echo "reference exit code: $?" |
| 136 |
|
| 137 |
# Must fail with lfortran — ideally with the same error message as the issue |
| 138 |
lfortran <re_file>.f90 |
| 139 |
echo "lfortran exit code: $?" |
| 140 |
``` |
| 141 |
|
| 142 |
For a **runtime failure** reported in the issue: |
| 143 |
|
| 144 |
```bash |
| 145 |
gfortran -o test_ref <re_file>.f90 |
| 146 |
lfortran <re_file>.f90 -o test_lfortran |
| 147 |
|
| 148 |
./test_ref # must succeed / produce expected output |
| 149 |
./test_lfortran # must crash or produce wrong output |
| 150 |
``` |
| 151 |
|
| 152 |
Confirm: |
| 153 |
|
| 154 |
- [ ] The reference compiler compiles and runs successfully |
| 155 |
- [ ] LFortran fails with (or very close to) the error reported in the issue |
| 156 |
- [ ] The code in the RE file(s) matches the issue's code as closely as possible |
| 157 |
- [ ] Any additions are clearly marked with `! [RE-ADDED]` comments |
| 158 |
- [ ] All RE files live in the repository root (`./`), not in any subdirectory |
| 159 |
|
| 160 |
If lfortran's error does **not** match the issue's error, investigate: |
| 161 |
|
| 162 |
- Is the compiler rebuilt on the relevant branch? |
| 163 |
- Are you missing a flag the reporter used? |
| 164 |
- Did the bug get fixed already (close the loop with the user before continuing)? |
| 165 |
|
| 166 |
### Phase 5: Produce Output Files |
| 167 |
|
| 168 |
**IMPORTANT: All output files MUST be created directly in the repository root |
| 169 |
directory (`./`). Do NOT create a subdirectory. Every file — `.f90` files, |
| 170 |
`run_re.sh` — goes in `./`.** This is the same convention `create-mre` uses, |
| 171 |
so the next stage in the pipeline can pick them up without any path wiring. |
| 172 |
|
| 173 |
These are scratch artifacts, not deliverables. They are ignored via |
| 174 |
`.gitignore` (see the `# repro-issue / create-mre scratch artifacts` block) so |
| 175 |
they never end up in a fix PR. Do not `git add -f` them. |
| 176 |
|
| 177 |
#### 1. The RE Fortran file(s) |
| 178 |
|
| 179 |
Name files with an `re_` prefix and a short descriptor derived from the issue |
| 180 |
(include the issue number to keep things traceable), for example: |
| 181 |
|
| 182 |
- `./re_issue_1234.f90` |
| 183 |
- `./re_issue_1234_mod.f90` + `./re_issue_1234_main.f90` (if multiple units) |
| 184 |
|
| 185 |
#### 2. `./run_re.sh` — Reproduction script |
| 186 |
|
| 187 |
Create an executable bash script **`./run_re.sh`** in the repository root |
| 188 |
directory. Replace any previous `./run_re.sh` if it exists. Do NOT place it |
| 189 |
inside any subdirectory. Template: |
| 190 |
|
| 191 |
```bash |
| 192 |
#!/usr/bin/env bash |
| 193 |
set -e |
| 194 |
|
| 195 |
# RE for: <issue title> |
| 196 |
# Issue: <issue URL> |
| 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 from the issue> |
| 201 |
|
| 202 |
LFORTRAN="${LFORTRAN:-lfortran}" |
| 203 |
REF="${REF:-gfortran}" |
| 204 |
|
| 205 |
echo "=== Verifying RE for issue <N> ===" |
| 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 from the issue>" |
| 216 |
$LFORTRAN <lfortran-flags-from-issue> <file(s)> 2>&1 || true |
| 217 |
echo "" |
| 218 |
echo "Done. If lfortran showed the expected error above, the RE is valid." |
| 219 |
|
| 220 |
# Cleanup |
| 221 |
rm -f test_ref test_lfortran a.out *.mod |
| 222 |
``` |
| 223 |
|
| 224 |
Make it executable: |
| 225 |
|
| 226 |
```bash |
| 227 |
chmod +x run_re.sh |
| 228 |
``` |
| 229 |
|
| 230 |
For **runtime failures**, adjust `run_re.sh` to compile with both compilers |
| 231 |
and run both binaries, comparing output. |
| 232 |
|
| 233 |
Preserve any `lfortran` flags mentioned in the issue verbatim (e.g. |
| 234 |
`--fast`, `--realloc-lhs`, backend selection). The RE must reproduce under |
| 235 |
the exact invocation the reporter used. |
| 236 |
|
| 237 |
### Phase 6: Summary |
| 238 |
|
| 239 |
Print a summary for the user: |
| 240 |
|
| 241 |
``` |
| 242 |
RE created successfully! |
| 243 |
|
| 244 |
Files (all in repository root ./): |
| 245 |
<list of re_*.f90 files> |
| 246 |
./run_re.sh |
| 247 |
|
| 248 |
Issue: #<N> — <title> |
| 249 |
URL: <issue URL> |
| 250 |
Error type: <compilation | runtime | wrong output> |
| 251 |
|
| 252 |
To reproduce: |
| 253 |
./run_re.sh |
| 254 |
|
| 255 |
The RE compiles with the reference compiler but fails with lfortran, |
| 256 |
matching the issue. |
| 257 |
|
| 258 |
Next step: run the `create-mre` skill on this RE to reduce it to a minimal |
| 259 |
reproducible example, then `fix-mre` to fix the bug. |
| 260 |
``` |
| 261 |
|
| 262 |
## Tips |
| 263 |
|
| 264 |
- **Stay faithful to the issue**: the whole point of the RE stage is that it |
| 265 |
mirrors the reported code. Any reduction, renaming, or simplification belongs |
| 266 |
in `create-mre`, not here. |
| 267 |
- **Multiple code blocks**: if the issue shows both a module and a program, |
| 268 |
keep them as separate files; this mirrors how a real project is structured |
| 269 |
and is friendlier to `create-mre`. |
| 270 |
- **Compiler flags**: some bugs only manifest with specific `lfortran` flags |
| 271 |
(`--fast`, `--realloc-lhs`, `--openmp`, backend flags). Extract these from |
| 272 |
the issue text/code fences and bake them into `run_re.sh`. |
| 273 |
- **Fixed-form Fortran**: if the issue uses fixed-form (`.f`/`.f77`), keep |
| 274 |
that format and extension in the RE. |
| 275 |
- **Reporter's own reduction**: if the issue already contains a minimal |
| 276 |
snippet (common for well-written issues), your RE may be identical to the |
| 277 |
MRE. That's fine — the `create-mre` stage will be a no-op or near no-op. |
| 278 |
- **Unreproducible issues**: if you cannot reproduce the failure locally, |
| 279 |
stop and report back with diagnostics (compiler version, flags tried, |
| 280 |
actual vs reported error). Do not fabricate a reproduction. |
| 281 |
- **Multiple bugs in one issue**: if an issue mentions several distinct |
| 282 |
failures, create one RE per distinct failure (e.g. `re_issue_1234_a.f90`, |
| 283 |
`re_issue_1234_b.f90`) and one `run_re.sh` that exercises each in turn, |
| 284 |
clearly separated. |