---
name: openclaw-bugfix-pr
description: 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:
```bash
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:
```bash
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:
```bash
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:
```bash
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.

```bash
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:
```bash
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):
```bash
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.

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