DexForce/EmbodiChain / .agents/skills/pr
pr
VerifiedCreate single or stacked pull requests for EmbodiChain following the project's PR template and conventions, including proportional validation, dependency ordering, and proper GitHub repository labels
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 15.1 KB |
| agents/openai.yaml | config | 75 B |
SKILL.md
View on GitHub---
name: pr
description: Create single or stacked pull requests for EmbodiChain following the project's PR template and conventions, including proportional validation, dependency ordering, and proper GitHub repository labels
---
# EmbodiChain Pull Request Creator
This skill guides you through creating a pull request that follows the EmbodiChain project's PR template and contribution guidelines.
## Usage
Invoke this skill when:
- You have completed a feature, bug fix, or other change and want to create a PR
- You want to split a large, dependency-ordered change into stacked PRs
- You want to ensure the PR follows the project's conventions
- You need help drafting a proper PR description
## Steps
### 1. Check Current State
First, check the current git status and changes:
```bash
git status
git diff HEAD
```
### 2. Determine Change Type
Based on the changes made, select one of these PR types:
- **Bug fix** - Non-breaking change which fixes an issue
- **Enhancement** - Non-breaking change which improves an existing functionality
- **New feature** - Non-breaking change which adds functionality
- **Breaking change** - Existing functionality will not work without user modification
- **Documentation update**
### 3. Draft the PR Description
Write a description that includes:
- **Summary**: A clear, concise summary of the change
- **Issue reference**: Which issue is fixed (e.g., "Fixes #123")
- **Motivation and context**: Why this change is needed
- **Dependencies**: List any dependencies required for this change
### 4. Review Test Necessity and Select Proportional Validation
Before validation and publication, apply the shared
[test necessity review](../add-test/SKILL.md#test-necessity-review). Inspect the
full proposed PR delta from the merge base with its intended target branch,
plus staged, unstaged, and untracked changes to be included. `git diff HEAD`
alone misses committed additions. Include new or extended cases and supporting
fixtures in existing files, not only newly added test files.
Within the task's authorized scope, remove or merge confirmed redundant
additions and simplify unjustified implementation coupling. Limit cleanup to
this change and preserve explicitly requested scenarios. Run the affected tests
after any edits. Briefly state the coverage basis and any meaningful cleanup in
the PR's validation summary, including existing coverage when no new tests are
needed; do not create a per-test justification ledger.
Inspect the changed files and validate only the affected behavior. Do not run the
full test suite automatically.
- Workflow-only changes: run `actionlint` on the changed workflows and any
directly related workflow-script tests.
- Documentation-only changes: run the relevant docs checks or build; do not run
Python tests unless executable examples or docs tooling changed.
- Isolated Python changes: run the nearest matching test module or package.
- Shared infrastructure or cross-package changes: run affected package tests and
focused integration tests.
- Run the full suite only for broad cross-cutting changes, global dependency or
test-configuration changes, release-critical changes that cannot be validated
narrowly, or when the user explicitly requests it.
If a validation command is likely to take more than two minutes, state why it is
needed before starting it. Honor an explicit user request to skip or narrow tests,
and record skipped checks honestly in the PR description.
Use the `pre-commit-check` skill for the detailed selection and reporting rules.
### 5. Run Code Formatting
Before creating the PR, ensure code is formatted:
```bash
black .
```
If formatting changes were made, commit them first:
```bash
git add -A
git commit -m "Format code with black"
```
Then run the read-only public API documentation gate used by CI:
```bash
python docs/scripts/check_api_docs.py
```
If it reports missing public exports, invoke `$update-api-docs` to generate or
update the relevant Sphinx entries and descriptions, then rerun the checker.
Keep generation in that specialized skill; do not add placeholder API docs in
the PR workflow merely to make the gate pass.
### 6. Create or Update Branch
For a single PR, create a feature branch if needed:
```bash
git checkout -b <branch-name>
```
Recommended branch naming:
- `fix/<description>` - for bug fixes
- `feat/<description>` - for new features
- `enhance/<description>` - for enhancements
- `docs/<description>` - for documentation changes
For a large change that can be split into small, dependency-ordered layers,
follow the [Stacked Pull Request Workflow](#stacked-pull-request-workflow)
instead of steps 6 through 9. Keep unrelated or independent changes in separate
PRs rather than forcing them into a stack.
### 7. Commit Changes
Commit with a clear message following conventional commits format:
```bash
git commit -m "type(scope): brief description
Detailed description of the change."
```
### 8. Push to Remote
```bash
git push -u origin <branch-name>
```
### 9. Create the PR
Use the gh CLI with the proper PR template:
```bash
gh pr create --title "<PR Title>" --body "<PR Body>"
```
### Stacked Pull Request Workflow
Use a stack when later changes depend on earlier changes but each layer can be
reviewed as a focused PR. Put shared types, schemas, and other foundations in
lower layers; put their dependents in higher layers. Keep every branch and PR in
the same repository because GitHub does not support cross-fork stacks. If the
contribution must come from a fork, use a single PR or separate non-stacked PRs.
> [!NOTE]
> GitHub stacked pull requests are in public preview and may change. They are
> available on GitHub, GitHub Mobile, and through the `gh stack` extension,
> but not in GitHub Desktop.
#### 1. Install and Authenticate the CLI
Use GitHub CLI 2.90.0 or later and Git 2.20 or later. Authenticate, then install
the official extension if it is not already installed:
```bash
gh auth login
gh extension install github/gh-stack
```
#### 2. Design the Stack
Define the trunk and order the layers from foundational to dependent. The
bottom PR targets the trunk, usually `main`, and each PR above it targets the
branch immediately below it:
```text
feat/ui -> PR #3 (base: feat/api) <- top
feat/api -> PR #2 (base: feat/core)
feat/core -> PR #1 (base: main) <- bottom
main <- trunk
```
Ensure each PR contains only the diff for its layer. If code in one layer
depends on another, place the dependency in the same layer or a lower layer.
#### 3. Create and Commit the Layers
Initialize the bottom branch, commit its focused change, then add branches from
the bottom upward:
```bash
gh stack init --base main feat/core
# Make, stage, validate, and commit the foundational change.
gh stack add feat/api
# Make, stage, validate, and commit the dependent API change.
gh stack add feat/ui
# Make, stage, validate, and commit the dependent UI change.
gh stack view
```
Apply the test necessity review and proportional validation in step 4 to every
affected layer, using that layer's own target branch as its base. Keep the
commits and working tree for each layer complete before adding the next branch.
#### 4. Publish or Update the Stack
Use the interactive submit flow so each PR can receive an EmbodiChain title and
body. This command pushes the branches, creates or updates their PRs, and links
them as a stack:
```bash
gh stack submit
```
Use `gh stack push` only when the branches should be pushed without creating or
updating PRs. Use `gh stack submit --auto` only when generated titles and draft
PRs are acceptable; add `--open` to make them ready for review.
After the remote stack or trunk changes, synchronize the entire chain:
```bash
gh stack sync
```
After amending a lower layer, cascade the new commit history through its
dependents, then update the remote PRs:
```bash
gh stack rebase --no-trunk
gh stack submit
```
If a rebase stops on conflicts, resolve and stage them, then run
`gh stack rebase --continue`; use `gh stack rebase --abort` to restore the
pre-rebase state. Preserve the dependency order and rerun validation for every
affected layer before submitting again.
#### 5. Describe Every Layer
Apply the standard PR template to every PR and add this stack context near the
top of each description:
```markdown
## Stack
- Layer: <position>/<total>
- Base: `<base-branch>`
- Depends on: <lower PR URL or "none">
- Followed by: <upper PR URL or "none">
```
Explain what can be reviewed in that layer and report its validation separately.
Use `Fixes #<issue>` only on the layer whose independent merge resolves the
issue; use `Refs #<issue>` on prerequisite layers. Apply appropriate repository
labels to every PR in the stack.
#### 6. Review and Merge
Review every layer independently. GitHub applies the trunk's merge requirements,
branch protections, CODEOWNER approvals, and applicable PR-triggered CI checks
to every layer, including PRs that do not directly target the trunk.
Merge from the bottom upward:
- Merge the top PR to land the entire stack.
- Merge a middle PR to land it and every lower layer; higher PRs remain open and
GitHub automatically rebases and retargets them.
- Merge the bottom PR to land only the first layer.
Use `gh stack merge` to select and merge the desired portion. The operation is
all-or-nothing for the selected layers and cannot bypass merge requirements:
```bash
gh stack merge
```
### 10. Select and Apply Labels
After creating the PR, select proper labels from the repository label list and apply them.
First, list available labels:
```bash
gh label list --limit 100
```
Then choose labels based on change type and scope. Typical mapping:
- Bug fix: `bug`
- Improvement to an existing capability: `enhancement`
- New feature: `feature`
- Documentation update: `docs`
- Structural change: `refactor`; performance work: `performance`
- Add `breaking` for user-visible incompatible changes, independently of change type.
- Select the affected areas from the current repository labels. Preserve the
exact label `motion gen` for motion planning, generation, retiming and expansion.
Keep these ownership boundaries explicit:
- `task`: concrete tasks, deployments and objectives; `task-program`: language,
semantics, compiler, runtime and integrations; `gym`: environment framework.
- `atomic-skill`: Atomic Skill contracts and execution; `kinematics`: FK/IK,
Jacobians and reachability; `physics`: dynamics and physics solvers.
- `gen-sim`: scene generation/editing and SimReady; `scene`: shared scene
composition/layout/state services; `assets`: resource files and catalogs;
`sim-object`: runtime simulation entities and their lifecycle.
- `data-pipeline`: collection, ODS, sampling, recording, persistence, conversion
and analysis. The former `data` and `dataset` labels are consolidated here.
- `model`: model architectures, inference and weights; `sl` and `rl`: the
corresponding training systems; `compute`: shared numerical algorithms.
- `agent`: runtime agents, MLLM and MCP integration; `devtools`: repository
development skills, agent context and contribution tooling.
- `rendering`: image generation and renderer behavior; `visualization`: viewers,
markers, previews and interactive debugging. Use these instead of `interaction`.
- `benchmark`: evaluation protocols, suites, metrics and reports; `performance`:
optimization work. Use both when both scopes change.
- `dexsim`: SDK interfaces and version integration, rather than every simulation
change; `robot`, `sensor` and `toolkit`: their corresponding runtime/tool owners.
Use `ci` for build/release automation and `dependencies` for dependency changes.
Apply `skip-release-notes` only when explicitly excluding the change from release
notes. Draft state and dependency links describe PR progress; area labels do not
claim that a planned capability has shipped.
Apply labels to the PR:
```bash
gh pr edit <pr-number> --add-label "bug" --add-label "gym"
```
If needed, remove incorrect labels:
```bash
gh pr edit <pr-number> --remove-label "<label-name>"
```
## PR Template
Use this template for the PR body:
```markdown
## Description
<!-- Clear summary of the change -->
This PR [briefly describe what the PR does].
<!-- Include motivation and context if needed -->
[Add any relevant motivation and context here].
<!-- List dependencies if applicable -->
Dependencies: [list any dependencies required]
<!-- Reference the issue -->
Fixes #<issue-number>
## Type of change
<!-- Select one and delete the others -->
- [x] Bug fix (non-breaking change which fixes an issue)
- [ ] Enhancement (non-breaking change which improves an existing functionality)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (existing functionality will not work without user modification)
- [ ] Documentation update
## Screenshots
<!-- Attach before/after screenshots if applicable -->
## Checklist
- [x] I have run the `black .` command to format the code base.
- [ ] I reviewed affected documentation and agent context, updated it where needed, or explained why no update was needed.
- [ ] Public API changes are reflected in the API docs (`python docs/scripts/check_api_docs.py`), if applicable
- [ ] I verified appropriate behavioral coverage, reviewed the necessity of added or extended tests, and explained when no new tests were needed.
- [ ] Dependencies have been updated, if applicable.
```
## PR Title Guidelines
- Keep titles short (under 70 characters)
- Use present tense and imperative mood
- Examples:
- "Fix KeyError when 'add' mode not present in observation_manager"
- "Add support for XYZ sensor"
- "Improve contact sensor data buffer"
## Quick Reference
| Command | Purpose |
|---------|---------|
| `git status` | Check current state |
| `git diff HEAD` | Show changes |
| `black .` | Format code |
| `python docs/scripts/check_api_docs.py` | Check public API documentation coverage |
| `git checkout -b branch-name` | Create branch |
| `git push -u origin branch` | Push to remote |
| `gh pr create` | Create PR |
| `gh stack init --base main branch` | Initialize a stack and its bottom branch |
| `gh stack add branch` | Add a branch above the current top layer |
| `gh stack view` | Show stack order and PR state |
| `gh stack submit` | Push branches and create or update stacked PRs |
| `gh stack sync` | Fetch, cascade rebase, push, and synchronize the stack |
| `gh stack rebase --no-trunk` | Cascade a lower-layer update through the stack |
| `gh stack merge` | Merge a selected portion or the entire stack |
| `gh label list --limit 100` | List repository labels |
| `gh pr edit <pr-number> --add-label ...` | Apply labels to PR |
## Notes
- Keep PRs small and focused. Large PRs are harder to review and merge.
- It's recommended to open an issue and discuss the design before opening a large PR.
- The checklist in the PR template should be completed honestly.
- For current stacked PR behavior, consult the [public preview announcement](https://github.blog/changelog/2026-07-30-stacked-pull-requests-are-now-in-public-preview/),
[GitHub stacked PR overview](https://docs.github.com/en/pull-requests/get-started/about-stacked-prs),
and [CLI command reference](https://docs.github.com/en/pull-requests/reference/stacked-prs-cli-commands).
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |