---

name: github-contribution description: "Automated GitHub contribution workflow with intelligent issue discovery via positive label detection. Use when: (1) Contributing to open source projects, (2) Discovering high-value issues via maintainer-approved labels, (3) Fork synchronization and PR submission, (4) Analyzing issue quality by label signals." version: "1.6.0"

GitHub Contribution Skill

Purpose

Automated GitHub contribution workflow that handles fork synchronization, branch creation, and PR submission while maintaining clean fork state. Includes intelligent issue discovery with positive label detection.

Core Features

1. Intelligent Issue Discovery (v1.6.0)

• Positive Label Detection: Automatically identify high-value issues via maintainer-approved labels
• Priority Scoring: Rank issues by contribution value and fix feasibility
• Smart Filtering: Focus on queueable, reproducible, and high-impact issues
• Multi-Repo Support: Discover issues across multiple target repositories

2. Fork Protection & Synchronization

• Main Branch Protection: Never commit directly to main branch
• Automatic Sync: Regularly sync fork main with upstream official repository
• Clean State Enforcement: Ensure fork main branch matches official repository exactly
• Pollution Prevention: Prevent local work files from contaminating main branch

3. Automated Contribution Workflow

• Fork Setup: Automatically configure upstream remote if not exists
• Branch Creation: Create feature branches based on latest official code
• PR Submission: Handle pull request creation with proper templates
• Issue Integration: Link fixes to relevant GitHub issues

4. Safety Measures

• Pre-flight Validation: Verify fork cleanliness before starting
• Atomic Operations: All changes happen in isolated feature branches
• Rollback Support: Easy recovery if something goes wrong
• Permission Handling: Work within GitHub token permission constraints

---

🎯 Intelligent Issue Discovery (v1.6.0)

Positive Label Detection System

Modern repositories use automated labeling systems to identify high-value, maintainer-approved issues. These positive labels signal issues that are:

• ✅ Ready for contribution (queueable-fix)
• ✅ Reproducible and confirmed (source-repro)
• ✅ Impact clearly assessed (impact:*)
• ✅ Value-rated by maintainers (issue-rating:)

Golden Rule: Prioritize issues with positive labels over random bugs.

Label Categories & Priority

OpenClaw-Specific Positive Labels

OpenClaw uses ClawSweeper automation to identify high-value issues:

# ClawSweeper labels (HIGH PRIORITY - maintainer-validated)
gh issue list --repo openclaw/openclaw --label "clawsweeper:fix-shape-clear" --state open
gh issue list --repo openclaw/openclaw --label "clawsweeper:queueable-fix" --state open
gh issue list --repo openclaw/openclaw --label "clawsweeper:source-repro" --state open

# Impact assessment labels
gh issue list --repo openclaw/openclaw --label "impact:auth-provider" --state open

# Value rating labels (🦞 diamond lobster = HIGHEST VALUE)
gh issue list --repo openclaw/openclaw --label "issue-rating: 🦞 diamond lobster" --state open
gh issue list --repo openclaw/openclaw --label "issue-rating: *" --state open

ClawSweeper Label Meanings:

• clawsweeper:fix-shape-clear → Clear implementation path identified
• clawsweeper:queueable-fix → Marked as queue-able for PR work
• clawsweeper:source-repro → High-confidence source-level reproduction found
• impact:auth-provider → Auth/provider/model routing may break (critical)
• issue-rating: 🦞 diamond lobster → Highest value issue (fix immediately)

Issue Discovery Workflow

Step 1: Explore Repository Labels

# Discover all labels in the repository
gh api repos/owner/repo/labels --paginate | jq '.[].name'

# Filter for positive label patterns
gh api repos/owner/repo/labels --paginate | jq '.[].name' | \
  grep -E '(queueable|fix-shape|source-repro|impact|issue-rating|severity|priority|good-first|help-wanted|confirmed|reproducible)'

Step 2: Query Issues with Positive Labels

# Single positive label
gh issue list --repo owner/repo \
  --label "clawsweeper:queueable-fix" \
  --state open \
  --json number,title,labels,createdAt

# Multiple positive labels (OR logic)
gh issue list --repo owner/repo \
  --label "queueable-fix,fix-shape-clear,source-repro" \
  --state open \
  --json number,title,labels,createdAt

# Value-rated issues only
gh issue list --repo owner/repo \
  --label "issue-rating: *" \
  --state open \
  --json number,title,labels,createdAt

Step 3: Prioritize by Label Combination

Priority Tiers:

Step 4: Analyze & Select

# Get full issue details
gh issue view <issue-number> --repo owner/repo

