fix-issue

# Fix Issue — From Issue to Review-Ready PR Drive each independent issue or connected group to a review-ready fork PR. An actual request to fix issues selects this skill through AGENTS.md's routing rule even when the user gives only the issues/search URL. The per-job and batch defaults apply without an additional workflow paragraph. Honor explicit task limits and do not start fixes for quoted examples or workflow discussions. Follow [AGENTS.md](../../../AGENTS.md#required-agent-toolchain-pixi): use only Pixi for dependencies, builds, compilers, and tests, with `llvm11` for all reference tests and updates. Pass this policy to every subagent; never install dependencies outside Pixi. For **a list, search URL, or filtered batch**, first read [references/batch.md](references/batch.md): resolve all matches and coordinate fresh issue-worker subagents in separate worktrees. Each worker follows the per-job procedure below. Pass it its assigned issue IDs, not the original batch query, so it does not recursively redispatch the batch. Per job: setup → reproduce → (reduce → fix → original-issue check) until fixed → suites once → draft PR → CI watch concurrent with the local pr-review/fix loop, with batched pushes → ready. Track additional bugs throughout, including jobs that stop without a PR. Quick checks (about 30–90 minutes) is the long pole: publish the draft as soon as the fix is verified, and review locally while CI runs. Every push reruns Quick and cancels the run in progress, so pushes are batched. **Push invariant:** never push compiler-source changes that have not passed the local suites once (`fix-mre` Phase 5b: unit, integration, and reference, in the default mode only). Record the passing commit as `suites_green_sha` in `state.md`. The suites are current when `git diff --quiet <suites_green_sha> HEAD -- src grammar` succeeds; otherwise whoever pushes next runs them once first. Changes outside `src/` and `grammar/` (tests, docs, commit messages, PR text) need only the changed tests run directly. Never rerun the suites locally with `--fast`, `--std=f23`, or other backends; Quick does. ## You are the orchestrator: delegate everything **Do all the real work in subagents.** Your job as the top-level agent is to sequence phases, pass short handoffs between them, and decide what happens next. Keep your own context small so it stays accurate across a loop that can last hours: - Spawn a **fresh** subagent for every phase and for every review/fix round. In Claude Code use the `Agent` tool; in other runtimes, use their equivalent. Never reuse a reviewer's context for fixing, or a fixer's context for reviewing. - Do not read source files, diffs, test logs, or CI logs yourself. Subagents read them and return a short report. - Every subagent prompt must be **self-contained**: a fresh subagent does not see this conversation. Include the issue IDs, absolute worktree and state paths, branch/base SHA, PR number, build directory, compiler path, exact Pixi invocation, job budget, skill, authorized actions, GitHub access method (`gh` or MCP tools, see **GitHub access**), and report format. Explicitly pass the no-co-author commit policy below to every committer. Tell it to load skills by name or read `.agents/skills/<name>/SKILL.md`. - Ask every subagent to end with a **report of at most ~20 lines** and to put anything longer (logs, review text, PR body) in a file under the state directory, returning only the path. - Only one subagent may modify, build, or test in a given worktree at a time. Independent worktrees may run concurrently within the shared resource budget. Read-only subagents (review, follow-up filing) may run with a CI watch, never with a fixer. - Every report ends with an **Unrelated bugs** list (or `none`): LFortran bugs the subagent ran into that are not needed to fix the original issue, such as a failure that also occurs on `main` or a separate bug seen while reducing or reviewing. One line each, plus a pointer to where the details (code, command, output) are saved. Never silently drop them, and never bundle unrelated fixes into this PR. Append each new one to `followups.md` and send it to the batch coordinator, which owns cross-job deduplication. ### State directory Keep each job's handoffs in `.fix-issue/<id>/` inside its **assigned worktree** (gitignored). `<id>` is an issue number or a job slug. Maintain `state.md`: input/all included issues, absolute worktree, branch/base SHA, fork remote, build directory, compiler/Pixi invocation, resource budget, PR URL, round, last pushed SHA, `suites_green_sha`, and status. Update it after every phase; reread it on resume. Subagents write their artifacts there: `repro.md`; for each MRE iteration `j`, `mre_<j>.md`, `fix_<j>.md`, `check_<j>.md`, the test and fail-before logs; then `suites.md`, `pr_body.md`, and for each review round `k`, `review_<k>.md`, `round_<k>.md`, `ci_<k>.log`. You maintain `followups.md`: one line per unrelated bug, with its status (`unfiled`, `filed #M`, `duplicate of #M`, or `regression, sent to fix loop`) and the path to its details. The reproducers themselves (`run_re.sh`, `re_*.f90`, `run.sh`, `mre_*.f90`) live in the repository root, following the conventions of the `repro-issue` and `create-mre` skills. Before iteration `j+1` overwrites `run.sh`, the current MRE files are archived to `.fix-issue/<id>/mre_<j>/`. ## GitHub access The `gh` commands in this skill name the required GitHub operation. Use `gh` where it works. In a cloud session, or whenever the session instructions recommend GitHub MCP tools over `gh`, perform the same operations with those tools; push with plain `git push` to the fork either way. Pass the access method to every subagent. If no available tool can perform a required operation, stop that step and report it to the user; do not continue as if it succeeded. ## Authorization For an actual fixing request, using this skill through explicit invocation or automatic routing authorizes isolated worktrees, branches, Pixi dependency installation/builds, commits and follow-up pushes to **the user's fork**, draft PRs against `lfortran/lfortran`, an explicitly requested Exhaustive dispatch in the fork, filing new unrelated pre-existing bugs, and marking verified PRs ready. This overrides the "do not commit" default in `fix-mre`. Pass the authorized subset explicitly to each subagent. Explicit user constraints (for example, no commits, no pushes, or no issue filing) narrow this workflow's authorization and must be passed to subagents. Never, under any circumstances: - push to the upstream `lfortran/lfortran` repository; - use an unconditional force-push; when the policy below calls for rebasing, update the fork branch only with `git push --force-with-lease`; - merge `main` into the PR branch; - comment on, close, or relabel the original issue, add a label to the PR, comment on other issues or PRs (including existing issues found in a duplicate search), or post review comments on other people's PRs; - bulk-update references blindly; use targeted LLVM 11 updates and review every change, including when invoking `pixi run -e llvm11 tests -u`. ### Commit authorship Do not add `Co-authored-by:` or `Co-author:` lines to **any** commit, including fixes, CI follow-ups, and merges. Do not use AI author/committer identities or alternative AI-credit stamps such as `Generated-By:` or `Assisted-By:`. `check_ai_commit_authorship.py` explains why: AI is a tool, while the submitting human must read, understand, and guarantee the changes. Quick Checks CI inspects the whole PR history. Preserve the configured human identity, do not invent one, and do not equate automated review with human sign-off. `AGENTS.md` owns this policy; `fix-mre` applies it when preparing commits. Pass it to all other fixers. ### Keeping the PR branch current Keep PR history linear: the branch must never contain a merge of `main`. Do not update the branch only because `main` moved; every push reruns CI, and Quick on `main` catches integration breakage after merging. Update it only when the PR has base conflicts, needs a change that landed on `main`, or CI failures look caused by a stale base. To update, run `git rebase <upstream-remote>/main` and resolve any conflicts. Set `suites_green_sha` to the rebased head only if the suites were current before the rebase and no conflicts in `src/` or `grammar/` were resolved; otherwise rebuild and rerun the targeted checks and the suites once before pushing (see **Push invariant**). Then update the fork with `git push --force-with-lease`. This applies in every PR state, including after review. Rebasing only moves the existing commits; address review feedback with new commits and do not squash or reword commits reviewers have already seen. ## Inputs 1. **The issue.** Accept any of: - a GitHub issue number (`12345`), `#12345`, or URL. Default repo: `lfortran/lfortran`. This is the common case. - an explicit list of issues, an issues/search URL with filters, or a request to fix all matching issues; use `references/batch.md`. - a pasted Fortran snippet with an error or wrong output; - a failure in a third-party package (project, file, command, error); - a JupyterLite / notebook failure. Ask the user only if the input is missing or does not describe a failure. ## Procedure ### Phase 0: Preflight (orchestrator, cheap commands only) Run a few quick checks yourself. Each prints only a few lines: Reuse shared preflight results supplied by a batch coordinator; do not repeat fetches or mutate shared Git state concurrently. 1. Choose the GitHub access method (see **GitHub access** above). With `gh`: `gh auth status`; if gh is not logged in, stop and ask the user to run `! gh auth login`. With MCP tools, confirm access to both `lfortran/lfortran` and the fork; otherwise ask the user to grant it. 2. `gh api user --jq .login` (or the MCP equivalent) gives `<login>`. 3. Inspect `git status --porcelain` and `git worktree list`. Preserve the caller's branch and dirty files: create a separate worktree instead of stashing, resetting, or asking the user to clean an unrelated checkout. 4. Identify remotes from `git remote -v`: - **upstream remote**: the one whose URL points at `lfortran/lfortran` (often `origin` or `upstream`); - **fork remote**: the one whose URL points at `<login>/lfortran`. If none exists, create the fork without touching existing remotes: `gh repo fork lfortran/lfortran --clone=false`, then `git remote add <login> git@github.com:<login>/lfortran.git` (use the https URL if `gh auth status` reports the https protocol). 5. For a GitHub issue, look for existing work and inspect candidates before deciding they overlap: `gh issue view <N> --repo lfortran/lfortran --json state,title` (closed?) and `gh pr list --repo lfortran/lfortran --state open --search "<N> in:body,title" --json number,title,author`. 6. Verify the configured human commit identity with `git var GIT_AUTHOR_IDENT` and `git var GIT_COMMITTER_IDENT`, and pass it to all committing workers. If it is missing or violates the authorship policy, report the required environment setup; do not infer a name/email from the GitHub login or invent an identity. Personal identity belongs in the user's Git configuration, including the cloud environment's setup, rather than shared project files. Do not take over someone else's PR or reopen a closed issue automatically. For overlapping work, ask or report that job as blocked; continue other jobs. Reserve an unused branch/worktree path and create the coordinator's state under the invoking checkout's ignored `.fix-issue/` directory. ### Phase 1: Setup subagent It should: 1. Use the coordinator's pinned upstream base. For a standalone job, fetch upstream `main` once and record its SHA. Create the reserved branch with `git worktree add -b fix/<id>-<slug> <absolute-worktree> <base-sha>`, never by checking out a branch in the caller's directory. Serialize shared Git operations; if the coordinator already created the worktree, verify and use it. Never reset or reuse unrelated existing branches. 2. In that worktree, create `.fix-issue/<id>/` and follow the **Pixi setup in `AGENTS.md`**: `pixi run -e llvm11 build '-DCMAKE_CXX_FLAGS_DEBUG=-g -O2' '-DCMAKE_C_FLAGS_DEBUG=-g -O2'`, saving the log. This provisions dependencies and builds into `build/llvm11`, not the source root. Set `CMAKE_BUILD_PARALLEL_LEVEL` to the worker's allocated budget. This first build, at the base SHA, also supplies the fail-before evidence for the first fix. 3. Record absolute paths and the exact environment invocation. In that environment, verify `command -v lfortran`, its reported LLVM version, `llvm-config --version`, and `gfortran --version`. Every later subagent must select this same build explicitly, not an inherited/system compiler. Report: worktree, branch/base SHA, build/compiler paths, Pixi command, job budget, tool versions, and build OK or failed (with the log path). ### Phase 2: Reproduce subagent - **GitHub issue:** run the `repro-issue` skill on the issue. Output: `run_re.sh` plus `re_*.f90` in the repository root. - **Pasted snippet:** apply the same RE conventions as `repro-issue` (faithful code, `run_re.sh` that shows the reference compiler succeeds and `lfortran` fails), just without fetching from GitHub. - **Third-party or notebook failure:** skip this phase. `create-mre` handles that input directly. For a connected group, repeat for every included issue and archive each RE and its script in `.fix-issue/<id>/repro/<issue>/` before the next one overwrites root-level scratch files. Preserve those originals for the final issue check. Report, also written to `repro.md`: reproduced yes/no, error type, the exact LFortran error, the reference compiler result, and whether the issue contains several distinct bugs. **Stop this job and report** if the bug does not reproduce on the pinned `main` (it may already be fixed), or if the reference compiler also rejects the code (the code may be invalid). Do not open a PR in either case. ### Phase 3: MRE loop — reduce, fix, check until the issue is fixed Fixing one bug can expose the next failure in the same reported code. Iterate `j = 1, 2, ...` with **no fixed cap**, one MRE, focused commit, and integration test per distinct bug. A single issue or connected group shares one PR; independent issues do not. Report newly discovered cross-job dependencies to the batch coordinator before implementing duplicate fixes or publishing. Stop the loop and report to the user if there is no progress: an iteration produced no verified fix, or the issue check shows the same failure as the previous iteration. Never open a PR for an unverified fix. #### 3a. Reduce subagent If `j > 1`, first move the previous `run.sh` and `mre_*.f90` to `.fix-issue/<id>/mre_<j-1>/`. Then run the `create-mre` skill on the **current** failure of the original reproducer: - for `j = 1`, the RE from Phase 2, or the third-party failure; - for `j > 1`, the failure recorded in `check_<j-1>.md`, which is produced by the assigned Pixi build of `lfortran` that already includes the earlier fixes. Output: `run.sh` plus `mre_*.f90`. Report, also written to `mre_<j>.md`: the MRE files, a one-line bug description, the error, and confirmation that `run.sh` fails with the current Pixi build of LFortran and succeeds with Pixi's reference compiler. If the current failure contains several distinct bugs, reduce only **one** per iteration. The loop picks up the rest. #### 3b. Fix subagent Run the `fix-mre` skill on the MRE, with these additions to its instructions: - Tell it which earlier iterations already committed fixes on this branch (from `fix_<1..j-1>.md`). It must not undo them, and must not duplicate their integration tests. - It must verify that the new integration test **fails without this iteration's fix and passes with it**, capturing the fail-before log with the build that predates this iteration's change (the first build at the base SHA for `j = 1`), not a separate baseline worktree unless that was missed. - It must pass `fix-mre` Phase 5a (the targeted checks) and skip 5b and 5c: the suites run once per job, in 3d, after the last iteration. - **Commit is authorized.** Make one focused commit for this bug, with an imperative `fix: ...` message. Do not stage scratch reproducers, logs, or `.fix-issue/`. Follow **Commit authorship**, including no co-author lines. - Do not push. Report, also written to `fix_<j>.md`: the commit SHA, the changed files, the test name, fail-before/pass-after verified (log paths), targeted results, any failures that already exist on `main`, and one paragraph of rationale (the bug, the compiler phase at fault, and why the fix belongs there). #### 3c. Issue check subagent (fresh) It verifies the **original** issue, not the MRE, against the rebuilt Pixi `lfortran`: - **GitHub issue or pasted snippet:** reread the issue text, including comments, and run `pixi run -e llvm11 bash run_re.sh`. The program must now compile and run, and its output must match the reference compiler's output and any expected output stated in the issue. Also check every other program, flag combination, or scenario the issue mentions that `run_re.sh` does not cover. If one is missing, add it to `run_re.sh`. - **Third-party failure:** re-run the original failing build or test command through the assigned Pixi environment, and continue past the point that used to fail. Report, also written to `check_<j>.md`: fully fixed yes/no. If no, report the exact new failure (the command, the error or the output diff, and the file involved) and whether it is the same failure as in `check_<j-1>.md`. For a group, perform this check for **every included issue**, using its archived original RE, and report per-issue results. If all are fixed, request the batch coordinator's grouping/publication decision, then go to 3d. Otherwise start iteration `j+1` on the next failure. #### 3d. Suites subagent (fresh) Unless the suites are already current (**Push invariant**), run `fix-mre` Phase 5b once on the head, handling failures as 5b describes: a regression caused by this branch starts iteration `j+1` on it; a pre-existing failure goes to `followups.md`. Record `suites_green_sha` in `state.md` and the results in `suites.md`, then go to Phase 4. ### Phase 4: Publish subagent Publish as soon as every included issue is fixed and the suites are current; local review follows in Phase 5, concurrently with CI. In a batch, wait for the coordinator to grant a Quick CI slot (`references/batch.md`). It should: 1. Write `.fix-issue/<id>/pr_body.md` from `repro.md` and all the `fix_<j>.md` files. Use plain Markdown with the headings Summary, Scope, Verification, Rationale. - Summary: `Fixes #<N>` for each fully verified included issue (omit for non-GitHub input), then a bullet per distinct bug, in commit order. - Scope: what is and is not covered, including unrelated bugs found along the way (linked once filed, see below) and non-bug follow-ups such as refactoring ideas or missing tests for existing behaviour, including review follow-up findings once known. - Verification: the integration tests added, each failing before its fix and passing after; the original reproducer now passing; the targeted checks and default-mode local suites; other modes run by Quick CI. - Rationale: for each bug, why the fix belongs in the chosen compiler phase. 2. Inspect all new commits for the authorship policy, confirm the **Push invariant**, then `git push -u <fork-remote> <branch>` 3. `gh pr create --repo lfortran/lfortran --base main --head <login>:<branch> --draft --title "<title>" --body-file .fix-issue/<id>/pr_body.md`. The title is the commit subject when there is a single commit. Otherwise