From 816a2e41a26f0b16158ac7851e498b3c33444b4e Mon Sep 17 00:00:00 2001 From: Pascal Roth Date: Wed, 11 Mar 2026 17:45:14 +0100 Subject: [PATCH 1/3] add claude pr review skills --- .agent/skills/isaaclab-bug-fix/SKILL.md | 151 +++++++++++++++ .agent/skills/isaaclab-bug-reproduce/SKILL.md | 179 ++++++++++++++++++ .agent/skills/isaaclab-issue-triage/SKILL.md | 82 ++++++++ AGENTS.md | 61 ++++++ 4 files changed, 473 insertions(+) create mode 100644 .agent/skills/isaaclab-bug-fix/SKILL.md create mode 100644 .agent/skills/isaaclab-bug-reproduce/SKILL.md create mode 100644 .agent/skills/isaaclab-issue-triage/SKILL.md diff --git a/.agent/skills/isaaclab-bug-fix/SKILL.md b/.agent/skills/isaaclab-bug-fix/SKILL.md new file mode 100644 index 000000000000..23c9948285e0 --- /dev/null +++ b/.agent/skills/isaaclab-bug-fix/SKILL.md @@ -0,0 +1,151 @@ +--- +name: isaaclab-bug-fix +description: Fix a reproduced IsaacLab bug by creating a branch, implementing the fix, updating changelogs, running pre-commit, and opening a PR following project guidelines. Use when a bug has been reproduced and needs a code fix, or when asked to fix an issue and create a pull request. +--- + +# IsaacLab Bug Fix + +Implement a fix for a reproduced bug, following all IsaacLab contribution guidelines. + +## Inputs + +- **Issue number**: GitHub issue `#N` +- **Issue title and description**: For PR context +- **Reproduction steps and error**: From the reproduce phase +- **Affected code location**: Identified during reproduction + +## Workflow + +### Step 1: Create a feature branch + +```bash +git checkout origin/develop +git checkout -b isaaclab-bot/fix-issue- +``` + +Branch naming: `isaaclab-bot/fix-issue-` (e.g. `isaaclab-bot/fix-issue-1234`). + +### Step 2: Implement the fix + +Follow the coding standards defined in `AGENTS.md` and `docs/source/refs/contributing.rst`. Read both files before implementing. + +### Step 3: Write a regression test + +Add a test that: +1. **Fails** without the fix (verify by temporarily reverting your change) +2. **Passes** with the fix applied + +Use pytest: +```bash +./isaaclab.sh -p -m pytest :: +``` + +### Step 4: Update the changelog + +Determine which `source//` directories were modified and update each affected package's changelog. + +1. Find the current version in `source//config/extension.toml` +2. Bump the **patch** version (e.g. `1.5.0` → `1.5.1`) +3. Add a new version entry at the top of `source//docs/CHANGELOG.rst` +4. Update `version` in `source//config/extension.toml` to match + +Changelog entry format: + +```rst +X.Y.Z (YYYY-MM-DD) +~~~~~~~~~~~~~~~~~~~ + +Fixed +^^^^^ + +* Fixed in :meth:`~package.Class.method`. + +``` + +Use today's date. Use past tense. Use Sphinx cross-references for class/method names. + +### Step 5: Run pre-commit + +**CRITICAL: Run BEFORE committing.** + +```bash +./isaaclab.sh -f +``` + +If it modifies files, stage them and run again: +```bash +git add -A +./isaaclab.sh -f +``` + +Repeat until all checks pass. + +### Step 6: Commit + +```bash +git add -A +git commit -m "$(cat <<'EOF' +Fix #: + + +EOF +)" +``` + +Rules: +- Imperative mood subject line (~50 chars) +- No trailing period on subject +- Body explains what and why +- **No AI attribution lines** + +### Step 7: Push and create PR + +```bash +git push -u origin HEAD +``` + +Create PR using the project template: + +```bash +gh pr create --repo isaac-sim/IsaacLab --base develop --title "Fix #: " --body "$(cat <<'EOF' +# Description + + + +Fixes # + +## Type of change + +- Bug fix (non-breaking change which fixes an issue) + +## Screenshots + +N/A + +## Checklist + +- [x] I have read and understood the [contribution guidelines](https://isaac-sim.github.io/IsaacLab/main/source/refs/contributing.html) +- [x] I have run the [`pre-commit` checks](https://pre-commit.com/) with `./isaaclab.sh --format` +- [x] I have made corresponding changes to the documentation +- [x] My changes generate no new warnings +- [x] I have added tests that prove my fix is effective or that my feature works +- [x] I have updated the changelog and the corresponding version in the extension's `config/extension.toml` file +- [ ] I have added my name to the `CONTRIBUTORS.md` or my name already exists there + +EOF +)" +``` + +### Step 8: Post-PR comment on the issue + +```bash +gh issue comment --repo isaac-sim/IsaacLab --body "A fix has been submitted in PR #. The root cause was ." +``` + +## References + +- Coding standards and changelog rules: read `AGENTS.md` +- Contributing guidelines and code style: read `docs/source/refs/contributing.rst` +- PR template: read `.github/PULL_REQUEST_TEMPLATE.md` +- Bug report template: read `.github/ISSUE_TEMPLATE/bug.md` diff --git a/.agent/skills/isaaclab-bug-reproduce/SKILL.md b/.agent/skills/isaaclab-bug-reproduce/SKILL.md new file mode 100644 index 000000000000..fe592352345d --- /dev/null +++ b/.agent/skills/isaaclab-bug-reproduce/SKILL.md @@ -0,0 +1,179 @@ +--- +name: isaaclab-bug-reproduce +description: Reproduce a reported bug in IsaacLab by checking out the specified commit, running the reproduction steps, and determining if the bug is still present on the latest commit. Use when asked to reproduce, verify, or test a reported GitHub issue. +--- + +# IsaacLab Bug Reproduce + +Systematically reproduce a reported bug and determine its current status. + +## Inputs + +- **Issue number**: GitHub issue `#N` +- **Commit hash**: From the issue's System Info or latest `develop` +- **Reproduction steps**: Extracted from the issue body + +## Workflow + +### Step 1: Checkout the reported commit + +Older commits won't have the workflow files. Before switching, save them to a +temp directory and restore them after checkout so the agent context is preserved. + +```bash +git fetch origin + +# Preserve workflow files that may not exist on the target commit +AGENT_TMPDIR="$(mktemp -d)" +cp -r .agent "$AGENT_TMPDIR/.agent" 2>/dev/null || true +cp AGENTS.md "$AGENT_TMPDIR/AGENTS.md" 2>/dev/null || true +cp CLAUDE.md "$AGENT_TMPDIR/CLAUDE.md" 2>/dev/null || true + +git stash # save any local changes +git checkout + +# Restore workflow files onto the checked-out tree (don't stage them) +cp -r "$AGENT_TMPDIR/.agent" .agent 2>/dev/null || true +cp "$AGENT_TMPDIR/AGENTS.md" AGENTS.md 2>/dev/null || true +cp "$AGENT_TMPDIR/CLAUDE.md" CLAUDE.md 2>/dev/null || true +``` + +If the commit hash is invalid or not found, fall back to `origin/develop`: +```bash +git checkout origin/develop + +# Restore workflow files (same as above) +cp -r "$AGENT_TMPDIR/.agent" .agent 2>/dev/null || true +cp "$AGENT_TMPDIR/AGENTS.md" AGENTS.md 2>/dev/null || true +cp "$AGENT_TMPDIR/CLAUDE.md" CLAUDE.md 2>/dev/null || true +``` + +### Step 2: Attempt reproduction + +Run the reproduction steps from the issue. Use `./isaaclab.sh -p` to run Python scripts: + +```bash +./isaaclab.sh -p +``` + +For inline Python: +```bash +./isaaclab.sh -p -c "" +``` + +For tests: +```bash +./isaaclab.sh -p -m pytest +``` + +**Record the output carefully** — capture exit codes, error messages, and stack traces. + +### Step 3: Evaluate reproduction result + +``` +Reproduction attempted +├─ Bug reproduced at reported commit? +│ ├─ YES → Go to Step 4 (test on latest) +│ └─ NO → Go to Step 5 (comment: cannot reproduce) +``` + +### Step 4: Test on latest commit + +```bash +git checkout origin/develop + +# Restore workflow files again after switching +cp -r "$AGENT_TMPDIR/.agent" .agent 2>/dev/null || true +cp "$AGENT_TMPDIR/AGENTS.md" AGENTS.md 2>/dev/null || true +cp "$AGENT_TMPDIR/CLAUDE.md" CLAUDE.md 2>/dev/null || true +``` + +Re-run the same reproduction steps. + +``` +Bug on latest develop? +├─ YES (still reproduces) → Route to isaaclab-bug-fix skill +├─ NO (fixed on latest) → Go to Step 6 (comment: fixed, close issue) +``` + +### Step 5: Comment — Cannot Reproduce + +Post a comment explaining what was tried and asking for clarification: + +```markdown +I attempted to reproduce this issue at commit `` with the following steps: + +``` + +``` + +**Result**: The operation completed successfully without the reported error. + +
+Full output + +``` + +``` + +
+ +Could you please provide more details or a minimal reproducible example? Specifically: +- The exact command or script you ran +- Your full environment details (OS, GPU, CUDA, Isaac Sim version) +- The complete error output + +This will help us narrow down environment-specific factors. +``` + +Post via: +```bash +gh issue comment --repo isaac-sim/IsaacLab --body "" +``` + +### Step 6: Comment — Fixed on Latest & Close + +```markdown +This issue appears to have been resolved on the latest `develop` branch (commit ``). + +I tested with the following steps: + +``` + +``` + +**Result**: The operation completed successfully. + +
+Full output + +``` + +``` + +
+ +Closing this issue. If you still experience the problem on the latest version, please reopen with updated reproduction steps. +``` + +Post and close: +```bash +gh issue comment --repo isaac-sim/IsaacLab --body "" +gh issue close --repo isaac-sim/IsaacLab +``` + +### Step 7: Clean up + +```bash +git checkout develop # return to develop +git stash pop # restore any stashed changes (if applicable) +rm -rf "$AGENT_TMPDIR" # remove temp copy of workflow files +``` + +## Important Notes + +- **Preserve workflow files across checkouts.** `AGENTS.md`, `CLAUDE.md`, and `.agent/` may not exist on older commits. Always copy them to a temp dir before checkout and restore them after. Never stage or commit these restored files. +- Always use `./isaaclab.sh -p` instead of raw `python3` for running scripts +- Capture ALL output (stdout + stderr) for evidence +- If reproduction requires a simulator (Isaac Sim) and it's not available, note this limitation in the comment +- Be precise about which commit was tested — always include the full hash diff --git a/.agent/skills/isaaclab-issue-triage/SKILL.md b/.agent/skills/isaaclab-issue-triage/SKILL.md new file mode 100644 index 000000000000..e72a8115ae3e --- /dev/null +++ b/.agent/skills/isaaclab-issue-triage/SKILL.md @@ -0,0 +1,82 @@ +--- +name: isaaclab-issue-triage +description: Triage GitHub issues for the IsaacLab repo. Validates bug reports against the bug template, checks for required fields (commit, steps to reproduce), comments requesting missing info, and routes reproducible bugs to the reproduce and fix workflows. Use when asked to triage issues, check bugs, or process GitHub issues. +--- + +# IsaacLab Issue Triage + +Automated workflow to triage bug issues on `isaac-sim/IsaacLab`. + +## Prerequisites + +- `gh` CLI authenticated (`gh auth status`) +- Git repo cloned with remote `origin` pointing to `isaac-sim/IsaacLab` + +## Workflow + +### Step 1: Fetch open bug issues + +```bash +gh issue list --repo isaac-sim/IsaacLab --label bug --state open --json number,title,body,labels,comments --limit 50 +``` + +If no `--label bug` filter works, fetch all open issues and filter for `[Bug Report]` in the title or `bug` label. + +### Step 2: For each bug issue, validate the report + +Parse the issue body and check for required fields from the bug template: + +**Required fields:** +- **Steps to reproduce**: Look for `### Steps to reproduce` section with actual content (not just the template placeholder) +- **Commit hash**: Look for `### System Info` section containing `- Commit:` with an actual hash (not `[e.g. 8f3b9ca]`) + +**Decision tree:** + +``` +Issue body parsed +├─ Missing steps to reproduce AND no other useful details? +│ └─ Comment requesting steps (see "Comment: Missing Steps" below) +│ Then STOP for this issue. +├─ Has steps to reproduce but missing commit? +│ └─ Use the latest commit on `develop` branch. +│ Proceed to reproduce. +├─ Has both commit and steps? +│ └─ Proceed to reproduce. +└─ Not a bug report (feature request, question, etc.)? + └─ Skip. +``` + +### Step 3: Route to reproduction + +Follow the **isaaclab-bug-reproduce** skill with: +- The issue number +- The commit hash (from issue or latest `develop`) +- The reproduction steps extracted from the issue body + +### Comment Templates + +**Comment: Missing Steps** + +```markdown +Thank you for filing this issue. To help us investigate, could you please provide: + +1. **Minimal steps to reproduce** the bug (a small script or sequence of commands) +2. **The full error message / stack trace** (if applicable) + +These details are required per our [bug report template](https://github.com/isaac-sim/IsaacLab/blob/main/.github/ISSUE_TEMPLATE/bug.md) and are essential for us to diagnose the problem. We'll revisit this issue once the reproduction steps are available. +``` + +Post via: +```bash +gh issue comment --repo isaac-sim/IsaacLab --body "" +``` + +## Batch Processing + +When triaging multiple issues, process them sequentially. For each issue, complete the full triage cycle (validate → reproduce → fix or comment) before moving to the next. + +## References + +- Bug report template: read `.github/ISSUE_TEMPLATE/bug.md` for the expected issue fields +- Contributing guidelines: read `docs/source/refs/contributing.rst` for coding style and PR requirements +- Project rules: read `AGENTS.md` for naming, changelog, commit, and testing conventions diff --git a/AGENTS.md b/AGENTS.md index 70c1d15158ab..ef8d8d93d902 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -149,6 +149,67 @@ Follow conventional commit message practices. ``` - Do not change the year in existing file headers. +## Issue Triage Workflow + +Automated pipeline for triaging, reproducing, and fixing GitHub bug reports. Trigger it for a single issue with: + +```bash +claude "Run the issue triage workflow for issue #" +``` + +The workflow chains three skills in `.agent/skills/` and follows this decision tree: + +``` +Fetch issue #N +├─ Not a bug report → Skip +├─ Missing reproduction steps (and no other useful details) +│ └─ Comment asking for steps → STOP +├─ Has reproduction steps (use latest develop if commit is missing) +│ └─ Checkout commit, run repro steps +│ ├─ Cannot reproduce +│ │ └─ Comment with what was tried, ask for details → STOP +│ └─ Reproduces +│ └─ Checkout latest develop, re-run +│ ├─ Fixed on latest +│ │ └─ Comment with evidence, close issue → STOP +│ └─ Still broken +│ └─ Create branch, fix, test, changelog, pre-commit, PR → DONE +``` + +### Skills + +| Skill | Path | Purpose | +|-------|------|---------| +| `isaaclab-issue-triage` | `.agent/skills/isaaclab-issue-triage/SKILL.md` | Fetch issue, validate bug template fields, route | +| `isaaclab-bug-reproduce` | `.agent/skills/isaaclab-bug-reproduce/SKILL.md` | Checkout commit, run repro steps, evaluate result | +| `isaaclab-bug-fix` | `.agent/skills/isaaclab-bug-fix/SKILL.md` | Branch, fix, test, changelog, pre-commit, PR | + +### Required context files + +The skills reference these repo files directly (no duplication): +- `.github/ISSUE_TEMPLATE/bug.md` — expected bug report fields +- `.github/PULL_REQUEST_TEMPLATE.md` — PR format +- `docs/source/refs/contributing.rst` — coding style and contribution process +- `AGENTS.md` (this file) — changelog, commit, naming, and testing rules + +### Running for a single issue + +When asked to triage a specific issue number, execute the full chain: + +1. **Read** `.agent/skills/isaaclab-issue-triage/SKILL.md` — fetch and validate the issue +2. If the issue is valid for reproduction, **read** `.agent/skills/isaaclab-bug-reproduce/SKILL.md` — attempt reproduction +3. If the bug still reproduces on latest, **read** `.agent/skills/isaaclab-bug-fix/SKILL.md` — implement and submit the fix + +Stop at any step that reaches a terminal state (commented, closed, or needs user input). + +### Running for all open bugs + +```bash +claude "Run the issue triage workflow for all open bug issues" +``` + +This processes each open bug issue sequentially through the full chain. + ## Sandbox & Networking - Network access (e.g., `git push`) is blocked by the sandbox. Use `dangerouslyDisableSandbox: true` so the user gets an approval prompt — don't ask them to run it manually. From 5ec43d2189079e91ded2832b0e3db92bf99c8ce7 Mon Sep 17 00:00:00 2001 From: Pascal Roth Date: Wed, 18 Mar 2026 14:09:05 +0100 Subject: [PATCH 2/3] Fix --video producing black frames when no Kit visualizer is active SimulationContext.render() was not calling omni.kit.app.get_app().update() when running with Isaac Sim (Kit) and no active visualizer pumped the Kit app loop. This meant replicator render products (used by gym.wrappers.RecordVideo via render_mode="rgb_array") were never refreshed, producing black video frames. The fix calls app.update() in render() when has_kit() is True and no visualizer with pumps_app_update() == True is active. KitVisualizer already calls app.update() in its own step(), so we skip the call to avoid double-rendering when --viz kit is used. Adds two regression tests to verify: 1. render() calls app.update() when no visualizer pumps the Kit loop 2. render() does not call app.update() when a visualizer already does Fixes #5052 --- source/isaaclab/config/extension.toml | 2 +- source/isaaclab/docs/CHANGELOG.rst | 11 ++++ .../isaaclab/sim/simulation_context.py | 15 +++++ .../test/sim/test_simulation_context.py | 61 +++++++++++++++++++ 4 files changed, 88 insertions(+), 1 deletion(-) diff --git a/source/isaaclab/config/extension.toml b/source/isaaclab/config/extension.toml index 27835fbd6240..6f1626a1ca8f 100644 --- a/source/isaaclab/config/extension.toml +++ b/source/isaaclab/config/extension.toml @@ -1,7 +1,7 @@ [package] # Note: Semantic Versioning is used: https://semver.org/ -version = "4.5.16" +version = "4.5.17" # Description title = "Isaac Lab framework for Robot Learning" diff --git a/source/isaaclab/docs/CHANGELOG.rst b/source/isaaclab/docs/CHANGELOG.rst index 4ea5c22e44f5..c5b898cfab83 100644 --- a/source/isaaclab/docs/CHANGELOG.rst +++ b/source/isaaclab/docs/CHANGELOG.rst @@ -1,6 +1,17 @@ Changelog --------- +4.5.17 (2026-03-18) +~~~~~~~~~~~~~~~~~~~ + +Fixed +^^^^^ + +* Fixed :meth:`~isaaclab.sim.SimulationContext.render` not calling ``app.update()`` when + running with Isaac Sim (Kit) and no active visualizer pumps the Kit app loop. This caused + ``--video`` recording to produce black frames when not using ``--viz kit``. + + 4.5.16 (2026-03-10) ~~~~~~~~~~~~~~~~~~~ diff --git a/source/isaaclab/isaaclab/sim/simulation_context.py b/source/isaaclab/isaaclab/sim/simulation_context.py index 8df584e1aa63..ef193af4d08d 100644 --- a/source/isaaclab/isaaclab/sim/simulation_context.py +++ b/source/isaaclab/isaaclab/sim/simulation_context.py @@ -604,6 +604,21 @@ def render(self, mode: int | None = None) -> None: for callback in self._render_callbacks.values(): callback(None) # Pass None as event data + # When running with Isaac Sim (Kit) and no active visualizer already pumps the Kit + # app loop, call app.update() so the viewport and replicator render products + # (used e.g. by gym.wrappers.RecordVideo with render_mode="rgb_array") are refreshed. + # KitVisualizer.pumps_app_update() returns True and calls app.update() in its own + # step(), so we skip this call to avoid double-rendering in that case. + if has_kit() and not any(v.pumps_app_update() for v in self._visualizers): + try: + import omni.kit.app + + app = omni.kit.app.get_app() + if app is not None and app.is_running(): + app.update() + except (ImportError, AttributeError): + pass + def update_visualizers(self, dt: float) -> None: """Update visualizers without triggering renderer/GUI.""" if not self._visualizers: diff --git a/source/isaaclab/test/sim/test_simulation_context.py b/source/isaaclab/test/sim/test_simulation_context.py index c03413838e3e..cb156db7cde6 100644 --- a/source/isaaclab/test/sim/test_simulation_context.py +++ b/source/isaaclab/test/sim/test_simulation_context.py @@ -290,6 +290,67 @@ def test_render(): assert sim.is_playing() +@pytest.mark.isaacsim_ci +def test_render_pumps_app_update_without_visualizer(): + """Regression test for issue #5052: render() must call app.update() when no visualizer pumps the Kit loop. + + Without this call, replicator render products (used by gym.wrappers.RecordVideo for + rgb_array rendering) are never updated, producing black video frames. + """ + from unittest.mock import MagicMock, patch + + cfg = SimulationCfg(dt=0.01) + sim = SimulationContext(cfg) + sim.reset() + + mock_app = MagicMock() + mock_app.is_running.return_value = True + + with patch("omni.kit.app.get_app", return_value=mock_app): + sim.render() + + # app.update() must be called when no visualizer pumps the Kit app loop + mock_app.update.assert_called_once() + + +@pytest.mark.isaacsim_ci +def test_render_skips_app_update_when_visualizer_pumps_it(): + """Regression test: render() must NOT call app.update() when a visualizer already does. + + A visualizer that returns ``pumps_app_update() == True`` (e.g. KitVisualizer) calls + ``app.update()`` in its own ``step()``, so ``SimulationContext.render()`` must not + call it again to avoid double-rendering. + """ + from unittest.mock import MagicMock, patch + + from isaaclab.visualizers.base_visualizer import BaseVisualizer + + cfg = SimulationCfg(dt=0.01) + sim = SimulationContext(cfg) + sim.reset() + + # Inject a mock visualizer that pumps the app update + mock_viz = MagicMock(spec=BaseVisualizer) + mock_viz.pumps_app_update.return_value = True + mock_viz.is_closed = False + mock_viz.is_running.return_value = True + mock_viz.is_rendering_paused.return_value = False + mock_viz.is_training_paused.return_value = False + mock_viz.get_rendering_dt.return_value = None + sim._visualizers = [mock_viz] + + mock_app = MagicMock() + mock_app.is_running.return_value = True + + with patch("omni.kit.app.get_app", return_value=mock_app): + sim.render() + + # app.update() must NOT be called since the visualizer already pumps it + mock_app.update.assert_not_called() + + sim._visualizers = [] + + """ Stage Operations Tests """ From db26442e0c32cb2b29998d4356e54ea6c9d473ef Mon Sep 17 00:00:00 2001 From: Pascal Roth Date: Wed, 18 Mar 2026 15:45:41 +0100 Subject: [PATCH 3/3] remove skills --- .agent/skills/isaaclab-bug-fix/SKILL.md | 151 --------------- .agent/skills/isaaclab-bug-reproduce/SKILL.md | 179 ------------------ .agent/skills/isaaclab-issue-triage/SKILL.md | 82 -------- AGENTS.md | 61 ------ 4 files changed, 473 deletions(-) delete mode 100644 .agent/skills/isaaclab-bug-fix/SKILL.md delete mode 100644 .agent/skills/isaaclab-bug-reproduce/SKILL.md delete mode 100644 .agent/skills/isaaclab-issue-triage/SKILL.md diff --git a/.agent/skills/isaaclab-bug-fix/SKILL.md b/.agent/skills/isaaclab-bug-fix/SKILL.md deleted file mode 100644 index 23c9948285e0..000000000000 --- a/.agent/skills/isaaclab-bug-fix/SKILL.md +++ /dev/null @@ -1,151 +0,0 @@ ---- -name: isaaclab-bug-fix -description: Fix a reproduced IsaacLab bug by creating a branch, implementing the fix, updating changelogs, running pre-commit, and opening a PR following project guidelines. Use when a bug has been reproduced and needs a code fix, or when asked to fix an issue and create a pull request. ---- - -# IsaacLab Bug Fix - -Implement a fix for a reproduced bug, following all IsaacLab contribution guidelines. - -## Inputs - -- **Issue number**: GitHub issue `#N` -- **Issue title and description**: For PR context -- **Reproduction steps and error**: From the reproduce phase -- **Affected code location**: Identified during reproduction - -## Workflow - -### Step 1: Create a feature branch - -```bash -git checkout origin/develop -git checkout -b isaaclab-bot/fix-issue- -``` - -Branch naming: `isaaclab-bot/fix-issue-` (e.g. `isaaclab-bot/fix-issue-1234`). - -### Step 2: Implement the fix - -Follow the coding standards defined in `AGENTS.md` and `docs/source/refs/contributing.rst`. Read both files before implementing. - -### Step 3: Write a regression test - -Add a test that: -1. **Fails** without the fix (verify by temporarily reverting your change) -2. **Passes** with the fix applied - -Use pytest: -```bash -./isaaclab.sh -p -m pytest :: -``` - -### Step 4: Update the changelog - -Determine which `source//` directories were modified and update each affected package's changelog. - -1. Find the current version in `source//config/extension.toml` -2. Bump the **patch** version (e.g. `1.5.0` → `1.5.1`) -3. Add a new version entry at the top of `source//docs/CHANGELOG.rst` -4. Update `version` in `source//config/extension.toml` to match - -Changelog entry format: - -```rst -X.Y.Z (YYYY-MM-DD) -~~~~~~~~~~~~~~~~~~~ - -Fixed -^^^^^ - -* Fixed in :meth:`~package.Class.method`. - -``` - -Use today's date. Use past tense. Use Sphinx cross-references for class/method names. - -### Step 5: Run pre-commit - -**CRITICAL: Run BEFORE committing.** - -```bash -./isaaclab.sh -f -``` - -If it modifies files, stage them and run again: -```bash -git add -A -./isaaclab.sh -f -``` - -Repeat until all checks pass. - -### Step 6: Commit - -```bash -git add -A -git commit -m "$(cat <<'EOF' -Fix #: - - -EOF -)" -``` - -Rules: -- Imperative mood subject line (~50 chars) -- No trailing period on subject -- Body explains what and why -- **No AI attribution lines** - -### Step 7: Push and create PR - -```bash -git push -u origin HEAD -``` - -Create PR using the project template: - -```bash -gh pr create --repo isaac-sim/IsaacLab --base develop --title "Fix #: " --body "$(cat <<'EOF' -# Description - - - -Fixes # - -## Type of change - -- Bug fix (non-breaking change which fixes an issue) - -## Screenshots - -N/A - -## Checklist - -- [x] I have read and understood the [contribution guidelines](https://isaac-sim.github.io/IsaacLab/main/source/refs/contributing.html) -- [x] I have run the [`pre-commit` checks](https://pre-commit.com/) with `./isaaclab.sh --format` -- [x] I have made corresponding changes to the documentation -- [x] My changes generate no new warnings -- [x] I have added tests that prove my fix is effective or that my feature works -- [x] I have updated the changelog and the corresponding version in the extension's `config/extension.toml` file -- [ ] I have added my name to the `CONTRIBUTORS.md` or my name already exists there - -EOF -)" -``` - -### Step 8: Post-PR comment on the issue - -```bash -gh issue comment --repo isaac-sim/IsaacLab --body "A fix has been submitted in PR #. The root cause was ." -``` - -## References - -- Coding standards and changelog rules: read `AGENTS.md` -- Contributing guidelines and code style: read `docs/source/refs/contributing.rst` -- PR template: read `.github/PULL_REQUEST_TEMPLATE.md` -- Bug report template: read `.github/ISSUE_TEMPLATE/bug.md` diff --git a/.agent/skills/isaaclab-bug-reproduce/SKILL.md b/.agent/skills/isaaclab-bug-reproduce/SKILL.md deleted file mode 100644 index fe592352345d..000000000000 --- a/.agent/skills/isaaclab-bug-reproduce/SKILL.md +++ /dev/null @@ -1,179 +0,0 @@ ---- -name: isaaclab-bug-reproduce -description: Reproduce a reported bug in IsaacLab by checking out the specified commit, running the reproduction steps, and determining if the bug is still present on the latest commit. Use when asked to reproduce, verify, or test a reported GitHub issue. ---- - -# IsaacLab Bug Reproduce - -Systematically reproduce a reported bug and determine its current status. - -## Inputs - -- **Issue number**: GitHub issue `#N` -- **Commit hash**: From the issue's System Info or latest `develop` -- **Reproduction steps**: Extracted from the issue body - -## Workflow - -### Step 1: Checkout the reported commit - -Older commits won't have the workflow files. Before switching, save them to a -temp directory and restore them after checkout so the agent context is preserved. - -```bash -git fetch origin - -# Preserve workflow files that may not exist on the target commit -AGENT_TMPDIR="$(mktemp -d)" -cp -r .agent "$AGENT_TMPDIR/.agent" 2>/dev/null || true -cp AGENTS.md "$AGENT_TMPDIR/AGENTS.md" 2>/dev/null || true -cp CLAUDE.md "$AGENT_TMPDIR/CLAUDE.md" 2>/dev/null || true - -git stash # save any local changes -git checkout - -# Restore workflow files onto the checked-out tree (don't stage them) -cp -r "$AGENT_TMPDIR/.agent" .agent 2>/dev/null || true -cp "$AGENT_TMPDIR/AGENTS.md" AGENTS.md 2>/dev/null || true -cp "$AGENT_TMPDIR/CLAUDE.md" CLAUDE.md 2>/dev/null || true -``` - -If the commit hash is invalid or not found, fall back to `origin/develop`: -```bash -git checkout origin/develop - -# Restore workflow files (same as above) -cp -r "$AGENT_TMPDIR/.agent" .agent 2>/dev/null || true -cp "$AGENT_TMPDIR/AGENTS.md" AGENTS.md 2>/dev/null || true -cp "$AGENT_TMPDIR/CLAUDE.md" CLAUDE.md 2>/dev/null || true -``` - -### Step 2: Attempt reproduction - -Run the reproduction steps from the issue. Use `./isaaclab.sh -p` to run Python scripts: - -```bash -./isaaclab.sh -p -``` - -For inline Python: -```bash -./isaaclab.sh -p -c "" -``` - -For tests: -```bash -./isaaclab.sh -p -m pytest -``` - -**Record the output carefully** — capture exit codes, error messages, and stack traces. - -### Step 3: Evaluate reproduction result - -``` -Reproduction attempted -├─ Bug reproduced at reported commit? -│ ├─ YES → Go to Step 4 (test on latest) -│ └─ NO → Go to Step 5 (comment: cannot reproduce) -``` - -### Step 4: Test on latest commit - -```bash -git checkout origin/develop - -# Restore workflow files again after switching -cp -r "$AGENT_TMPDIR/.agent" .agent 2>/dev/null || true -cp "$AGENT_TMPDIR/AGENTS.md" AGENTS.md 2>/dev/null || true -cp "$AGENT_TMPDIR/CLAUDE.md" CLAUDE.md 2>/dev/null || true -``` - -Re-run the same reproduction steps. - -``` -Bug on latest develop? -├─ YES (still reproduces) → Route to isaaclab-bug-fix skill -├─ NO (fixed on latest) → Go to Step 6 (comment: fixed, close issue) -``` - -### Step 5: Comment — Cannot Reproduce - -Post a comment explaining what was tried and asking for clarification: - -```markdown -I attempted to reproduce this issue at commit `` with the following steps: - -``` - -``` - -**Result**: The operation completed successfully without the reported error. - -
-Full output - -``` - -``` - -
- -Could you please provide more details or a minimal reproducible example? Specifically: -- The exact command or script you ran -- Your full environment details (OS, GPU, CUDA, Isaac Sim version) -- The complete error output - -This will help us narrow down environment-specific factors. -``` - -Post via: -```bash -gh issue comment --repo isaac-sim/IsaacLab --body "" -``` - -### Step 6: Comment — Fixed on Latest & Close - -```markdown -This issue appears to have been resolved on the latest `develop` branch (commit ``). - -I tested with the following steps: - -``` - -``` - -**Result**: The operation completed successfully. - -
-Full output - -``` - -``` - -
- -Closing this issue. If you still experience the problem on the latest version, please reopen with updated reproduction steps. -``` - -Post and close: -```bash -gh issue comment --repo isaac-sim/IsaacLab --body "" -gh issue close --repo isaac-sim/IsaacLab -``` - -### Step 7: Clean up - -```bash -git checkout develop # return to develop -git stash pop # restore any stashed changes (if applicable) -rm -rf "$AGENT_TMPDIR" # remove temp copy of workflow files -``` - -## Important Notes - -- **Preserve workflow files across checkouts.** `AGENTS.md`, `CLAUDE.md`, and `.agent/` may not exist on older commits. Always copy them to a temp dir before checkout and restore them after. Never stage or commit these restored files. -- Always use `./isaaclab.sh -p` instead of raw `python3` for running scripts -- Capture ALL output (stdout + stderr) for evidence -- If reproduction requires a simulator (Isaac Sim) and it's not available, note this limitation in the comment -- Be precise about which commit was tested — always include the full hash diff --git a/.agent/skills/isaaclab-issue-triage/SKILL.md b/.agent/skills/isaaclab-issue-triage/SKILL.md deleted file mode 100644 index e72a8115ae3e..000000000000 --- a/.agent/skills/isaaclab-issue-triage/SKILL.md +++ /dev/null @@ -1,82 +0,0 @@ ---- -name: isaaclab-issue-triage -description: Triage GitHub issues for the IsaacLab repo. Validates bug reports against the bug template, checks for required fields (commit, steps to reproduce), comments requesting missing info, and routes reproducible bugs to the reproduce and fix workflows. Use when asked to triage issues, check bugs, or process GitHub issues. ---- - -# IsaacLab Issue Triage - -Automated workflow to triage bug issues on `isaac-sim/IsaacLab`. - -## Prerequisites - -- `gh` CLI authenticated (`gh auth status`) -- Git repo cloned with remote `origin` pointing to `isaac-sim/IsaacLab` - -## Workflow - -### Step 1: Fetch open bug issues - -```bash -gh issue list --repo isaac-sim/IsaacLab --label bug --state open --json number,title,body,labels,comments --limit 50 -``` - -If no `--label bug` filter works, fetch all open issues and filter for `[Bug Report]` in the title or `bug` label. - -### Step 2: For each bug issue, validate the report - -Parse the issue body and check for required fields from the bug template: - -**Required fields:** -- **Steps to reproduce**: Look for `### Steps to reproduce` section with actual content (not just the template placeholder) -- **Commit hash**: Look for `### System Info` section containing `- Commit:` with an actual hash (not `[e.g. 8f3b9ca]`) - -**Decision tree:** - -``` -Issue body parsed -├─ Missing steps to reproduce AND no other useful details? -│ └─ Comment requesting steps (see "Comment: Missing Steps" below) -│ Then STOP for this issue. -├─ Has steps to reproduce but missing commit? -│ └─ Use the latest commit on `develop` branch. -│ Proceed to reproduce. -├─ Has both commit and steps? -│ └─ Proceed to reproduce. -└─ Not a bug report (feature request, question, etc.)? - └─ Skip. -``` - -### Step 3: Route to reproduction - -Follow the **isaaclab-bug-reproduce** skill with: -- The issue number -- The commit hash (from issue or latest `develop`) -- The reproduction steps extracted from the issue body - -### Comment Templates - -**Comment: Missing Steps** - -```markdown -Thank you for filing this issue. To help us investigate, could you please provide: - -1. **Minimal steps to reproduce** the bug (a small script or sequence of commands) -2. **The full error message / stack trace** (if applicable) - -These details are required per our [bug report template](https://github.com/isaac-sim/IsaacLab/blob/main/.github/ISSUE_TEMPLATE/bug.md) and are essential for us to diagnose the problem. We'll revisit this issue once the reproduction steps are available. -``` - -Post via: -```bash -gh issue comment --repo isaac-sim/IsaacLab --body "" -``` - -## Batch Processing - -When triaging multiple issues, process them sequentially. For each issue, complete the full triage cycle (validate → reproduce → fix or comment) before moving to the next. - -## References - -- Bug report template: read `.github/ISSUE_TEMPLATE/bug.md` for the expected issue fields -- Contributing guidelines: read `docs/source/refs/contributing.rst` for coding style and PR requirements -- Project rules: read `AGENTS.md` for naming, changelog, commit, and testing conventions diff --git a/AGENTS.md b/AGENTS.md index ef8d8d93d902..70c1d15158ab 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -149,67 +149,6 @@ Follow conventional commit message practices. ``` - Do not change the year in existing file headers. -## Issue Triage Workflow - -Automated pipeline for triaging, reproducing, and fixing GitHub bug reports. Trigger it for a single issue with: - -```bash -claude "Run the issue triage workflow for issue #" -``` - -The workflow chains three skills in `.agent/skills/` and follows this decision tree: - -``` -Fetch issue #N -├─ Not a bug report → Skip -├─ Missing reproduction steps (and no other useful details) -│ └─ Comment asking for steps → STOP -├─ Has reproduction steps (use latest develop if commit is missing) -│ └─ Checkout commit, run repro steps -│ ├─ Cannot reproduce -│ │ └─ Comment with what was tried, ask for details → STOP -│ └─ Reproduces -│ └─ Checkout latest develop, re-run -│ ├─ Fixed on latest -│ │ └─ Comment with evidence, close issue → STOP -│ └─ Still broken -│ └─ Create branch, fix, test, changelog, pre-commit, PR → DONE -``` - -### Skills - -| Skill | Path | Purpose | -|-------|------|---------| -| `isaaclab-issue-triage` | `.agent/skills/isaaclab-issue-triage/SKILL.md` | Fetch issue, validate bug template fields, route | -| `isaaclab-bug-reproduce` | `.agent/skills/isaaclab-bug-reproduce/SKILL.md` | Checkout commit, run repro steps, evaluate result | -| `isaaclab-bug-fix` | `.agent/skills/isaaclab-bug-fix/SKILL.md` | Branch, fix, test, changelog, pre-commit, PR | - -### Required context files - -The skills reference these repo files directly (no duplication): -- `.github/ISSUE_TEMPLATE/bug.md` — expected bug report fields -- `.github/PULL_REQUEST_TEMPLATE.md` — PR format -- `docs/source/refs/contributing.rst` — coding style and contribution process -- `AGENTS.md` (this file) — changelog, commit, naming, and testing rules - -### Running for a single issue - -When asked to triage a specific issue number, execute the full chain: - -1. **Read** `.agent/skills/isaaclab-issue-triage/SKILL.md` — fetch and validate the issue -2. If the issue is valid for reproduction, **read** `.agent/skills/isaaclab-bug-reproduce/SKILL.md` — attempt reproduction -3. If the bug still reproduces on latest, **read** `.agent/skills/isaaclab-bug-fix/SKILL.md` — implement and submit the fix - -Stop at any step that reaches a terminal state (commented, closed, or needs user input). - -### Running for all open bugs - -```bash -claude "Run the issue triage workflow for all open bug issues" -``` - -This processes each open bug issue sequentially through the full chain. - ## Sandbox & Networking - Network access (e.g., `git push`) is blocked by the sandbox. Use `dangerouslyDisableSandbox: true` so the user gets an approval prompt — don't ask them to run it manually.