# Check issue comments for context
gh issue view <issue-number> --repo owner/repo --comments

# Check if already being worked on
gh pr list --repo owner/repo --search "fixes #<issue-number>"

# Verify no existing PRs
gh pr list --repo owner/repo --state open --search "<issue-keyword>"

Multi-Repo Issue Discovery

# Search across multiple repositories
gh search issues \
  --label "queueable-fix,fix-shape-clear,source-repro" \
  --state open \
  --limit 50 \
  --json repository,title,number,url

# Target specific organizations
gh search issues \
  --owner openclaw \
  --label "impact:*" \
  --state open \
  --sort created \
  --order desc

Issue Selection Decision Matrix

Proceed if issue has:

• ✅ At least 1 positive label (queueable/reproducible/impact)
• ✅ Clear description and reproduction steps
• ✅ No existing PR addressing it
• ✅ Scope matches your expertise
• ✅ Effort fits available time

Skip if issue has:

• ❌ No positive labels (unless urgent bug)
• ❌ Unclear description or missing details
• ❌ Existing PR in progress
• ❌ Requires deep domain expertise you lack
• ❌ Breaking changes or major refactoring

Quick Issue Discovery Commands

# One-liner: Find all queueable-fix issues
gh issue list --repo openclaw/openclaw --label "clawsweeper:queueable-fix" --state open --limit 10

# Find highest value issues (diamond rated)
gh issue list --repo openclaw/openclaw --label "issue-rating: 🦞 diamond lobster" --state open

# Find reproducible issues with clear implementation path
gh issue list --repo openclaw/openclaw \
  --label "clawsweeper:source-repro,clawsweeper:fix-shape-clear" \
  --state open

# Find impact:auth issues (critical system)
gh issue list --repo openclaw/openclaw --label "impact:auth-provider" --state open

# Batch discover: All positive labels
for label in "clawsweeper:queueable-fix" "clawsweeper:fix-shape-clear" "clawsweeper:source-repro"; do
  echo "=== $label ==="
  gh issue list --repo openclaw/openclaw --label "$label" --state open --json number,title --limit 5
done

Integration with Contribution Workflow

After discovering a high-value issue:

1. Validate - Confirm issue is still open and unassigned
2. Comment - Express interest, ask clarifying questions
3. Wait - Get assigned before starting (respect maintainer process)
4. Follow Standard Workflow - Fork → Sync → Branch → Fix → PR

Pro Tip: Issues with multiple positive labels (e.g., queueable + source-repro + impact) have 90%+ merge rate because maintainers have pre-validated the fix path.

---

Usage

Basic Command

./github-contribution.sh <username> <owner/repo> <issue-number> <branch-name> [projects-root]

Examples

# Fix issue #123 in openclaw/openclaw
./github-contribution.sh Linux2010 openclaw/openclaw 123 fix/issue-description

# Specify custom project root
./github-contribution.sh Linux2010 openclaw/openclaw 456 fix/bug-fix /custom/path

Fork Protection Best Practices

Main Branch Rules

1. Never commit directly to fork's main branch
2. Always sync first before creating new branches
3. Use feature branches for all development work
4. Regular cleanup of local pollution files

Safe Synchronization Script

#!/bin/bash
# sync-fork.sh - Safe fork synchronization

git checkout main
git fetch upstream
git reset --hard upstream/main
git clean -fdx  # Remove all untracked files

# Verify clean state
if [[ $(git status --porcelain) ]]; then
    echo "❌ Warning: Working tree not clean"
    exit 1
fi
echo "✅ Fork synchronized successfully"

Local Git Configuration

# Prevent accidental main branch pushes
git config branch.main.pushRemote no_push

# Set safe push default
git config push.default nothing

Workflow Steps

Step 1: Fork Validation

• Check if fork exists and is accessible
• Verify upstream remote configuration
• Validate current fork state cleanliness

Step 2: Synchronization

• Fetch latest from upstream official repository
• Reset local main branch to match upstream exactly
• Clean any untracked/local pollution files
• Push synchronized state to fork (if permissions allow)

Step 3: Feature Branch Creation

• Create new branch from clean main
• Apply necessary changes and fixes
• Commit with proper semantic format
• Push feature branch to fork

Step 4: PR Creation

• Generate PR with complete template
• Link to relevant issue numbers
• Include proper change type and scope
• Add security impact assessment

---

🩺 Bug Fix Module: Change Plan

Before fixing any bug, always write a change plan first. This ensures minimal, safe changes and makes PR review easier.

The 5-Point Analysis

Answer these 5 questions in plain language before writing any code:

