.agents/skills/openclaw-bugfix-pr/SKILL.md

name	description
openclaw-bugfix-pr	Find, fix, validate, and ship focused bug-fix pull requests for the openclaw/openclaw repository. Use when asked to “find a bug,” “fix this regression,” “open a PR,” “watch CI,” or do end-to-end contribution work from triage through green checks in OpenClaw.

OpenClaw Bugfix PR

Overview

Execute a full bug-fix contribution loop in openclaw/openclaw: pick a real bug, reproduce it, implement a minimal fix, validate with tests, open a clean PR, and monitor CI to completion.

Work pragmatically and keep scope tight. Prefer one bug, one root cause, one focused commit.

Workflow

1) Establish Safe Working Context

• Confirm repository and branch state before edits.
• Respect existing unrelated changes; do not revert work you did not make.
• Read repository AGENTS.md instructions first.

Use:

git status -sb
git branch --show-current
git remote -v

2) Pick a Real Bug

• Prefer active, concrete bugs from GitHub issues.
• If issue triage is unavailable, find a reproducible local defect with existing tests.
• Choose bugs with clear expected vs actual behavior.

Useful triage commands:

gh search issues --repo openclaw/openclaw --state open --label bug --limit 20 --json number,title,url,updatedAt

If gh issue view fails, fetch via API:

gh api repos/openclaw/openclaw/issues/<number>

3) Reproduce Before Fixing

• Reproduce with a targeted test whenever possible.
• Add or adjust one regression test that fails on current code.
• Keep reproduction deterministic and small.

4) Implement Minimal Fix

• Fix root cause, not symptoms.
• Prefer existing code paths/patterns over new abstractions.
• Keep changes surgical and readable.
• Add brief comments only where logic is non-obvious.

5) Validate Thoroughly but Efficiently

• Run the exact failing test first.
• Run adjacent suites affected by the change.
• If dependencies are missing, install once and rerun the exact command.

Typical sequence:

pnpm vitest run <targeted-test-file>
pnpm vitest run <related-suite-1> <related-suite-2>

6) Commit Correctly

• Use repository-required committer script.
• Keep commit message concise and action-oriented.
• Commit only relevant files.

scripts/committer "Tools: fix <concise bug description>" <file1> <file2>

7) Push and Open PR

• Push to upstream if permitted.
• If upstream push fails (403), push to user fork and open PR from fork branch.
• Reference the issue in PR summary.

Push pattern:

git push origin HEAD:refs/heads/<branch>
# fallback
git remote add fork https://github.com/<user>/<fork>.git
git push fork HEAD:refs/heads/<branch>

Create PR with heredoc body (avoid shell escaping issues):

gh pr create --repo openclaw/openclaw --base main --head <user>:<branch> --title "<title>" -F - <<'EOPR'
## Summary
- ...

## Problem
Fixes #<issue>

## Validation
- `pnpm vitest run ...`
EOPR

8) Monitor CI to Green

• Watch checks until completion.
• Report failures immediately with job URL and first actionable error.
• If all pass, report success and stop.

gh pr checks <pr-number> --repo openclaw/openclaw
gh pr checks <pr-number> --repo openclaw/openclaw --watch --interval 15

9) Communicate Clearly and Graciously

• Be concise and respectful.
• Summarize: bug fixed, files changed, test evidence, PR URL, CI state.
• If blocked, state exact blocker and next action.

OpenClaw-Specific Guardrails

• Use repo-root relative file references in chat.
• Use rg for code search.
• Never use destructive git commands unless explicitly requested.
• Do not use gh issue/pr comment -b "..." for complex bodies; use heredoc.
• Before security advisory triage/severity decisions, read SECURITY.md.
• Keep channel/plugin impact in mind when touching shared routing/session logic.

Done Criteria

• A real bug is identified and reproducible.
• Regression test fails before fix and passes after fix.
• Related suites pass.
• Commit is scoped and clean.
• PR is opened with validation evidence.
• CI status is monitored and reported.