Debian Codegraph @

.claude/skills/repro-issue/SKILL.md

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