Change Plan Template

## Change Plan for Issue #<number>

1. **Observed behavior**:
   <Describe what's broken - the user-visible symptom>

2. **Expected behavior**:
   <Describe what should happen instead>

3. **Suspected root cause**:
   <Point to specific file/line/function that causes the bug>

4. **Safest seam to modify**:
   <Identify the minimal code change location - smallest safe fix>

5. **Risk surface**:
   <List what could be affected by this change>

Example: Issue #5968

## Change Plan for Issue #5968

1. **Observed behavior**:
   `extract_content_or_reasoning()` crashes when `response.choices` is None, missing, or empty list.

2. **Expected behavior**:
   Function should return empty string gracefully when no usable choices exist.

3. **Suspected root cause**:
   Line `msg = response.choices[0].message` in `agent/auxiliary_client.py` assumes choices is always non-empty.

4. **Safest seam to modify**:
   Add a guard at the top of `extract_content_or_reasoning()` before accessing choices:
   `if not getattr(response, "choices", None): return ""`

5. **Risk surface**:
   Minimal - only affects edge cases where API response is malformed.

When to Use Change Plan

Benefits of Change Plan

Change Plan Checklist

Before coding:

• Can you describe the bug in one sentence?
• Can you point to the exact line causing it?
• Is your fix the smallest possible change?
• Have you identified what else could break?
• Will this change need a regression test?

If you answered "no" to any question, do more investigation before coding.

---

Error Handling

Common Issues & Solutions

Fork Not Clean

• Problem: Local main branch has extra commits/files
• Solution: Force reset to upstream and clean untracked files

Permission Denied (Workflow Scope)

• Problem: Token lacks workflow permissions
• Solution: Use web-based PR creation or update token permissions

Upstream Not Configured

• Problem: Missing upstream remote
• Solution: Auto-add upstream remote pointing to official repository

Branch Already Exists

• Problem: Feature branch already exists
• Solution: Use unique branch naming or delete existing branch

Security Considerations

Token Permissions

• Minimum Required: repo scope
• Optional: workflow scope (for full automation)
• Never Grant: Excessive permissions beyond contribution needs

Local Security

• File Cleanup: Always clean working directory after contributions
• Credential Management: Use secure credential storage
• Audit Trail: Maintain logs of all contribution activities

Integration with Other Skills

PR Advocacy Skill

• Hand off created PRs to PR Advocacy for monitoring
• Share PR tracking information for continuous follow-up
• Coordinate review response and maintenance

Document Spell Check Skill

• Pre-validate documentation changes before PR creation
• Ensure all text content passes spell checking
• Maintain documentation quality standards

High-Quality PR Best Practices (Maximize Merge Success Rate)

🎯 Merge Success Rate Formula (Based on 30+ Merged PRs Analysis)

Merge Success Rate = 
  (PR Description Completeness × 0.2) +
  (Review Response Speed × 0.25) +
  (Test Coverage × 0.2) +
  (Conflict Resolution Status × 0.15) +
  (Review Resolution Rate × 0.2)

Target: > 80% success rate

✅ 10 Success Characteristics (Must Follow 100%)

1. ✅ Complete PR Description - Use template, fill ALL required fields
2. ✅ Fast Review Response - < 30 minutes average response time
3. ✅ Small Focused Commits - 1 commit solves 1 problem
4. ✅ 100% Test Coverage - Include edge cases and regression tests
5. ✅ Zero Conflicts - Daily rebase upstream, keep CLEAN
6. ✅ Changelog Updated - All user-visible changes
7. ✅ Security Checklist - 5 required security questions
8. ✅ Human Verification Statement - Manual test content + untested areas
9. ✅ Review Conversations Resolved - 100% resolve bot review comments
10. ✅ Rollback Plan - Rollback steps + known issues

📋 Pre-Submission Checklist

Before pushing PR:

Code Quality:

• Title format: type(scope): description
• Commit message: includes "what" + "why"
• At least 1 new test case
• CHANGELOG.md updated
• 4-7 meaningful commits

CI Pre-flight (MUST pass locally):

• pnpm protocol:check - Protocol validation
• pnpm test - All tests pass
• pnpm lint - No lint errors
• pnpm tsc --noEmit - TypeScript compilation

Review Readiness:

• Ready to respond within 24h
• Greptile/Aisle Security comments addressed
• Security questions answered (5 required)

📊 High Success Rate PR Patterns

