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