Debian Codegraph @

.claude/skills/pr-review/SKILL.md

raw
1 ---
2 name: pr-review
3 description: >
4 Review LFortran pull requests and code diffs using the project's architecture
5 and established review rules. Use this skill whenever asked to review a PR,
6 assess a patch, judge PR readiness, inspect an LLVM/codegen change, or suggest
7 where an LFortran compiler fix belongs. Push decisions as early as practical
8 into AST-to-ASR, explicit ASR state and verification, or a focused ASR pass;
9 keep backends small and mechanical. Covers correctness, reuse, tests, scope,
10 and maintainability with concrete good and bad implementation patterns.
11 compatibility: Requires git; use gh when reviewing a GitHub pull request.
12 ---
13
14 # Review an LFortran Pull Request
15
16 Find correctness and design problems before style issues. The central question
17 for every backend change is:
18
19 > What decision is the backend making, and can the compiler make that decision
20 > earlier and represent it explicitly in ASR?
21
22 Read `AGENTS.md` first. Read [references/review-rules.md](references/review-rules.md)
23 for the detailed principles. Consult [references/examples.md](references/examples.md)
24 when a concrete comparison would help.
25
26 ## Gather the change
27
28 For a GitHub PR, collect the description, commits, changed files, and diff:
29
30 ```bash
31 gh pr view <number> --repo lfortran/lfortran \
32 --json title,body,author,baseRefName,headRefName,commits,files,reviews
33 gh pr diff <number> --repo lfortran/lfortran
34 ```
35
36 For a local branch, inspect the merge-base diff and the worktree. Do not review
37 only the latest commit when the PR contains several commits.
38
39 Identify:
40
41 1. The bug or feature and its MRE.
42 2. The first compiler phase where behavior becomes wrong.
43 3. The invariant the fix should establish.
44 4. The tests that prove the old behavior fails and the new behavior works.
45
46 Check that the description's rationale and every helper, artifact, or behavior
47 it names are present and accurate in the diff. Treat architectural claims as
48 hypotheses until the code and reproducer support them.
49
50 If these cannot be determined from the PR, report that as a review finding
51 rather than guessing.
52
53 ## Review placement from earliest to latest
54
55 Walk this ladder in order. Stop at the earliest layer that can express the
56 decision cleanly:
57
58 1. **Parser / AST:** syntax and source-form distinctions. Parser actions should
59 produce AST even for semantically invalid input; semantic diagnostics belong
60 in AST-to-ASR.
61 2. **AST-to-ASR:** symbol resolution, type coercion, casts, overload selection,
62 semantic diagnostics, and other source-language decisions.
63 3. **ASR representation:** add or use a node field, enum, structured type, or
64 other explicit state when downstream code needs to know a semantic fact.
65 Extend ASR verification so malformed states fail near their origin. Only
66 symbol nodes own symbol tables; represent statement-local scopes with a
67 `Block` or a dedicated symbol node. A new ASR node also needs minimal support
68 in every exhaustive visitor, including verification, round-trip printing,
69 and dependency collection.
70 4. **Existing ASR pass:** use or extend a pass when the decision requires a
71 whole-tree transformation or canonical lowering.
72 5. **New ASR pass:** consider one only when it localizes a coherent algorithm,
73 simplifies multiple consumers, produces a useful explicit IR, and has clear
74 ordering and invariants.
75 6. **Backend:** keep only target-specific mechanics that cannot be represented
76 earlier.
77
78 Do not accept an LLVM-type query, opportunistic bitcast, magic string, or
79 backend-only type inference as a substitute for understanding the ASR. Querying
80 LLVM for a type and casting based on the result is a warning that ASR does not
81 yet express what is happening.
82
83 ### Decide whether to add an ASR pass
84
85 An ASR pass is justified when most of these are true:
86
87 - The transformation requires non-local knowledge or repeated tree rewriting.
88 - Several backends or later phases benefit from one canonical form.
89 - The output invariant is explicit and verifiable.
90 - Centralizing the algorithm removes duplicated complex logic.
91 - The pass can be enabled, disabled, ordered, and tested independently.
92
93 Prefer an ASR field plus verifier, an existing pass, or direct AST-to-ASR
94 construction when the transformation is local. A new pass adds compile time,
95 ordering dependencies, maintenance, and another failure boundary; LFortran
96 should have a few strong passes rather than many narrow ones.
97
98 If the work must remain in a backend, require the smallest target-specific
99 change possible. Reuse `asr_to_llvm`, `llvm_utils`, `ASRUtils`, `PassUtils`, and
100 existing lowering helpers. Reject duplicated loop builders, copied symbol
101 lookup, hard-coded argument positions, and long one-off blobs.
102
103 ## Review correctness and invariants
104
105 - Trace types, ranks, kinds, ownership, physical representations, and ABI facts
106 from ASR to the changed code.
107 - Check scalar and array forms, sections, allocatable/pointer forms, inherited
108 types, type-bound procedures, nondefault kinds, and target differences when
109 relevant.
110 - Preserve language semantics, not merely contiguous memory behavior. For
111 example, character-array elements used as an internal file are separate
112 records; flattening them into one byte stream is wrong.
113 - Prefer explicit structured state over string inspection and positional
114 assumptions.
115 - Identify intrinsic types and modules by structured origin, not a spoofable
116 name string.
117 - Distinguish compiler-synthesized and user-visible entities with explicit ASR
118 provenance, not generated-name prefixes or node-kind guesses.
119 - Represent defined-layout properties such as `SEQUENCE` and `BIND(C)` in ASR;
120 use that state for physical layout and interoperability decisions.
121 - Preserve symbol-table invariants: imported symbols point to their original
122 definitions, and symbol creation does not duplicate an existing local name.
123 - Use assertions that test the actual boolean invariant, or ASR verification,
124 for impossible states instead of quietly accepting them through defensive
125 conditionals.
126 - Propagate failures with `Result` and diagnostics carrying source `Location`;
127 do not introduce exceptions or broad try/catch recovery.
128 - Point diagnostics at the precise offending tokens and render types as valid
129 Fortran syntax.
130 - When accepting a deliberate nonstandard extension, emit a located portability
131 warning that explains the conforming alternative.
132 - In runtime C, pass actual buffer capacities to bounded APIs and avoid
133 undefined conversions or writes.
134 - Ensure `libasr` remains frontend-independent.
135
136 ## Review reuse and scope
137
138 Search before accepting a new helper or algorithm:
139
140 ```bash
141 rg "<related symbol or operation>" src integration_tests tests
142 ```
143
144 Ask whether the patch:
145
146 - duplicates a scalar path for arrays instead of normalizing the type once;
147 - adds a core utility when a pass-layer helper already exists;
148 - reconstructs loop nests, bounds, or array references already handled by a
149 shared helper;
150 - mixes a bug fix with refactoring, formatting, generated-output churn, or an
151 unrelated cleanup;
152 - adds comments that repeat the code or describe behavior not implemented; or
153 - introduces unused, dead, or unreachable code.
154
155 Recommend the concrete existing helper or layer, not just "simplify this."
156
157 ## Review tests
158
159 Require a test that fails without the fix and passes with it.
160
161 - Prefer a compact registered integration test with at least `gfortran` and
162 `llvm` labels when the behavior can run end to end.
163 - Verify that CI executes the exact binary, backend, options, and code path
164 changed by the PR.
165 - Add a targeted edge case for each newly handled error or semantic branch.
166 - Put recoverable semantic diagnostics in a complete continue-compilation test
167 and verify each error branch independently.
168 - Keep shared diagnostic fixtures append-only so new cases do not shift existing
169 source locations.
170 - Test portability warnings themselves, not only the accepted runtime behavior;
171 document why unsupported reference compilers are omitted from test labels.
172 - Differential C interoperability tests must include each compiler's own
173 `ISO_Fortran_binding.h` and use its corresponding runtime.
174 - Keep fixtures proportional to the bug. A 1,300-line program for one
175 out-of-bounds error is not an acceptable regression test.
176 - Avoid large reference-output churn. Make preparatory spacing or mechanical
177 changes separately so the behavioral diff remains reviewable. Regeneration
178 caused directly by an ASR schema change is legitimate, but should be
179 mechanically consistent.
180 - For external-project CI failures, identify the failing toolchain and root
181 cause before accepting a skip or an upstream patch that disables coverage.
182 - Build changes must track real inputs, quote paths, fail early when required
183 artifacts are absent, and avoid committed binary or large generated blobs.
184 - Any CI build or generation step that can fail must run on pull requests unless
185 it inherently requires main-only publishing credentials.
186
187 ## Account for pragmatic follow-ups
188
189 An approval can mean "safe enough to merge and iterate," not that every line is
190 endorsed. Keep unresolved correctness issues visible. Classify each finding as:
191
192 - **Blocker:** wrong semantics, invalid ASR, regression, unsafe error handling,
193 or an untested core behavior.
194 - **Rework:** maintainability or placement problem that should be fixed in this
195 PR because it shapes the implementation.
196 - **Follow-up:** bounded debt that does not invalidate the current change; state
197 the exact follow-up test or refactor.
198
199 Do not silently downgrade a correctness bug because another review approved the
200 PR.
201
202 A draft, pending, or otherwise unsubmitted review does not gate merging. Confirm
203 that any blocker-level concern was resolved or explicitly tracked before
204 treating a merge as evidence that the implementation is sound. Treat approval
205 conditioned on a fresh full run as incomplete until that run succeeds.
206
207 ## Write the review
208
209 Report only actionable findings, ordered by severity. Use this shape:
210
211 ```text
212 [blocker|rework|follow-up] Short title
213 path/to/file.cpp:<line>
214
215 What is wrong and the concrete input or invariant that demonstrates it.
216 Why the current layer or implementation is risky.
217 Recommended shape: the earlier phase, ASR state/pass, or existing helper to use.
218 ```
219
220 Then add a short **Architecture assessment**:
221
222 - earliest wrong phase;
223 - chosen fix layer and whether it is justified;
224 - ASR invariant added or still missing;
225 - backend complexity added or removed.
226
227 If no actionable findings remain, say so and mention only meaningful residual
228 risks or test gaps. Treat automated-review findings as hypotheses: reproduce
229 and understand them before reporting them as blockers. Do not manufacture style
230 comments.