Pattern 1: Security Fix Response (vincentkoc #44437)

7 commits in same day:
1. Main fix implementation
2. Changelog update
3. Merge main (resolve conflicts)
4. Tests: add coverage for review comments
5. Fix: address Greptile suggestions
6. Extra hardening (defensive programming)
7. Merge main (final sync)

Key Learnings:

• ✅ Separate commits for review responses
• ✅ Tests and docs as separate commits
• ✅ Frequent merge main to resolve conflicts
• ✅ Extra hardening shows professionalism

Pattern 2: Security Report Response (gumadeiras #44176)

When Aisle Security reports issues:

1. Quote SECURITY.md to explain why it's out of scope
2. But still fix it (defensive programming)
3. List specific hardening done
4. Provide verification commands

Key Learnings:

• ✅ Respond to security reports first
• ✅ Explain scope判断 basis
• ✅ Still fix it (show cooperation)
• ✅ Provide verification method

⚠️ Common Mistakes That Reduce Merge Rate

🎯 Quality Metrics

📝 PR Template Best Practices

Title Format:

✅ fix(hooks): fail closed on unreadable loader paths
✅ feat(context-engine): plumb sessionKey into all methods
✅ docs: codify American English spelling convention
✅ security: include accountId in session keys

Commit Message Structure:

First line: What was done (concise description)

Second paragraph: Why (problem background, impact)

Optional: Regeneration-Prompt / AI assistance notes

Example (#44411):

fix(ci): restore generated protocol swift outputs

Regenerate the Swift protocol models so PushTestResult keeps the 
transport field required by the current gateway schema, and update 
protocol:check to diff both generated Swift destinations because 
the generator writes both files.

Regeneration-Prompt: |
  Investigate the protocol CI failure on current origin/main...

---

Best Practices

For Contributors

• Always start from clean, synchronized main branch
• Use descriptive branch names following convention
• Fill complete PR templates with all required fields
• Test changes locally before pushing
• Always rebase on the original PR branch (never create new branches for rebase)
• Follow High-Quality PR Best Practices (see section above)

PR Rebase Best Practices (Critical!)

Golden Rule: Always rebase on the original PR branch, never create a new branch.

Correct Rebase Workflow

# 1. Confirm current branch
git branch --show-current

# 2. Confirm PR's branch name
gh pr view <PR-number> --json headRefName --jq .headRefName

# 3. Switch to correct branch if needed
git checkout <PR-branch-name>

# 4. Rebase on the SAME branch (do NOT create new branch)
git fetch upstream
git rebase upstream/main

# 5. Push to the SAME branch
git push -f origin <same-branch-name>

Common Mistakes to Avoid

Why This Matters?

1. Clean branch history - No duplicate branches created
2. Avoid confusion - PR always linked to same branch
3. Reduce errors - Won't push to wrong branch
4. Easy management - All changes in one place

Pre-Rebase Checklist

Before rebasing:

• Run git branch --show-current to confirm current branch
• Run gh pr view <num> --json headRefName to confirm PR branch
• Ensure both names match before proceeding
• If mismatch, git checkout <PR-branch> first

Post-Rebase Checklist

After rebasing:

• Run git log --oneline -3 to verify commits
• Run pnpm test or relevant tests
• Run git push -f origin <branch> to update PR

Example: Rebase PR #48568

# Check current branch
$ git branch --show-current
fix/47752-final  # ✅ Correct!

# Confirm PR branch
$ gh pr view 48568 --json headRefName --jq .headRefName
fix/47752-final  # ✅ Matches!

# Rebase on same branch
git fetch upstream
git rebase upstream/main

# Test
pnpm test src/infra/heartbeat-runner.timeout.test.ts

# Push to same branch
git push -f origin fix/47752-final

Troubleshooting

Problem: Accidentally created new branch during rebase

Solution:

# Go back to original branch
git checkout <original-branch>

# Rebase there instead
git rebase upstream/main

# Delete the accidental branch
git branch -D <accidental-branch>

# Push to original branch
git push -f origin <original-branch>

---

For Maintainers

• Regularly audit fork cleanliness
• Update synchronization scripts as needed
• Monitor token permissions and security
• Document contribution workflows for team members

Limitations

GitHub Fork Restrictions

• Cannot set full branch protection rules on forks
• Limited automation capabilities without workflow permissions
• Manual intervention sometimes required for complex scenarios

Workarounds

• Use local git hooks for additional protection
• Implement manual verification steps in workflow
• Leverage GitHub web interface for final PR creation when needed

Maintenance

Updates

• Regular script updates for new GitHub API changes
• Security patches for authentication methods
• Performance improvements for large repositories

Monitoring

• Track success/failure rates of contribution attempts
• Monitor GitHub API rate limit usage
• Collect user feedback for workflow improvements