{"id":"6e3d300c-beb2-4426-b65b-873163db589b","entityType":"agent","slug":"clawhub-linux2010-github-contribution","name":"Github Contribution","canonicalUrl":"https://www.xpersona.co/agent/clawhub-linux2010-github-contribution","canonicalPath":"/agent/clawhub-linux2010-github-contribution","generatedAt":"2026-10-09T13:07:28.867Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"editorial-content","verified":true,"confidence":"high","updatedAt":"2026-10-09T10:52:30.035Z","emptyReason":null},"description":"Automated GitHub contribution workflow with intelligent issue discovery via positive label detection. Use when: (1) Contributing to open source projects, (2)... Skill: Github Contribution Owner: linux2010 Summary: Automated GitHub contribution workflow with intelligent issue discovery via positive label detection. Use when: (1) Contributing to open source projects, (2)... Tags: contribution:1.0.3, fork:1.0.3, github:1.0.3, github, contribution, opensource, pr:1.0.0, latest:1.7.4, protection:1.0.3 Version history: v1.7.4 | 2026-07-23T15:45:59.174Z | auto GitHub Contribution S","descriptionLabel":"Technical summary","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 2.9K downloads reported by the source. Last updated 10/9/2026.","installCommand":"clawhub skill install s1751dhnzp0ph63jb85dgvkztd83hhdp:github-contribution","sourceUrl":"https://clawhub.ai/linux2010/github-contribution","homepage":"https://clawhub.ai/linux2010/skills/github-contribution","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/linux2010/github-contribution","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/linux2010/skills/github-contribution","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":57,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"Automated GitHub contribution workflow with intelligent issue discovery via positive label detection. Use when: (1) Contributing to open source projects, (2)..."},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-09T10:52:30.035Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T10:52:30.035Z","emptyReason":null},"stars":null,"forks":null,"downloads":2895,"packageName":null,"latestVersion":"1.7.4","tractionLabel":"2.9K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T10:52:30.035Z","emptyReason":null},"lastUpdatedAt":"2026-10-09T10:52:30.035Z","lastCrawledAt":"2026-10-09T10:52:30.035Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-10T10:52:30.035Z","lastVerifiedAt":null,"highlights":[{"version":"1.7.4","createdAt":"2026-07-23T15:45:59.174Z","changelog":"## GitHub Contribution Skill v1.7.4 - Updated documentation in SKILL.md: references to v1.7.0/v1.7.2 unified/minor text changes; descriptions and workflow steps clarified. - Bumped version and metadata in _meta.json and skill.json for release. - No changes to workflows or core logic; update is documentation/metadata only.","fileCount":7,"zipByteSize":22280},{"version":"1.7.3","createdAt":"2026-07-23T15:45:27.579Z","changelog":"Version 1.7.3 of the GitHub Contribution Skill - Maintenance release with no file changes detected. - All features, workflows, and documentation remain unchanged from the previous version.","fileCount":7,"zipByteSize":22072},{"version":"1.7.2","createdAt":"2026-07-23T15:43:17.013Z","changelog":"- Corrected documentation version references from v1.7.2 to v1.7.0 in SKILL.md to match implemented features. - No functional or code changes; update is documentation-only. - Metadata files (_meta.json, skill.json) updated to reflect the new version number.","fileCount":7,"zipByteSize":22284},{"version":"1.7.1","createdAt":"2026-07-23T15:40:23.234Z","changelog":"- Added live-proof-cases.md to provide actionable guidance for passing automated code review. - Removed skill-card.md for simplified documentation structure. - Updated SKILL.md: Clarified workflow purpose and added live-proof integration references. - Improved and reorganized documentation for easier issue discovery and contribution workflow. - Updated metadata files (_meta.json, skill.json) for version 1.7.1.","fileCount":7,"zipByteSize":22205},{"version":"1.7.0","createdAt":"2026-07-23T15:38:05.123Z","changelog":"# github-contribution v1.7.0 Changelog - Added live-proof-cases.md to provide live-proof guidance for passing automated code review. - Expanded documentation in SKILL.md to describe new live-proof workflow integration. - Updated all metadata and configuration files for version 1.7.0. - Removed deprecated skill-card.md file. - Improved contribution workflow docs and clarified positive label detection logic.","fileCount":7,"zipByteSize":22199},{"version":"1.6.0","createdAt":"2026-06-21T05:32:11.237Z","changelog":"No changes detected in this version. - Version number remains at 1.6.0. - No file modifications were made. - All features and documentation are unchanged.","fileCount":6,"zipByteSize":14804},{"version":"1.5.1","createdAt":"2026-06-21T05:31:43.945Z","changelog":"**GitHub Contribution Skill v1.5.1 Changelog** - Added intelligent issue discovery using positive label detection for high-value, maintainer-approved issues (v1.6.0). - Documented label-driven priority system and commands for finding and filtering contributor-friendly GitHub issues. - Updated usage docs to reflect improved multi-repo and queueable issue discovery capabilities. - Improved and expanded documentation; migrated changelog and documentation structure. - Removed redundant documentation file (`skill-card.md`).","fileCount":6,"zipByteSize":14875},{"version":"1.5.0","createdAt":"2026-06-21T03:12:48.641Z","changelog":"Add Real Behavior Proof guide with examples from merged PRs (#94337, #94574, #93949)","fileCount":6,"zipByteSize":14889}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s1751dhnzp0ph63jb85dgvkztd83hhdp:github-contribution","setupComplexity":"low","setupSteps":["Setup complexity is classified as HIGH. You must provision dedicated cloud infrastructure or an isolated VM. Do not run this directly on your local workstation.","Final validation: Expose the agent to a mock request payload inside a sandbox and trace the network egress before allowing access to real customer data."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-linux2010-github-contribution/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-linux2010-github-contribution/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-linux2010-github-contribution/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-linux2010-github-contribution/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-linux2010-github-contribution/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-linux2010-github-contribution/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-09T13:07:28.862Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-linux2010-github-contribution/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-linux2010-github-contribution/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-linux2010-github-contribution/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-linux2010-github-contribution/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"high","updatedAt":"2026-10-09T10:52:30.035Z","emptyReason":null},"readme":"Skill: Github Contribution\n\nOwner: linux2010\n\nSummary: Automated GitHub contribution workflow with intelligent issue discovery via positive label detection. Use when: (1) Contributing to open source projects, (2)...\n\nTags: contribution:1.0.3, fork:1.0.3, github:1.0.3, github, contribution, opensource, pr:1.0.0, latest:1.7.4, protection:1.0.3\n\nVersion history:\n\nv1.7.4 | 2026-07-23T15:45:59.174Z | auto\n\n## GitHub Contribution Skill v1.7.4\n\n- Updated documentation in SKILL.md: references to v1.7.0/v1.7.2 unified/minor text changes; descriptions and workflow steps clarified.\n- Bumped version and metadata in _meta.json and skill.json for release.\n- No changes to workflows or core logic; update is documentation/metadata only.\n\nv1.7.3 | 2026-07-23T15:45:27.579Z | auto\n\nVersion 1.7.3 of the GitHub Contribution Skill\n\n- Maintenance release with no file changes detected.\n- All features, workflows, and documentation remain unchanged from the previous version.\n\nv1.7.2 | 2026-07-23T15:43:17.013Z | auto\n\n- Corrected documentation version references from v1.7.2 to v1.7.0 in SKILL.md to match implemented features.\n- No functional or code changes; update is documentation-only.\n- Metadata files (_meta.json, skill.json) updated to reflect the new version number.\n\nv1.7.1 | 2026-07-23T15:40:23.234Z | auto\n\n- Added live-proof-cases.md to provide actionable guidance for passing automated code review.\n- Removed skill-card.md for simplified documentation structure.\n- Updated SKILL.md: Clarified workflow purpose and added live-proof integration references.\n- Improved and reorganized documentation for easier issue discovery and contribution workflow.\n- Updated metadata files (_meta.json, skill.json) for version 1.7.1.\n\nv1.7.0 | 2026-07-23T15:38:05.123Z | auto\n\n# github-contribution v1.7.0 Changelog\n\n- Added live-proof-cases.md to provide live-proof guidance for passing automated code review.\n- Expanded documentation in SKILL.md to describe new live-proof workflow integration.\n- Updated all metadata and configuration files for version 1.7.0.\n- Removed deprecated skill-card.md file.\n- Improved contribution workflow docs and clarified positive label detection logic.\n\nv1.6.0 | 2026-06-21T05:32:11.237Z | auto\n\nNo changes detected in this version.\n\n- Version number remains at 1.6.0.\n- No file modifications were made.\n- All features and documentation are unchanged.\n\nv1.5.1 | 2026-06-21T05:31:43.945Z | auto\n\n**GitHub Contribution Skill v1.5.1 Changelog**\n\n- Added intelligent issue discovery using positive label detection for high-value, maintainer-approved issues (v1.6.0).\n- Documented label-driven priority system and commands for finding and filtering contributor-friendly GitHub issues.\n- Updated usage docs to reflect improved multi-repo and queueable issue discovery capabilities.\n- Improved and expanded documentation; migrated changelog and documentation structure.\n- Removed redundant documentation file (`skill-card.md`).\n\nv1.5.0 | 2026-06-21T03:12:48.641Z | user\n\nAdd Real Behavior Proof guide with examples from merged PRs (#94337, #94574, #93949)\n\nv1.4.0 | 2026-04-11T09:17:58.284Z | auto\n\n**Summary:**  \nIntroduces a structured bug fix \"change plan\" module, requiring explicit pre-coding analysis to improve PR quality and review speed.\n\n- Added \"Bug Fix Module: Change Plan\" section with a 5-point analysis template for bug fixes.\n- Mandates creating a change plan (problem definition, cause, risk analysis) before any code for bugs or UX issues.\n- Provides clear checklists and examples illustrating minimal and safe fix workflows.\n- No changes to core workflows, commands, or integration points.\n- Documentation now enforces better process for safer, faster, and more understandable contributions.\n\nv1.3.0 | 2026-03-21T05:07:21.225Z | user\n\nAdd High-Quality PR Best Practices - merge success rate formula, 10 success characteristics, pre-submission checklist, and patterns from 30+ merged PRs analysis\n\nv1.2.0 | 2026-03-21T04:35:22.651Z | user\n\nAdd PR Rebase Best Practices - critical guidance on always rebasing on original PR branch, never create new branches\n\nv1.1.0 | 2026-03-14T07:26:53.699Z | user\n\nAdded automation workflow for PR creation with gh CLI, workflow token auth, rebase sync, and high-quality PR standards from #45707实战经验\n\nv1.0.3 | 2026-03-03T14:15:47.661Z | auto\n\n- Major update: Modernized and automated the GitHub contribution workflow documentation.\n- Consolidated and simplified all instructions into a single SKILL.md for clarity.\n- Introduced fork protection, automatic synchronization, and clean-state enforcement practices.\n- Added guidance on command usage, error handling, security, and integration with related skills.\n- Removed deprecated and duplicate files for a streamlined codebase.\n\nv1.0.2 | 2026-03-03T11:41:01.155Z | auto\n\n- Updated documentation with simplified, step-by-step instructions for the GitHub contribution workflow in Chinese.\n- Added support and instructions for submitting Pull Requests via Chrome browser.\n- Reorganized and expanded troubleshooting, checklist, and workflow best practices sections.\n- Migrated and restructured reference and package management files.\n- Removed legacy documentation and metadata files.\n\nv1.0.1 | 2026-03-03T11:29:58.091Z | auto\n\nSummary: Major refactor to simplify structure, automate workflow, and improve usability.\n\n- Reorganized files; removed legacy and duplicate files, keeping only current essentials.\n- Consolidated documentation into a new, simplified SKILL.md with step-by-step usage, features, best practices, and troubleshooting.\n- Added machine-readable skill definition (skill.json) and standalone workflow guide (github-contribution-workflow.md).\n- Automated the GitHub contribution process: forking, cloning, syncing, branching, and PR creation, with robust error handling.\n- Clarified tool dependencies and required GitHub CLI authentication for streamlined setup.\n\nv1.0.0 | 2026-03-02T06:21:02.845Z | user\n\nInitial release: Complete GitHub contribution workflow for open source projects including fork, sync, development, and PR submission with Chrome browser support.\n\nArchive index:\n\nArchive v1.7.4: 7 files, 22280 bytes\n\nFiles: _meta.json (138b), github-contribution-workflow.md (4039b), live-proof-cases.md (12856b), scripts/github-contribution.sh (3565b), skill-card.md (2457b), skill.json (535b), SKILL.md (25843b)\n\nFile v1.7.4:SKILL.md\n\n# GitHub Contribution Skill\n\n## Purpose\nAutomated GitHub contribution workflow with intelligent issue discovery via positive label detection. Handles fork synchronization, branch creation, PR submission while maintaining clean fork state, and provides live-proof guidance for passing automated code review.\n\n## Core Features\n\n### 1. Intelligent Issue Discovery (v1.7.2)\n- **Positive Label Detection**: Automatically identify high-value issues via maintainer-approved labels\n- **Priority Scoring**: Rank issues by contribution value and fix feasibility\n- **Smart Filtering**: Focus on queueable, reproducible, and high-impact issues\n- **Multi-Repo Support**: Discover issues across multiple target repositories\n\n### 2. Fork Protection & Synchronization\n- **Main Branch Protection**: Never commit directly to main branch\n- **Automatic Sync**: Regularly sync fork main with upstream official repository  \n- **Clean State Enforcement**: Ensure fork main branch matches official repository exactly\n- **Pollution Prevention**: Prevent local work files from contaminating main branch\n\n### 3. Automated Contribution Workflow\n- **Fork Setup**: Automatically configure upstream remote if not exists\n- **Branch Creation**: Create feature branches based on latest official code\n- **PR Submission**: Handle pull request creation with proper templates\n- **Issue Integration**: Link fixes to relevant GitHub issues\n\n### 4. Safety Measures\n- **Pre-flight Validation**: Verify fork cleanliness before starting\n- **Atomic Operations**: All changes happen in isolated feature branches\n- **Rollback Support**: Easy recovery if something goes wrong\n- **Permission Handling**: Work within GitHub token permission constraints\n\n## 🎯 Intelligent Issue Discovery (v1.7.2)\n\n### Positive Label Detection System\n\nModern repositories use automated labeling systems to identify **high-value, maintainer-approved issues**. These **positive labels** signal issues that are:\n\n- ✅ Ready for contribution (`queueable-fix`)\n- ✅ Reproducible and confirmed (`source-repro`)\n- ✅ Impact clearly assessed (`impact:*`)\n- ✅ Value-rated by maintainers (`issue-rating:`)\n\n**Golden Rule**: Prioritize issues with positive labels over random bugs.\n\n### Label Categories & Priority\n\n| Category | Label Pattern | Meaning | Priority |\n|----------|-------------|---------|----------|\n| Queueable | `*:queueable-fix`, `*:queue_fix_pr` | Marked as ready for PR work | ⭐⭐⭐⭐⭐ |\n| Reproducible | `*:source-repro`, `confirmed`, `reproducible` | Issue reproduction validated | ⭐⭐⭐⭐⭐ |\n| Impact Assessed | `impact:*`, `severity:*`, `priority:*` | Clear impact scope | ⭐⭐⭐⭐ |\n| Value Rated | `issue-rating: *`, `value:*`, `diamond`, `gold` | Official value rating | ⭐⭐⭐⭐⭐ |\n| Implementation Clear | `*:fix-shape-*`, `fix-shape-clear` | Clear implementation path | ⭐⭐⭐⭐ |\n| Contributor Welcome | `good first issue`, `help wanted`, `contributions welcome` | Explicitly inviting contributions | ⭐⭐⭐⭐ |\n| Scope Defined | `scope:*`, `area:*`, `module:*` | Clear modification scope | ⭐⭐⭐ |\n\n### OpenClaw-Specific Positive Labels\n\nOpenClaw uses **ClawSweeper** automation to identify high-value issues:\n\n```bash\n# ClawSweeper labels (HIGH PRIORITY - maintainer-validated)\ngh issue list --repo openclaw/openclaw --label \"clawsweeper:fix-shape-clear\" --state open\ngh issue list --repo openclaw/openclaw --label \"clawsweeper:queueable-fix\" --state open\ngh issue list --repo openclaw/openclaw --label \"clawsweeper:source-repro\" --state open\n\n# Impact assessment labels\ngh issue list --repo openclaw/openclaw --label \"impact:auth-provider\" --state open\n\n# Value rating labels (🦞 diamond lobster = HIGHEST VALUE)\ngh issue list --repo openclaw/openclaw --label \"issue-rating: 🦞 diamond lobster\" --state open\ngh issue list --repo openclaw/openclaw --label \"issue-rating: *\" --state open\n```\n\n**ClawSweeper Label Meanings**:\n- `clawsweeper:fix-shape-clear` → Clear implementation path identified\n- `clawsweeper:queueable-fix` → Marked as queue-able for PR work\n- `clawsweeper:source-repro` → High-confidence source-level reproduction found\n- `impact:auth-provider` → Auth/provider/model routing may break (critical)\n- `issue-rating: 🦞 diamond lobster` → Highest value issue (fix immediately)\n\n### Issue Discovery Workflow\n\n**Step 1: Explore Repository Labels**\n\n```bash\n# Discover all labels in the repository\ngh api repos/owner/repo/labels --paginate | jq '.[].name'\n\n# Filter for positive label patterns\ngh 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)'\n```\n\n**Step 2: Query Issues with Positive Labels**\n\n```bash\n# Single positive label\ngh issue list --repo owner/repo   --label \"clawsweeper:queueable-fix\"   --state open   --json number,title,labels,createdAt\n\n# Multiple positive labels (OR logic)\ngh issue list --repo owner/repo   --label \"queueable-fix,fix-shape-clear,source-repro\"   --state open   --json number,title,labels,createdAt\n\n# Value-rated issues only\ngh issue list --repo owner/repo   --label \"issue-rating: *\"   --state open   --json number,title,labels,createdAt\n```\n\n**Step 3: Prioritize by Label Combination**\n\n**Priority Tiers**:\n\n| Tier | Label Combination | Action |\n|------|------------------|--------|\n| 🦞 **Diamond** | queueable-fix + source-repro + impact:* | Fix immediately |\n| 💎 **Gold** | fix-shape-clear + impact:* | High priority |\n| 🔥 **Platinum** | source-repro + severity:critical | Urgent fix |\n| � **Silver** | good first issue + help wanted | Good start |\n| ✅ **Standard** | Single positive label | Normal queue |\n| ⚪ **Low** | No positive labels | Skip unless urgent |\n\n**Step 4: Analyze & Select**\n\n```bash\n# Get full issue details\ngh issue view <issue-number> --repo owner/repo\n\n# Check issue comments for context\ngh issue view <issue-number> --repo owner/repo --comments\n\n# Check if already being worked on\ngh pr list --repo owner/repo --search \"fixes #<issue-number>\"\n\n# Verify no existing PRs\ngh pr list --repo owner/repo --state open --search \"<issue-keyword>\"\n```\n\n### Multi-Repo Issue Discovery\n\n```bash\n# Search across multiple repositories\ngh search issues   --label \"queueable-fix,fix-shape-clear,source-repro\"   --state open   --limit 50   --json repository,title,number,url\n\n# Target specific organizations\ngh search issues   --owner openclaw   --label \"impact:*\"   --state open   --sort created   --order desc\n```\n\n### Issue Selection Decision Matrix\n\n**Proceed if issue has**:\n- ✅ At least 1 positive label (queueable/reproducible/impact)\n- ✅ Clear description and reproduction steps\n- ✅ No existing PR addressing it\n- ✅ Scope matches your expertise\n- ✅ Effort fits available time\n\n**Skip if issue has**:\n- ❌ No positive labels (unless urgent bug)\n- ❌ Unclear description or missing details\n- ❌ Existing PR in progress\n- ❌ Requires deep domain expertise you lack\n- ❌ Breaking changes or major refactoring\n\n### Quick Issue Discovery Commands\n\n```bash\n# One-liner: Find all queueable-fix issues\ngh issue list --repo openclaw/openclaw --label \"clawsweeper:queueable-fix\" --state open --limit 10\n\n# Find highest value issues (diamond rated)\ngh issue list --repo openclaw/openclaw --label \"issue-rating: 🦞 diamond lobster\" --state open\n\n# Find reproducible issues with clear implementation path\ngh issue list --repo openclaw/openclaw   --label \"clawsweeper:source-repro,clawsweeper:fix-shape-clear\"   --state open\n\n# Find impact:auth issues (critical system)\ngh issue list --repo openclaw/openclaw --label \"impact:auth-provider\" --state open\n\n# Batch discover: All positive labels\nfor label in \"clawsweeper:queueable-fix\" \"clawsweeper:fix-shape-clear\" \"clawsweeper:source-repro\"; do\n  echo \"=== $label ===\"\n  gh issue list --repo openclaw/openclaw --label \"$label\" --state open --json number,title --limit 5\ndone\n```\n\n### Integration with Contribution Workflow\n\nAfter discovering a high-value issue:\n\n1. **Validate** - Confirm issue is still open and unassigned\n2. **Comment** - Express interest, ask clarifying questions\n3. **Wait** - Get assigned before starting (respect maintainer process)\n4. **Follow Standard Workflow** - Fork → Sync → Branch → Fix → PR\n\n**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.\n\n\n## Usage\n\n### Basic Command\n```bash\n./github-contribution.sh <username> <owner/repo> <issue-number> <branch-name> [projects-root]\n```\n\n### Examples\n```bash\n# Fix issue #123 in openclaw/openclaw\n./github-contribution.sh Linux2010 openclaw/openclaw 123 fix/issue-description\n\n# Specify custom project root\n./github-contribution.sh Linux2010 openclaw/openclaw 456 fix/bug-fix /custom/path\n```\n\n## Fork Protection Best Practices\n\n### Main Branch Rules\n1. **Never commit directly** to fork's main branch\n2. **Always sync first** before creating new branches\n3. **Use feature branches** for all development work\n4. **Regular cleanup** of local pollution files\n\n### Safe Synchronization Script\n```bash\n#!/bin/bash\n# sync-fork.sh - Safe fork synchronization\n\ngit checkout main\ngit fetch upstream\ngit reset --hard upstream/main\ngit clean -fdx  # Remove all untracked files\n\n# Verify clean state\nif [[ $(git status --porcelain) ]]; then\n    echo \"❌ Warning: Working tree not clean\"\n    exit 1\nfi\necho \"✅ Fork synchronized successfully\"\n```\n\n### Local Git Configuration\n```bash\n# Prevent accidental main branch pushes\ngit config branch.main.pushRemote no_push\n\n# Set safe push default\ngit config push.default nothing\n```\n\n## Workflow Steps\n\n### Step 1: Fork Validation\n- Check if fork exists and is accessible\n- Verify upstream remote configuration\n- Validate current fork state cleanliness\n\n### Step 2: Synchronization  \n- Fetch latest from upstream official repository\n- Reset local main branch to match upstream exactly\n- Clean any untracked/local pollution files\n- Push synchronized state to fork (if permissions allow)\n\n### Step 3: Feature Branch Creation\n- Create new branch from clean main\n- Apply necessary changes and fixes\n- Commit with proper semantic format\n- Push feature branch to fork\n\n### Step 4: PR Creation\n- Generate PR with complete template\n- Link to relevant issue numbers\n- Include proper change type and scope\n- Add security impact assessment\n\n---\n\n## 🩺 Bug Fix Module: Change Plan\n\nBefore fixing any bug, **always write a change plan first**. This ensures minimal, safe changes and makes PR review easier.\n\n### The 5-Point Analysis\n\nAnswer these 5 questions in plain language before writing any code:\n\n| # | Question | Purpose |\n|---|----------|---------|\n| 1 | **Observed behavior** | What's broken? (What the user sees) |\n| 2 | **Expected behavior** | What should happen? (Correct behavior) |\n| 3 | **Suspected root cause** | Where's the bug? (Specific code location) |\n| 4 | **Safest seam to modify** | Minimal change location? (Narrowest fix) |\n| 5 | **Risk surface** | What else could break? (Impact scope) |\n\n### Change Plan Template\n\n```markdown\n## Change Plan for Issue #<number>\n\n1. **Observed behavior**:\n   <Describe what's broken - the user-visible symptom>\n\n2. **Expected behavior**:\n   <Describe what should happen instead>\n\n3. **Suspected root cause**:\n   <Point to specific file/line/function that causes the bug>\n\n4. **Safest seam to modify**:\n   <Identify the minimal code change location - smallest safe fix>\n\n5. **Risk surface**:\n   <List what could be affected by this change>\n```\n\n### Example: Issue #5968\n\n```markdown\n## Change Plan for Issue #5968\n\n1. **Observed behavior**:\n   `extract_content_or_reasoning()` crashes when `response.choices` is None, missing, or empty list.\n\n2. **Expected behavior**:\n   Function should return empty string gracefully when no usable choices exist.\n\n3. **Suspected root cause**:\n   Line `msg = response.choices[0].message` in `agent/auxiliary_client.py` assumes choices is always non-empty.\n\n4. **Safest seam to modify**:\n   Add a guard at the top of `extract_content_or_reasoning()` before accessing choices:\n   `if not getattr(response, \"choices\", None): return \"\"`\n\n5. **Risk surface**:\n   Minimal - only affects edge cases where API response is malformed.\n```\n\n### When to Use Change Plan\n\n| Scenario | Required? |\n|----------|-----------|\n| Bug fix | ✅ Always |\n| Paper-cut UX improvement | ✅ Always |\n| Feature addition | ❌ Use feature spec instead |\n| Refactoring | ❌ Use refactor plan instead |\n| Documentation fix | ❌ Not needed |\n\n### Benefits of Change Plan\n\n| Benefit | Why It Matters |\n|---------|----------------|\n| **Forces understanding** | Can't fix what you don't understand |\n| **Defines boundaries** | Prevents scope creep and \"opportunistic\" changes |\n| **Reduces risk** | Identifies potential side effects upfront |\n| **Speeds review** | Maintainer can understand intent in 20 seconds |\n| **Enables rollback** | Clear what was changed and why |\n\n### Change Plan Checklist\n\nBefore coding:\n- [ ] Can you describe the bug in one sentence?\n- [ ] Can you point to the exact line causing it?\n- [ ] Is your fix the smallest possible change?\n- [ ] Have you identified what else could break?\n- [ ] Will this change need a regression test?\n\nIf you answered \"no\" to any question, **do more investigation before coding**.\n\n---\n\n## 🧪 Live-Proof：如何让 PR 获得官方认可\n\n> **详细案例库见 [`live-proof-cases.md`](./live-proof-cases.md)** — 记录了真实 PR 中通过 ClawSweeper 评审的 live-proof 实践，开发 PR 时必读。\n\n### 什么是 live-proof？\n\nOpenClaw 的自动评审机器人 ClawSweeper 要求 PR 提供证明修复**实际生效**的证据。仅有\"单元测试通过\"不算充分 proof。\n\n**目标评级**：`status: 👀 ready for maintainer look` + `proof: sufficient` + Overall ≥ 🐚 platinum hermit\n\n### 评级体系（短板效应）\n\n`Overall = Proof 和 Patch quality 中较弱者`\n\n即使 patch 质量很高，如果 proof 不足，整体评级仍会被拉低。\n\n| 评级 | 含义 |\n|------|------|\n| 🦀 challenger crab | 卓越就绪 |\n| 🦞 diamond lobster | 很强，少量审查 |\n| 🐚 platinum hermit | 良好普通 PR |\n| 🦪 silver shellfish | 信号薄弱，需改进 |\n| 🧂 unranked krab | 不可合并 |\n\n### Live-Proof 形式\n\n被合并的 PR 全部使用**终端命令输出**（不用截图/视频）：\n\n| 类型 | 命令 | 适用 |\n|------|------|------|\n| 直接验证 | `node --import tsx -e \"...\"` | 配置验证、纯函数 |\n| 聚焦测试 | `node scripts/run-vitest.mjs <path>` | 运行时修复 |\n| 格式检查 | `git diff --check` | 代码格式 |\n\n### 最有效模式：BEFORE vs AFTER 对比\n\n```\nBEFORE (current main) - <invalid input> passed validation with ok: true\nAFTER - <invalid input> is rejected with clear error message\n```\n\n### 提交前必查\n\n- [ ] 提供了 BEFORE vs AFTER 对比（不只是 AFTER）\n- [ ] Proof 是终端命令输出，不是只有\"测试通过\"\n- [ ] 覆盖了边界值（最小、最大、无效）\n- [ ] 覆盖了幂等性（如涉及迁移）\n- [ ] **修改前能复现 bug**（测试在修复前会失败）\n- [ ] 修改的代码路径在正常情况下会被走到\n\n### 关键教训\n\n1. **收紧 config 验证 = 破坏性变更**：必须配 `openclaw doctor --fix` 迁移，否则已有配置升级后报错\n2. **Doctor 迁移用替换而非删除**：`gateway.port = DEFAULT` 比 `delete gateway.port` 更安全（配置行为明确）\n3. **修改前先证明 bug 在该路径**：写一个修复前会失败的测试；如果修复前就通过，bug 不在这\n4. **诚实面对找不到根因**：硬提交无效修复会被打 🧂 unranked krab；关闭 PR + 评论 issue 更好\n\n### 详细案例\n\n- ✅ **成功案例 #110051**：配置验证 + Doctor 迁移，`🦞 diamond lobster`\n- ✅ **成功案例 #109875**：竞品学习对象，`👀 ready for maintainer look`\n- ❌ **失败案例 #109885**：修改了不可达路径，`🧂 unranked krab` -> 关闭\n\n---\n\n## Error Handling\n\n### Common Issues & Solutions\n\n#### Fork Not Clean\n- **Problem**: Local main branch has extra commits/files\n- **Solution**: Force reset to upstream and clean untracked files\n\n#### Permission Denied (Workflow Scope)\n- **Problem**: Token lacks workflow permissions\n- **Solution**: Use web-based PR creation or update token permissions\n\n#### Upstream Not Configured  \n- **Problem**: Missing upstream remote\n- **Solution**: Auto-add upstream remote pointing to official repository\n\n#### Branch Already Exists\n- **Problem**: Feature branch already exists\n- **Solution**: Use unique branch naming or delete existing branch\n\n## Security Considerations\n\n### Token Permissions\n- **Minimum Required**: `repo` scope\n- **Optional**: `workflow` scope (for full automation)\n- **Never Grant**: Excessive permissions beyond contribution needs\n\n### Local Security\n- **File Cleanup**: Always clean working directory after contributions\n- **Credential Management**: Use secure credential storage\n- **Audit Trail**: Maintain logs of all contribution activities\n\n## Integration with Other Skills\n\n### PR Advocacy Skill\n- Hand off created PRs to PR Advocacy for monitoring\n- Share PR tracking information for continuous follow-up\n- Coordinate review response and maintenance\n\n### Document Spell Check Skill  \n- Pre-validate documentation changes before PR creation\n- Ensure all text content passes spell checking\n- Maintain documentation quality standards\n\n## High-Quality PR Best Practices (Maximize Merge Success Rate)\n\n### 🎯 Merge Success Rate Formula (Based on 30+ Merged PRs Analysis)\n\n```\nMerge Success Rate = \n  (PR Description Completeness × 0.2) +\n  (Review Response Speed × 0.25) +\n  (Test Coverage × 0.2) +\n  (Conflict Resolution Status × 0.15) +\n  (Review Resolution Rate × 0.2)\n```\n\n**Target**: > 80% success rate\n\n### ✅ 10 Success Characteristics (Must Follow 100%)\n\n1. ✅ **Complete PR Description** - Use template, fill ALL required fields\n2. ✅ **Fast Review Response** - < 30 minutes average response time\n3. ✅ **Small Focused Commits** - 1 commit solves 1 problem\n4. ✅ **100% Test Coverage** - Include edge cases and regression tests\n5. ✅ **Zero Conflicts** - Daily rebase upstream, keep CLEAN\n6. ✅ **Changelog Updated** - All user-visible changes\n7. ✅ **Security Checklist** - 5 required security questions\n8. ✅ **Human Verification Statement** - Manual test content + untested areas\n9. ✅ **Review Conversations Resolved** - 100% resolve bot review comments\n10. ✅ **Rollback Plan** - Rollback steps + known issues\n\n### 📋 Pre-Submission Checklist\n\nBefore pushing PR:\n\n**Code Quality:**\n- [ ] Title format: `type(scope): description`\n- [ ] Commit message: includes \"what\" + \"why\"\n- [ ] At least 1 new test case\n- [ ] CHANGELOG.md updated\n- [ ] 4-7 meaningful commits\n\n**CI Pre-flight (MUST pass locally):**\n- [ ] `pnpm protocol:check` - Protocol validation\n- [ ] `pnpm test` - All tests pass\n- [ ] `pnpm lint` - No lint errors\n- [ ] `pnpm tsc --noEmit` - TypeScript compilation\n\n**Review Readiness:**\n- [ ] Ready to respond within 24h\n- [ ] Greptile/Aisle Security comments addressed\n- [ ] Security questions answered (5 required)\n\n### 📊 High Success Rate PR Patterns\n\n#### Pattern 1: Security Fix Response (vincentkoc #44437)\n```\n7 commits in same day:\n1. Main fix implementation\n2. Changelog update\n3. Merge main (resolve conflicts)\n4. Tests: add coverage for review comments\n5. Fix: address Greptile suggestions\n6. Extra hardening (defensive programming)\n7. Merge main (final sync)\n```\n\n**Key Learnings:**\n- ✅ Separate commits for review responses\n- ✅ Tests and docs as separate commits\n- ✅ Frequent merge main to resolve conflicts\n- ✅ Extra hardening shows professionalism\n\n#### Pattern 2: Security Report Response (gumadeiras #44176)\n```markdown\nWhen Aisle Security reports issues:\n\n1. Quote SECURITY.md to explain why it's out of scope\n2. But still fix it (defensive programming)\n3. List specific hardening done\n4. Provide verification commands\n```\n\n**Key Learnings:**\n- ✅ Respond to security reports first\n- ✅ Explain scope判断 basis\n- ✅ Still fix it (show cooperation)\n- ✅ Provide verification method\n\n### ⚠️ Common Mistakes That Reduce Merge Rate\n\n| Mistake | Impact | Solution |\n|---------|--------|----------|\n| ❌ Missing Changelog | -20% | Always update CHANGELOG.md |\n| ❌ Slow review response (>24h) | -25% | Respond within 24h, ideally <30min |\n| ❌ Incomplete test coverage | -20% | Add tests for edge cases |\n| ❌ Merge conflicts | -15% | Daily rebase upstream |\n| ❌ Unresolved bot reviews | -20% | 100% resolve all comments |\n| ❌ CI failures | Automatic reject | Pre-flight check locally |\n\n### 🎯 Quality Metrics\n\n| Metric | Target | Current Best Practice |\n|--------|--------|----------------------|\n| **Greptile Score** | ≥ 4/5 | Address all P1/P2 issues |\n| **Aisle Security** | 0 unresolved | Respond or fix all |\n| **Test Coverage** | ≥ 1 new test | Include edge cases |\n| **CI Pass Rate** | 100% | Pre-check locally |\n| **Behind upstream** | 0 commits | Daily rebase |\n| **Response Time** | < 24h | Same day preferred |\n\n### 📝 PR Template Best Practices\n\n**Title Format:**\n```\n✅ fix(hooks): fail closed on unreadable loader paths\n✅ feat(context-engine): plumb sessionKey into all methods\n✅ docs: codify American English spelling convention\n✅ security: include accountId in session keys\n```\n\n**Commit Message Structure:**\n```\nFirst line: What was done (concise description)\n\nSecond paragraph: Why (problem background, impact)\n\nOptional: Regeneration-Prompt / AI assistance notes\n```\n\n**Example (#44411):**\n```\nfix(ci): restore generated protocol swift outputs\n\nRegenerate the Swift protocol models so PushTestResult keeps the \ntransport field required by the current gateway schema, and update \nprotocol:check to diff both generated Swift destinations because \nthe generator writes both files.\n\nRegeneration-Prompt: |\n  Investigate the protocol CI failure on current origin/main...\n```\n\n---\n\n## Best Practices\n\n### For Contributors\n- Always start from clean, synchronized main branch\n- Use descriptive branch names following convention\n- Fill complete PR templates with all required fields\n- Test changes locally before pushing\n- **Always rebase on the original PR branch** (never create new branches for rebase)\n- **Follow High-Quality PR Best Practices** (see section above)\n\n### PR Rebase Best Practices (Critical!)\n\n**Golden Rule**: Always rebase on the **original PR branch**, never create a new branch.\n\n#### Correct Rebase Workflow\n\n```bash\n# 1. Confirm current branch\ngit branch --show-current\n\n# 2. Confirm PR's branch name\ngh pr view <PR-number> --json headRefName --jq .headRefName\n\n# 3. Switch to correct branch if needed\ngit checkout <PR-branch-name>\n\n# 4. Rebase on the SAME branch (do NOT create new branch)\ngit fetch upstream\ngit rebase upstream/main\n\n# 5. Push to the SAME branch\ngit push -f origin <same-branch-name>\n```\n\n#### Common Mistakes to Avoid\n\n| ❌ Wrong | ✅ Correct |\n|---------|---------|\n| `git checkout -b new-branch` then rebase | Stay on original branch, rebase there |\n| Switch to different branch for rebase | Rebase on PR's own branch |\n| Skip branch confirmation | Always run `git branch --show-current` first |\n| Don't verify PR branch name | Use `gh pr view` to confirm |\n\n#### Why This Matters?\n\n1. **Clean branch history** - No duplicate branches created\n2. **Avoid confusion** - PR always linked to same branch\n3. **Reduce errors** - Won't push to wrong branch\n4. **Easy management** - All changes in one place\n\n#### Pre-Rebase Checklist\n\nBefore rebasing:\n- [ ] Run `git branch --show-current` to confirm current branch\n- [ ] Run `gh pr view <num> --json headRefName` to confirm PR branch\n- [ ] Ensure both names match before proceeding\n- [ ] If mismatch, `git checkout <PR-branch>` first\n\n#### Post-Rebase Checklist\n\nAfter rebasing:\n- [ ] Run `git log --oneline -3` to verify commits\n- [ ] Run `pnpm test` or relevant tests\n- [ ] Run `git push -f origin <branch>` to update PR\n\n#### Example: Rebase PR #48568\n\n```bash\n# Check current branch\n$ git branch --show-current\nfix/47752-final  # ✅ Correct!\n\n# Confirm PR branch\n$ gh pr view 48568 --json headRefName --jq .headRefName\nfix/47752-final  # ✅ Matches!\n\n# Rebase on same branch\ngit fetch upstream\ngit rebase upstream/main\n\n# Test\npnpm test src/infra/heartbeat-runner.timeout.test.ts\n\n# Push to same branch\ngit push -f origin fix/47752-final\n```\n\n#### Troubleshooting\n\n**Problem**: Accidentally created new branch during rebase\n\n**Solution**:\n```bash\n# Go back to original branch\ngit checkout <original-branch>\n\n# Rebase there instead\ngit rebase upstream/main\n\n# Delete the accidental branch\ngit branch -D <accidental-branch>\n\n# Push to original branch\ngit push -f origin <original-branch>\n```\n\n---\n\n### For Maintainers  \n- Regularly audit fork cleanliness\n- Update synchronization scripts as needed\n- Monitor token permissions and security\n- Document contribution workflows for team members\n\n## Limitations\n\n### GitHub Fork Restrictions\n- Cannot set full branch protection rules on forks\n- Limited automation capabilities without workflow permissions\n- Manual intervention sometimes required for complex scenarios\n\n### Workarounds\n- Use local git hooks for additional protection\n- Implement manual verification steps in workflow\n- Leverage GitHub web interface for final PR creation when needed\n\n## Maintenance\n\n### Updates\n- Regular script updates for new GitHub API changes\n- Security patches for authentication methods\n- Performance improvements for large repositories\n\n### Monitoring\n- Track success/failure rates of contribution attempts\n- Monitor GitHub API rate limit usage\n- Collect user feedback for workflow improvements\n\nFile v1.7.4:_meta.json\n\n{\n  \"ownerId\": \"kn7djfrkxdrrb6syjdv4vvtmp18252ry\",\n  \"slug\": \"github-contribution\",\n  \"version\": \"1.7.4\",\n  \"publishedAt\": 1784821559174\n}\n\nFile v1.7.4:github-contribution-workflow.md\n\n# GitHub 开源项目贡献完整工作流程\n\n## 1. Fork 和同步项目\n\n### Fork 官方仓库\n- 访问目标项目的 GitHub 页面（例如 `https://github.com/owner/repo`）\n- 点击右上角的 \"Fork\" 按钮\n- 选择你的 GitHub 账户作为 fork 目标\n\n### 克隆你的 Fork\n```bash\ngit clone https://github.com/your-username/repo.git\ncd repo\n```\n\n### 添加上游远程仓库\n```bash\ngit remote add upstream https://github formulate the official repository URL\ngit remote -v  # 验证远程仓库配置\n```\n\n### 同步 Fork 到最新状态\n```bash\n# 切换到 main/master 分支\ngit checkout main\n\n# 获取上游仓库的最新更改\ngit fetch upstream\n\n# 将上游的更改合并到本地\ngit merge upstream/main\n\n# 推送到你的 fork\ngit push origin main\n```\n\n## 2. 创建功能分支\n\n### 基于最新的 main 分支创建新分支\n```bash\n# 确保在 main 分支且已同步\ngit checkout main\ngit pull upstream main\n\n# 创建新的功能分支（使用描述性名称）\ngit checkout -b fix/issue-description\n# 或者\ngit checkout -b feature/new-functionality\n```\n\n### 分支命名约定\n- `fix/` - 用于 bug 修复\n- `feature/` - 用于新功能\n- `docs/` - 用于文档更新\n- `chore/` - 用于维护任务\n\n## 3. 开发和测试\n\n### 进行代码更改\n- 在功能分支上进行所有开发工作\n- 遵循项目的代码风格和规范\n- 编写必要的测试用例\n- 更新相关文档（如果需要）\n\n### 提交更改\n```bash\n# 查看更改状态\ngit status\n\n# 添加更改的文件\ngit add .\n\n# 提交更改（使用清晰的提交信息）\ngit commit -m \"fix: resolve issue with XYZ component\"\n\n# 推送到你的 fork\ngit push origin fix/issue-description\n```\n\n### 提交信息格式\n遵循 conventional commits 格式：\n- `fix:` - bug 修复\n- `feat:` - 新功能\n- `docs:` - 文档更新\n- `style:` - 代码格式更改\n- `refactor:` - 代码重构\n- `test:` - 测试相关\n- `chore:` - 构建过程或辅助工具的变动\n\n## 4. 创建 Pull Request\n\n### 通过 GitHub 网页界面创建 PR\n1. 访问你的 fork 仓库页面\n2. GitHub 通常会自动检测到新推送的分支并显示 \"Compare & pull request\" 按钮\n3. 点击该按钮进入 PR 创建页面\n\n### PR 标题和描述\n- **标题**: 清晰描述更改的目的（例如：\"Fix null pointer exception in auth handler\"）\n- **描述**: \n  - 说明问题的背景\n  - 描述解决方案\n  - 提及相关的 issue（使用 `Closes #123` 或 `Fixes #123`）\n  - 列出主要的更改点\n\n### PR 检查清单\n- [ ] 代码通过所有测试\n- [ ] 遵循项目代码风格\n- [ ] 包含必要的测试用例\n- [ ] 更新了相关文档\n- [ ] PR 描述清晰完整\n- [ ] 关联了相关 issue\n\n## 5. PR 审查和合并\n\n### 处理审查反馈\n- 及时响应审查者的评论\n- 根据反馈进行必要的修改\n- 使用新的提交来处理反馈（不要强制推送覆盖历史）\n\n### 更新 PR\n```bash\n# 在功能分支上进行修改\ngit add .\ngit commit -m \"address review feedback: improve error handling\"\ngit push origin fix/issue-description\n```\n\n### PR 合并后清理\n```bash\n# 切换回 main 分支\ngit checkout main\n\n# 删除本地功能分支\ngit branch -d fix/issue-description\n\n# 删除远程功能分支（可选）\ngit push origin --delete fix/issue-description\n```\n\n## 常见问题和最佳实践\n\n### 保持分支同步\n如果 PR 审查时间较长，可能需要将最新的上游更改合并到你的功能分支：\n```bash\ngit checkout main\ngit pull upstream main\ngit checkout fix/issue-description\ngit rebase main\ngit push --force-with-lease origin fix/issue-description\n```\n\n### 避免强制推送\n除非必要（如 rebase 后），避免使用 `--force` 推送，使用 `--force-with-lease` 更安全。\n\n### 小而专注的 PR\n- 每个 PR 应该解决一个具体的问题\n- 避免在一个 PR 中包含多个不相关的更改\n- 这样更容易审查和合并\n\n### 社区礼仪\n- 保持礼貌和专业的沟通\n- 及时响应审查反馈\n- 感谢维护者的审查时间\n- 遵循项目的贡献指南（CONTRIBUTING.md）\n\nFile v1.7.4:live-proof-cases.md\n\n# Live-Proof 案例库\n\n> 本文件记录真实 PR 中通过 ClawSweeper 评审、获得 `status: 👀 ready for maintainer look` 的 live-proof 实践。\n> 开发 PR 时参考本案例库，确保提供的 proof 足够充分。\n\n## 目录\n\n- [ClawSweeper 评级体系](#clawsweeper-评级体系)\n- [什么是 live-proof](#什么是-live-proof)\n- [案例一：配置验证类修复（#110051）](#案例一配置验证类修复110051)\n- [案例二：竞品对比学习（#109875）](#案例二竞品对比学习109875)\n- [失败案例：修改了不可达路径（#109885）](#失败案例修改了不可达路径109885)\n- [通用 Proof 模板](#通用-proof-模板)\n- [检查清单](#检查清单)\n\n---\n\n## ClawSweeper 评级体系\n\nClawSweeper（OpenClaw 的自动评审机器人）对 PR 给出三个维度的甲壳类评级：\n\n| 评级 | 含义 | 可合并性 |\n|------|------|----------|\n| 🦀 challenger crab | 罕见，卓越的就绪状态 | 极高 |\n| 🦞 diamond lobster | 很强，仅需少量 maintainer 审查 | 高 |\n| 🐚 platinum hermit | 良好的普通 PR，普通审查即可 | 中高 |\n| 🦐 gold shrimp | 有用信号，但 proof/confidence 仍有限 | 中 |\n| 🦪 silver shellfish | 信号薄弱，proof/validation/实现需改进 | 低 |\n| 🧂 unranked krab | 不可合并（proof 缺失或有严重问题） | 不可合并 |\n| 🌊 off-meta tidepool | 评级不适用 | N/A |\n\n### 三个评分维度\n\n| 维度 | 说明 |\n|------|------|\n| **Overall** | 综合 = proof 和 patch quality 中较弱者（短板效应） |\n| **Proof** | 真实行为证明的充分性 |\n| **Patch quality** | 代码实现质量 |\n\n> ⚠️ **关键规则**：`Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.`\n> 即使 patch 质量是 🐚 platinum hermit，如果 proof 只有 🦪 silver shellfish，整体仍是 🦪。\n\n### 状态标签\n\n| 标签 | 含义 |\n|------|------|\n| `status: 📣 needs proof` | 需要补充真实行为证明才能合并 |\n| `status: 👀 ready for maintainer look` | ClawSweeper 无 contributor 阻塞项，等待 maintainer 审查 |\n| `proof: sufficient` | Contributor 真实行为证明充分 |\n\n**目标**：获得 `status: 👀 ready for maintainer look` + `proof: sufficient`。\n\n---\n\n## 什么是 live-proof\n\nLive-proof（真实行为证明）是 ClawSweeper 要求的、证明修复**实际生效**的证据。\n\n### ❌ 不是 live-proof 的东西\n\n- 只有单元测试通过（\"X tests passed\"）\n- 纯代码阅读得出的结论（\"代码逻辑应该正确\"）\n- 声称修复有效但没有运行验证\n\n### ✅ 是 live-proof 的东西\n\n被合并的 PR 全部使用**终端命令输出**作为 proof，不用截图/视频：\n\n| Proof 类型 | 命令模式 | 适用场景 |\n|-----------|---------|---------|\n| 直接验证 | `node --import tsx -e \"...\"` | 配置验证、纯函数行为 |\n| 聚焦测试 | `node scripts/run-vitest.mjs <path>` | 运行时修复、回归测试 |\n| 完整 gate | `node scripts/check-changed.mjs -- <files>` | 多文件变更 |\n| 格式检查 | `git diff --check` / `oxfmt --check` | 代码格式 |\n| Autoreview | `autoreview --mode uncommitted` | 代码审查 |\n\n### 关键：BEFORE vs AFTER 对比\n\n最有效的 proof 是展示**修复前**和**修复后**的对比：\n\n```\nBEFORE (current main) - gateway.port: 65536 passed validation with ok: true\nAFTER - gateway.port: 65536 is rejected with clear error message\n```\n\n---\n\n## 案例一：配置验证类修复（#110051）\n\n**Issue**: #109293 - `gateway.port` 接受超出 TCP 端口范围的值\n**PR**: https://github.com/openclaw/openclaw/pull/110051\n**修复类型**: 配置 schema 收紧 + Doctor 迁移\n\n### 问题描述\n\n`gateway.port` 的 Zod schema 只有 `.positive()` 没有 `.max(65535)`，导致 `65536` 等无效端口通过验证。\n\n### 关键教训：收紧 config 验证 = 破坏性变更\n\n**这是最重要的教训。** 收紧 config schema 会让之前合法的配置变非法，必须配 Doctor 迁移！\n\n> CLAUDE.md 明确规定：\"If a config change invalidates existing files, add a matching `openclaw doctor --fix` migration.\"\n\n只加 schema 约束而不加 Doctor 迁移的后果：\n- 已有 `gateway.port: 65536` 的用户升级后直接报错，无升级路径\n- ClawSweeper 标记 `merge-risk: 🚨 compatibility`\n- 无法获得 `status: 👀 ready for maintainer look`\n\n### Doctor 迁移设计决策\n\n迁移应**替换为默认值**而非删除键：\n\n| 策略 | #109875（竞品） | #110051（我们的） |\n|------|-----------------|------------------|\n| 做法 | `delete gateway.port` | `gateway.port = DEFAULT_GATEWAY_PORT` |\n| 迁移后配置 | 无 port 键 | `port: 18789` |\n| 用户体验 | 困惑：配置里没 port，网关用什么端口？ | 明确：绑定到默认 18789 |\n\n### 提供的 Proof 内容\n\n**1. Schema validation - BEFORE vs AFTER**\n\n```sh\n# BEFORE (current main) - passes validation\n{\"ok\": true, \"config\": {\"gateway\": {\"port\": 65536}}}\n\n# AFTER - rejected\n$ node --import tsx -e \"\nimport { validateConfigObjectRaw } from './src/config/validation.ts';\nconsole.log(JSON.stringify(validateConfigObjectRaw({gateway:{port:65536}}), null, 2));\"\n{\n  \"ok\": false,\n  \"issues\": [{\n    \"path\": \"gateway.port\",\n    \"message\": \"Too big: expected number to be <=65535 (maximum: 65535)\"\n  }]\n}\n```\n\n**2. Doctor migration - 升级路径证明**\n\n```sh\n$ node --import tsx -e \"\nimport { applyLegacyDoctorMigrations } from './src/commands/doctor/shared/legacy-config-compat.js';\nconst raw = {gateway:{port:65536}};\nconst { next, changes } = applyLegacyDoctorMigrations(raw);\nconsole.log('changes:', JSON.stringify(changes));\nconsole.log('next:', JSON.stringify(next));\"\nchanges: [\"Replaced out-of-range gateway.port (65536) with default 18789...\"]\nnext: {\"gateway\":{\"port\":18789}}\n```\n\n覆盖场景：\n- port 65536（超上限）→ 替换为默认\n- port 0（低于下限）→ 替换为默认\n- port 65535（有效）→ 无迁移\n- port 65536 + bind:loopback → port 替换，bind 保留\n- 幂等性：第二次迁移无变化\n\n**3. 测试结果**\n\n```\n- node scripts/run-vitest.mjs src/config/zod-schema.gateway.test.ts - 7 tests\n- node scripts/run-vitest.mjs src/config/validation.policy.test.ts - 8 tests\n- node scripts/run-vitest.mjs src/commands/doctor/shared/legacy-config-migrate.test.ts - 158 tests\n- git diff --check - passed\n```\n\n### 评级结果\n\n| 维度 | 评级 |\n|------|------|\n| Patch quality | 🐚 platinum hermit |\n| Proof | 🦞 diamond lobster（加入 Doctor proof 后） |\n| Overall | 🦞 diamond lobster |\n\n---\n\n## 案例二：竞品对比学习（#109875）\n\n**Issue**: 同 #109293\n**PR**: https://github.com/openclaw/openclaw/pull/109875\n**结果**: 获得 `status: 👀 ready for maintainer look` + `proof: sufficient`\n\n### 它做对了什么\n\n1. **Doctor 迁移配对**：schema 收紧 + `openclaw doctor --fix` 迁移\n2. **BEFORE vs AFTER 对比**：明确展示修复前后验证输出\n3. **Doctor 迁移的完整场景证明**：6 个场景，每个都有终端输出\n4. **测试分散在正确的位置**：验证策略测试 + 迁移测试\n\n### ClawSweeper 的关键评语\n\n> `status: 👀 ready for maintainer look`: ClawSweeper has no concrete contributor-facing blocker left for this PR.\n> `proof: sufficient`: The PR body includes after-fix terminal output for raw validation and Doctor migration behavior, including invalid, valid-boundary, idempotence, and sibling-key cases.\n\n### 它的不足（我们改进的点）\n\n1. Doctor 迁移用 `delete` 而非 `replace`，用户体验较差\n2. `legacyRules` 的 `match` 没有覆盖非数字/非整数类型\n3. 迁移测试没覆盖负数端口\n\n---\n\n## 失败案例：修改了不可达路径（#109885）\n\n**Issue**: #109673 - `browser.headless` 配置被忽略\n**PR**: https://github.com/openclaw/openclaw/pull/109885（已关闭）\n**结果**: 🧂 unranked krab → 关闭\n\n### 失败原因\n\n**修改了一个正常代码路径不会走到的 fallback。**\n\n```typescript\n// resolveManagedBrowserHeadlessMode 的 fallback (line 730)\nreturn { headless: resolved.headless, source: \"default\" };  // 我改成了 resolved.headlessSource\n```\n\nClawSweeper 的批评：\n> The changed final fallback is bypassed by the normal resolved profile according to the PR's own tests, so the patch does not yet identify or repair the boundary producing the reported behavior.\n\n### 教训\n\n1. **修改前先证明 bug 在该路径**：写一个测试，在修复前应该失败。如果修复前测试就通过，说明 bug 不在这。\n2. **不要修改\"看起来不对\"但实际不影响行为的代码**：要验证改动是否真正改变运行时行为。\n3. **ClawSweeper 会读你的测试**：如果测试本身说明\"正常 profile 走早期分支\"，它就知道你的 fallback 修改无效。\n4. **找不到根因时不要硬提交**：诚实说明，关闭 PR，评论 issue 说明调查结果。\n\n### 正确的流程\n\n```\n1. 写测试复现 bug（修复前应失败）\n   ↓ 失败 = 找到了根因\n2. 修复代码\n   ↓ 测试通过\n3. 验证修复改变了运行时行为（live-proof）\n   ↓\n4. 提交 PR\n```\n\n---\n\n## 通用 Proof 模板\n\n### 配置验证类修复\n\n```markdown\n## Evidence\n\n### 1. Schema validation - BEFORE vs AFTER\n\n**BEFORE** (current main) - `<invalid input>` passed validation with `ok: true`\n\n**AFTER** - `<invalid input>` is rejected:\n\n\\`\\`\\`sh\n$ node --import tsx -e \"\nimport { validateConfigObjectRaw } from './src/config/validation.ts';\nconsole.log(JSON.stringify(validateConfigObjectRaw({<path>:<value>}), null, 2));\"\n<actual output showing ok:false + error message>\n\\`\\`\\`\n\n### 2. Doctor migration - upgrade path proof\n\n\\`\\`\\`sh\n$ node --import tsx -e \"\nimport { applyLegacyDoctorMigrations } from './src/commands/doctor/shared/legacy-config-compat.js';\nconst raw = {<path>:<invalid_value>};\nconst { next, changes } = applyLegacyDoctorMigrations(raw);\nconsole.log('changes:', JSON.stringify(changes));\nconsole.log('next:', JSON.stringify(next));\"\n<output showing repair>\n\\`\\`\\`\n\n覆盖场景：\n- 无效值 → 修复\n- 有效边界值 → 不变\n- 幂等性\n- sibling key 保留\n\n### 3. Test results\n- `node scripts/run-vitest.mjs <test-path>` - N tests passed\n- `git diff --check` - passed\n```\n\n### 运行时逻辑修复\n\n```markdown\n## Evidence\n\n- Focused proof: `node scripts/run-vitest.mjs <test-path>` - N tests passed.\n- BEFORE: <描述修复前的错误行为，最好有测试断言证明>\n- AFTER: <描述修复后的正确行为>\n- `git diff --check` - passed.\n```\n\n### Bug 复现型修复\n\n```markdown\n## Evidence\n\n### Regression test (fails before fix, passes after)\n\\`\\`\\`\nnode scripts/run-vitest.mjs <test-path>\n# Before fix: FAIL - <error>\n# After fix: PASS\n\\`\\`\\`\n\n### Live behavior proof\n<运行实际命令展示修复前后行为变化>\n```\n\n---\n\n## 检查清单\n\n### 提交 PR 前的 proof 检查\n\n- [ ] 提供了 BEFORE vs AFTER 对比（不只是 AFTER）\n- [ ] Proof 是终端命令输出，不是只有\"测试通过\"\n- [ ] 覆盖了边界值（最小、最大、无效）\n- [ ] 覆盖了幂等性（如涉及迁移）\n- [ ] 覆盖了 sibling key 保留（如涉及删除/修改配置项）\n- [ ] 如果收紧了 config 验证，配了 Doctor 迁移\n- [ ] 修复前能复现 bug（测试在修复前会失败）\n\n### 自问：修改是否真正改变运行时行为？\n\n- [ ] 我写的测试在**修复前**会失败吗？\n- [ ] 我修改的代码路径在**正常情况下**会被走到吗？\n- [ ] ClawSweeper 读完我的测试后，会认为我的修复有效吗？\n\n如果任何一项为\"否\"，**不要提交**，继续调查根因。\n\n### 达标目标\n\n提交 PR 后，目标评级：\n- ✅ `status: 👀 ready for maintainer look`\n- ✅ `proof: sufficient`\n- ✅ Overall ≥ 🐚 platinum hermit\n\n---\n\n## 经验总结\n\n### 1. 收紧配置验证必须配 Doctor 迁移\n\n这是 OpenClaw 的硬规则。任何让之前合法配置变非法的变更，都要提供 `openclaw doctor --fix` 升级路径。\n\n### 2. Proof 要展示真实运行时行为\n\nClawSweeper 明确说：\"Only unit-test claims are provided\" 是不够的。要运行实际命令展示修复效果。\n\n### 3. BEFORE vs AFTER 对比最有效\n\n明确展示\"修复前是坏的，修复后是好的\"比单纯展示\"修复后是好的\"更有说服力。\n\n### 4. 修改前先证明 bug 在该路径\n\n写一个在修复前会失败的测试。如果修复前测试就通过，说明 bug 不在你修改的地方。\n\n### 5. Doctor 迁移用替换而非删除\n\n替换为默认值比删除键更安全：用户看到的配置文件行为明确，不依赖隐式默认。\n\n### 6. 诚实面对找不到根因的情况\n\n如果代码逻辑看起来正确但 bug 仍存在，可能 bug 在运行时其他地方或已被间接修复。诚实说明，关闭 PR，评论 issue，比硬提交一个无效修复好。\n\nFile v1.7.4:skill-card.md\n\n## Description:\n\nGithub Contribution helps agents discover maintainer-approved GitHub issues, prepare clean fork branches, and produce pull request contribution guidance with proof expectations.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[linux2010](https://clawhub.ai/user/linux2010)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and coding agents use this skill to identify suitable GitHub issues, prepare a synchronized fork and feature branch, and draft contribution-ready pull requests with concrete validation evidence.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The workflow can reset and clean a local repository, which may discard uncommitted work or untracked files.\n\nMitigation: Run it only in disposable or freshly cloned fork directories, check git status first, and back up or commit any local work before execution.\n\nRisk: The workflow may encourage broader GitHub token permissions than are needed for normal contribution tasks.\n\nMitigation: Prefer existing GitHub CLI or SSH authentication, or use fine-grained credentials limited to the relevant fork or repository.\n\nRisk: The automation depends on repository branch conventions and upstream remote state.\n\nMitigation: Manually verify the target repository, fork, upstream remote, and branch names before allowing push or pull request actions.\n\n## Reference(s):\n\n- [ClawHub Skill Page](https://clawhub.ai/linux2010/skills/github-contribution)\n- [Publisher Profile](https://clawhub.ai/user/linux2010)\n- [Skill Instructions](artifact/SKILL.md)\n- [Contribution Workflow](artifact/github-contribution-workflow.md)\n- [Live Proof Cases](artifact/live-proof-cases.md)\n- [Automation Script](artifact/scripts/github-contribution.sh)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, code, shell commands, guidance]\n\n**Output Format:** [Markdown guidance with inline shell commands and code snippets]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [May include repository-specific command sequences, PR text, checklists, and validation evidence templates.]\n\n## Skill Version(s):\n\n1.7.4 (source: server release evidence)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nFile v1.7.4:skill.json\n\n{\n  \"name\": \"github-contribution\",\n  \"version\": \"1.7.2\",\n  \"description\": \"Automated GitHub contribution workflow with fork protection, clean state enforcement, change plan module, and high merge success rate best practices\",\n  \"author\": \"Linux2010\",\n  \"license\": \"MIT\",\n  \"keywords\": [\n    \"github\",\n    \"contribution\",\n    \"fork\",\n    \"pr\",\n    \"protection\",\n    \"merge-success\",\n    \"quality\",\n    \"change-plan\",\n    \"bugfix\"\n  ],\n  \"repository\": {\n    \"type\": \"git\",\n    \"url\": \"https://github.com/Linux2010/openclaw-skills\"\n  }\n}\n\nArchive v1.7.3: 7 files, 22072 bytes\n\nFiles: _meta.json (138b), github-contribution-workflow.md (4039b), live-proof-cases.md (12856b), scripts/github-contribution.sh (3565b), skill-card.md (1974b), skill.json (535b), SKILL.md (25843b)\n\nFile v1.7.3:SKILL.md\n\n# GitHub Contribution Skill\n\n## Purpose\nAutomated GitHub contribution workflow with intelligent issue discovery via positive label detection. Handles fork synchronization, branch creation, PR submission while maintaining clean fork state, and provides live-proof guidance for passing automated code review.\n\n## Core Features\n\n### 1. Intelligent Issue Discovery (v1.7.2)\n- **Positive Label Detection**: Automatically identify high-value issues via maintainer-approved labels\n- **Priority Scoring**: Rank issues by contribution value and fix feasibility\n- **Smart Filtering**: Focus on queueable, reproducible, and high-impact issues\n- **Multi-Repo Support**: Discover issues across multiple target repositories\n\n### 2. Fork Protection & Synchronization\n- **Main Branch Protection**: Never commit directly to main branch\n- **Automatic Sync**: Regularly sync fork main with upstream official repository  \n- **Clean State Enforcement**: Ensure fork main branch matches official repository exactly\n- **Pollution Prevention**: Prevent local work files from contaminating main branch\n\n### 3. Automated Contribution Workflow\n- **Fork Setup**: Automatically configure upstream remote if not exists\n- **Branch Creation**: Create feature branches based on latest official code\n- **PR Submission**: Handle pull request creation with proper templates\n- **Issue Integration**: Link fixes to relevant GitHub issues\n\n### 4. Safety Measures\n- **Pre-flight Validation**: Verify fork cleanliness before starting\n- **Atomic Operations**: All changes happen in isolated feature branches\n- **Rollback Support**: Easy recovery if something goes wrong\n- **Permission Handling**: Work within GitHub token permission constraints\n\n## 🎯 Intelligent Issue Discovery (v1.7.2)\n\n### Positive Label Detection System\n\nModern repositories use automated labeling systems to identify **high-value, maintainer-approved issues**. These **positive labels** signal issues that are:\n\n- ✅ Ready for contribution (`queueable-fix`)\n- ✅ Reproducible and confirmed (`source-repro`)\n- ✅ Impact clearly assessed (`impact:*`)\n- ✅ Value-rated by maintainers (`issue-rating:`)\n\n**Golden Rule**: Prioritize issues with positive labels over random bugs.\n\n### Label Categories & Priority\n\n| Category | Label Pattern | Meaning | Priority |\n|----------|-------------|---------|----------|\n| Queueable | `*:queueable-fix`, `*:queue_fix_pr` | Marked as ready for PR work | ⭐⭐⭐⭐⭐ |\n| Reproducible | `*:source-repro`, `confirmed`, `reproducible` | Issue reproduction validated | ⭐⭐⭐⭐⭐ |\n| Impact Assessed | `impact:*`, `severity:*`, `priority:*` | Clear impact scope | ⭐⭐⭐⭐ |\n| Value Rated | `issue-rating: *`, `value:*`, `diamond`, `gold` | Official value rating | ⭐⭐⭐⭐⭐ |\n| Implementation Clear | `*:fix-shape-*`, `fix-shape-clear` | Clear implementation path | ⭐⭐⭐⭐ |\n| Contributor Welcome | `good first issue`, `help wanted`, `contributions welcome` | Explicitly inviting contributions | ⭐⭐⭐⭐ |\n| Scope Defined | `scope:*`, `area:*`, `module:*` | Clear modification scope | ⭐⭐⭐ |\n\n### OpenClaw-Specific Positive Labels\n\nOpenClaw uses **ClawSweeper** automation to identify high-value issues:\n\n```bash\n# ClawSweeper labels (HIGH PRIORITY - maintainer-validated)\ngh issue list --repo openclaw/openclaw --label \"clawsweeper:fix-shape-clear\" --state open\ngh issue list --repo openclaw/openclaw --label \"clawsweeper:queueable-fix\" --state open\ngh issue list --repo openclaw/openclaw --label \"clawsweeper:source-repro\" --state open\n\n# Impact assessment labels\ngh issue list --repo openclaw/openclaw --label \"impact:auth-provider\" --state open\n\n# Value rating labels (🦞 diamond lobster = HIGHEST VALUE)\ngh issue list --repo openclaw/openclaw --label \"issue-rating: 🦞 diamond lobster\" --state open\ngh issue list --repo openclaw/openclaw --label \"issue-rating: *\" --state open\n```\n\n**ClawSweeper Label Meanings**:\n- `clawsweeper:fix-shape-clear` → Clear implementation path identified\n- `clawsweeper:queueable-fix` → Marked as queue-able for PR work\n- `clawsweeper:source-repro` → High-confidence source-level reproduction found\n- `impact:auth-provider` → Auth/provider/model routing may break (critical)\n- `issue-rating: 🦞 diamond lobster` → Highest value issue (fix immediately)\n\n### Issue Discovery Workflow\n\n**Step 1: Explore Repository Labels**\n\n```bash\n# Discover all labels in the repository\ngh api repos/owner/repo/labels --paginate | jq '.[].name'\n\n# Filter for positive label patterns\ngh 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)'\n```\n\n**Step 2: Query Issues with Positive Labels**\n\n```bash\n# Single positive label\ngh issue list --repo owner/repo   --label \"clawsweeper:queueable-fix\"   --state open   --json number,title,labels,createdAt\n\n# Multiple positive labels (OR logic)\ngh issue list --repo owner/repo   --label \"queueable-fix,fix-shape-clear,source-repro\"   --state open   --json number,title,labels,createdAt\n\n# Value-rated issues only\ngh issue list --repo owner/repo   --label \"issue-rating: *\"   --state open   --json number,title,labels,createdAt\n```\n\n**Step 3: Prioritize by Label Combination**\n\n**Priority Tiers**:\n\n| Tier | Label Combination | Action |\n|------|------------------|--------|\n| 🦞 **Diamond** | queueable-fix + source-repro + impact:* | Fix immediately |\n| 💎 **Gold** | fix-shape-clear + impact:* | High priority |\n| 🔥 **Platinum** | source-repro + severity:critical | Urgent fix |\n| � **Silver** | good first issue + help wanted | Good start |\n| ✅ **Standard** | Single positive label | Normal queue |\n| ⚪ **Low** | No positive labels | Skip unless urgent |\n\n**Step 4: Analyze & Select**\n\n```bash\n# Get full issue details\ngh issue view <issue-number> --repo owner/repo\n\n# Check issue comments for context\ngh issue view <issue-number> --repo owner/repo --comments\n\n# Check if already being worked on\ngh pr list --repo owner/repo --search \"fixes #<issue-number>\"\n\n# Verify no existing PRs\ngh pr list --repo owner/repo --state open --search \"<issue-keyword>\"\n```\n\n### Multi-Repo Issue Discovery\n\n```bash\n# Search across multiple repositories\ngh search issues   --label \"queueable-fix,fix-shape-clear,source-repro\"   --state open   --limit 50   --json repository,title,number,url\n\n# Target specific organizations\ngh search issues   --owner openclaw   --label \"impact:*\"   --state open   --sort created   --order desc\n```\n\n### Issue Selection Decision Matrix\n\n**Proceed if issue has**:\n- ✅ At least 1 positive label (queueable/reproducible/impact)\n- ✅ Clear description and reproduction steps\n- ✅ No existing PR addressing it\n- ✅ Scope matches your expertise\n- ✅ Effort fits available time\n\n**Skip if issue has**:\n- ❌ No positive labels (unless urgent bug)\n- ❌ Unclear description or missing details\n- ❌ Existing PR in progress\n- ❌ Requires deep domain expertise you lack\n- ❌ Breaking changes or major refactoring\n\n### Quick Issue Discovery Commands\n\n```bash\n# One-liner: Find all queueable-fix issues\ngh issue list --repo openclaw/openclaw --label \"clawsweeper:queueable-fix\" --state open --limit 10\n\n# Find highest value issues (diamond rated)\ngh issue list --repo openclaw/openclaw --label \"issue-rating: 🦞 diamond lobster\" --state open\n\n# Find reproducible issues with clear implementation path\ngh issue list --repo openclaw/openclaw   --label \"clawsweeper:source-repro,clawsweeper:fix-shape-clear\"   --state open\n\n# Find impact:auth issues (critical system)\ngh issue list --repo openclaw/openclaw --label \"impact:auth-provider\" --state open\n\n# Batch discover: All positive labels\nfor label in \"clawsweeper:queueable-fix\" \"clawsweeper:fix-shape-clear\" \"clawsweeper:source-repro\"; do\n  echo \"=== $label ===\"\n  gh issue list --repo openclaw/openclaw --label \"$label\" --state open --json number,title --limit 5\ndone\n```\n\n### Integration with Contribution Workflow\n\nAfter discovering a high-value issue:\n\n1. **Validate** - Confirm issue is still open and unassigned\n2. **Comment** - Express interest, ask clarifying questions\n3. **Wait** - Get assigned before starting (respect maintainer process)\n4. **Follow Standard Workflow** - Fork → Sync → Branch → Fix → PR\n\n**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.\n\n\n## Usage\n\n### Basic Command\n```bash\n./github-contribution.sh <username> <owner/repo> <issue-number> <branch-name> [projects-root]\n```\n\n### Examples\n```bash\n# Fix issue #123 in openclaw/openclaw\n./github-contribution.sh Linux2010 openclaw/openclaw 123 fix/issue-description\n\n# Specify custom project root\n./github-contribution.sh Linux2010 openclaw/openclaw 456 fix/bug-fix /custom/path\n```\n\n## Fork Protection Best Practices\n\n### Main Branch Rules\n1. **Never commit directly** to fork's main branch\n2. **Always sync first** before creating new branches\n3. **Use feature branches** for all development work\n4. **Regular cleanup** of local pollution files\n\n### Safe Synchronization Script\n```bash\n#!/bin/bash\n# sync-fork.sh - Safe fork synchronization\n\ngit checkout main\ngit fetch upstream\ngit reset --hard upstream/main\ngit clean -fdx  # Remove all untracked files\n\n# Verify clean state\nif [[ $(git status --porcelain) ]]; then\n    echo \"❌ Warning: Working tree not clean\"\n    exit 1\nfi\necho \"✅ Fork synchronized successfully\"\n```\n\n### Local Git Configuration\n```bash\n# Prevent accidental main branch pushes\ngit config branch.main.pushRemote no_push\n\n# Set safe push default\ngit config push.default nothing\n```\n\n## Workflow Steps\n\n### Step 1: Fork Validation\n- Check if fork exists and is accessible\n- Verify upstream remote configuration\n- Validate current fork state cleanliness\n\n### Step 2: Synchronization  \n- Fetch latest from upstream official repository\n- Reset local main branch to match upstream exactly\n- Clean any untracked/local pollution files\n- Push synchronized state to fork (if permissions allow)\n\n### Step 3: Feature Branch Creation\n- Create new branch from clean main\n- Apply necessary changes and fixes\n- Commit with proper semantic format\n- Push feature branch to fork\n\n### Step 4: PR Creation\n- Generate PR with complete template\n- Link to relevant issue numbers\n- Include proper change type and scope\n- Add security impact assessment\n\n---\n\n## 🩺 Bug Fix Module: Change Plan\n\nBefore fixing any bug, **always write a change plan first**. This ensures minimal, safe changes and makes PR review easier.\n\n### The 5-Point Analysis\n\nAnswer these 5 questions in plain language before writing any code:\n\n| # | Question | Purpose |\n|---|----------|---------|\n| 1 | **Observed behavior** | What's broken? (What the user sees) |\n| 2 | **Expected behavior** | What should happen? (Correct behavior) |\n| 3 | **Suspected root cause** | Where's the bug? (Specific code location) |\n| 4 | **Safest seam to modify** | Minimal change location? (Narrowest fix) |\n| 5 | **Risk surface** | What else could break? (Impact scope) |\n\n### Change Plan Template\n\n```markdown\n## Change Plan for Issue #<number>\n\n1. **Observed behavior**:\n   <Describe what's broken - the user-visible symptom>\n\n2. **Expected behavior**:\n   <Describe what should happen instead>\n\n3. **Suspected root cause**:\n   <Point to specific file/line/function that causes the bug>\n\n4. **Safest seam to modify**:\n   <Identify the minimal code change location - smallest safe fix>\n\n5. **Risk surface**:\n   <List what could be affected by this change>\n```\n\n### Example: Issue #5968\n\n```markdown\n## Change Plan for Issue #5968\n\n1. **Observed behavior**:\n   `extract_content_or_reasoning()` crashes when `response.choices` is None, missing, or empty list.\n\n2. **Expected behavior**:\n   Function should return empty string gracefully when no usable choices exist.\n\n3. **Suspected root cause**:\n   Line `msg = response.choices[0].message` in `agent/auxiliary_client.py` assumes choices is always non-empty.\n\n4. **Safest seam to modify**:\n   Add a guard at the top of `extract_content_or_reasoning()` before accessing choices:\n   `if not getattr(response, \"choices\", None): return \"\"`\n\n5. **Risk surface**:\n   Minimal - only affects edge cases where API response is malformed.\n```\n\n### When to Use Change Plan\n\n| Scenario | Required? |\n|----------|-----------|\n| Bug fix | ✅ Always |\n| Paper-cut UX improvement | ✅ Always |\n| Feature addition | ❌ Use feature spec instead |\n| Refactoring | ❌ Use refactor plan instead |\n| Documentation fix | ❌ Not needed |\n\n### Benefits of Change Plan\n\n| Benefit | Why It Matters |\n|---------|----------------|\n| **Forces understanding** | Can't fix what you don't understand |\n| **Defines boundaries** | Prevents scope creep and \"opportunistic\" changes |\n| **Reduces risk** | Identifies potential side effects upfront |\n| **Speeds review** | Maintainer can understand intent in 20 seconds |\n| **Enables rollback** | Clear what was changed and why |\n\n### Change Plan Checklist\n\nBefore coding:\n- [ ] Can you describe the bug in one sentence?\n- [ ] Can you point to the exact line causing it?\n- [ ] Is your fix the smallest possible change?\n- [ ] Have you identified what else could break?\n- [ ] Will this change need a regression test?\n\nIf you answered \"no\" to any question, **do more investigation before coding**.\n\n---\n\n## 🧪 Live-Proof：如何让 PR 获得官方认可\n\n> **详细案例库见 [`live-proof-cases.md`](./live-proof-cases.md)** — 记录了真实 PR 中通过 ClawSweeper 评审的 live-proof 实践，开发 PR 时必读。\n\n### 什么是 live-proof？\n\nOpenClaw 的自动评审机器人 ClawSweeper 要求 PR 提供证明修复**实际生效**的证据。仅有\"单元测试通过\"不算充分 proof。\n\n**目标评级**：`status: 👀 ready for maintainer look` + `proof: sufficient` + Overall ≥ 🐚 platinum hermit\n\n### 评级体系（短板效应）\n\n`Overall = Proof 和 Patch quality 中较弱者`\n\n即使 patch 质量很高，如果 proof 不足，整体评级仍会被拉低。\n\n| 评级 | 含义 |\n|------|------|\n| 🦀 challenger crab | 卓越就绪 |\n| 🦞 diamond lobster | 很强，少量审查 |\n| 🐚 platinum hermit | 良好普通 PR |\n| 🦪 silver shellfish | 信号薄弱，需改进 |\n| 🧂 unranked krab | 不可合并 |\n\n### Live-Proof 形式\n\n被合并的 PR 全部使用**终端命令输出**（不用截图/视频）：\n\n| 类型 | 命令 | 适用 |\n|------|------|------|\n| 直接验证 | `node --import tsx -e \"...\"` | 配置验证、纯函数 |\n| 聚焦测试 | `node scripts/run-vitest.mjs <path>` | 运行时修复 |\n| 格式检查 | `git diff --check` | 代码格式 |\n\n### 最有效模式：BEFORE vs AFTER 对比\n\n```\nBEFORE (current main) - <invalid input> passed validation with ok: true\nAFTER - <invalid input> is rejected with clear error message\n```\n\n### 提交前必查\n\n- [ ] 提供了 BEFORE vs AFTER 对比（不只是 AFTER）\n- [ ] Proof 是终端命令输出，不是只有\"测试通过\"\n- [ ] 覆盖了边界值（最小、最大、无效）\n- [ ] 覆盖了幂等性（如涉及迁移）\n- [ ] **修改前能复现 bug**（测试在修复前会失败）\n- [ ] 修改的代码路径在正常情况下会被走到\n\n### 关键教训\n\n1. **收紧 config 验证 = 破坏性变更**：必须配 `openclaw doctor --fix` 迁移，否则已有配置升级后报错\n2. **Doctor 迁移用替换而非删除**：`gateway.port = DEFAULT` 比 `delete gateway.port` 更安全（配置行为明确）\n3. **修改前先证明 bug 在该路径**：写一个修复前会失败的测试；如果修复前就通过，bug 不在这\n4. **诚实面对找不到根因**：硬提交无效修复会被打 🧂 unranked krab；关闭 PR + 评论 issue 更好\n\n### 详细案例\n\n- ✅ **成功案例 #110051**：配置验证 + Doctor 迁移，`🦞 diamond lobster`\n- ✅ **成功案例 #109875**：竞品学习对象，`👀 ready for maintainer look`\n- ❌ **失败案例 #109885**：修改了不可达路径，`🧂 unranked krab` -> 关闭\n\n---\n\n## Error Handling\n\n### Common Issues & Solutions\n\n#### Fork Not Clean\n- **Problem**: Local main branch has extra commits/files\n- **Solution**: Force reset to upstream and clean untracked files\n\n#### Permission Denied (Workflow Scope)\n- **Problem**: Token lacks workflow permissions\n- **Solution**: Use web-based PR creation or update token permissions\n\n#### Upstream Not Configured  \n- **Problem**: Missing upstream remote\n- **Solution**: Auto-add upstream remote pointing to official repository\n\n#### Branch Already Exists\n- **Problem**: Feature branch already exists\n- **Solution**: Use unique branch naming or delete existing branch\n\n## Security Considerations\n\n### Token Permissions\n- **Minimum Required**: `repo` scope\n- **Optional**: `workflow` scope (for full automation)\n- **Never Grant**: Excessive permissions beyond contribution needs\n\n### Local Security\n- **File Cleanup**: Always clean working directory after contributions\n- **Credential Management**: Use secure credential storage\n- **Audit Trail**: Maintain logs of all contribution activities\n\n## Integration with Other Skills\n\n### PR Advocacy Skill\n- Hand off created PRs to PR Advocacy for monitoring\n- Share PR tracking information for continuous follow-up\n- Coordinate review response and maintenance\n\n### Document Spell Check Skill  \n- Pre-validate documentation changes before PR creation\n- Ensure all text content passes spell checking\n- Maintain documentation quality standards\n\n## High-Quality PR Best Practices (Maximize Merge Success Rate)\n\n### 🎯 Merge Success Rate Formula (Based on 30+ Merged PRs Analysis)\n\n```\nMerge Success Rate = \n  (PR Description Completeness × 0.2) +\n  (Review Response Speed × 0.25) +\n  (Test Coverage × 0.2) +\n  (Conflict Resolution Status × 0.15) +\n  (Review Resolution Rate × 0.2)\n```\n\n**Target**: > 80% success rate\n\n### ✅ 10 Success Characteristics (Must Follow 100%)\n\n1. ✅ **Complete PR Description** - Use template, fill ALL required fields\n2. ✅ **Fast Review Response** - < 30 minutes average response time\n3. ✅ **Small Focused Commits** - 1 commit solves 1 problem\n4. ✅ **100% Test Coverage** - Include edge cases and regression tests\n5. ✅ **Zero Conflicts** - Daily rebase upstream, keep CLEAN\n6. ✅ **Changelog Updated** - All user-visible changes\n7. ✅ **Security Checklist** - 5 required security questions\n8. ✅ **Human Verification Statement** - Manual test content + untested areas\n9. ✅ **Review Conversations Resolved** - 100% resolve bot review comments\n10. ✅ **Rollback Plan** - Rollback steps + known issues\n\n### 📋 Pre-Submission Checklist\n\nBefore pushing PR:\n\n**Code Quality:**\n- [ ] Title format: `type(scope): description`\n- [ ] Commit message: includes \"what\" + \"why\"\n- [ ] At least 1 new test case\n- [ ] CHANGELOG.md updated\n- [ ] 4-7 meaningful commits\n\n**CI Pre-flight (MUST pass locally):**\n- [ ] `pnpm protocol:check` - Protocol validation\n- [ ] `pnpm test` - All tests pass\n- [ ] `pnpm lint` - No lint errors\n- [ ] `pnpm tsc --noEmit` - TypeScript compilation\n\n**Review Readiness:**\n- [ ] Ready to respond within 24h\n- [ ] Greptile/Aisle Security comments addressed\n- [ ] Security questions answered (5 required)\n\n### 📊 High Success Rate PR Patterns\n\n#### Pattern 1: Security Fix Response (vincentkoc #44437)\n```\n7 commits in same day:\n1. Main fix implementation\n2. Changelog update\n3. Merge main (resolve conflicts)\n4. Tests: add coverage for review comments\n5. Fix: address Greptile suggestions\n6. Extra hardening (defensive programming)\n7. Merge main (final sync)\n```\n\n**Key Learnings:**\n- ✅ Separate commits for review responses\n- ✅ Tests and docs as separate commits\n- ✅ Frequent merge main to resolve conflicts\n- ✅ Extra hardening shows professionalism\n\n#### Pattern 2: Security Report Response (gumadeiras #44176)\n```markdown\nWhen Aisle Security reports issues:\n\n1. Quote SECURITY.md to explain why it's out of scope\n2. But still fix it (defensive programming)\n3. List specific hardening done\n4. Provide verification commands\n```\n\n**Key Learnings:**\n- ✅ Respond to security reports first\n- ✅ Explain scope判断 basis\n- ✅ Still fix it (show cooperation)\n- ✅ Provide verification method\n\n### ⚠️ Common Mistakes That Reduce Merge Rate\n\n| Mistake | Impact | Solution |\n|---------|--------|----------|\n| ❌ Missing Changelog | -20% | Always update CHANGELOG.md |\n| ❌ Slow review response (>24h) | -25% | Respond within 24h, ideally <30min |\n| ❌ Incomplete test coverage | -20% | Add tests for edge cases |\n| ❌ Merge conflicts | -15% | Daily rebase upstream |\n| ❌ Unresolved bot reviews | -20% | 100% resolve all comments |\n| ❌ CI failures | Automatic reject | Pre-flight check locally |\n\n### 🎯 Quality Metrics\n\n| Metric | Target | Current Best Practice |\n|--------|--------|----------------------|\n| **Greptile Score** | ≥ 4/5 | Address all P1/P2 issues |\n| **Aisle Security** | 0 unresolved | Respond or fix all |\n| **Test Coverage** | ≥ 1 new test | Include edge cases |\n| **CI Pass Rate** | 100% | Pre-check locally |\n| **Behind upstream** | 0 commits | Daily rebase |\n| **Response Time** | < 24h | Same day preferred |\n\n### 📝 PR Template Best Practices\n\n**Title Format:**\n```\n✅ fix(hooks): fail closed on unreadable loader paths\n✅ feat(context-engine): plumb sessionKey into all methods\n✅ docs: codify American English spelling convention\n✅ security: include accountId in session keys\n```\n\n**Commit Message Structure:**\n```\nFirst line: What was done (concise description)\n\nSecond paragraph: Why (problem background, impact)\n\nOptional: Regeneration-Prompt / AI assistance notes\n```\n\n**Example (#44411):**\n```\nfix(ci): restore generated protocol swift outputs\n\nRegenerate the Swift protocol models so PushTestResult keeps the \ntransport field required by the current gateway schema, and update \nprotocol:check to diff both generated Swift destinations because \nthe generator writes both files.\n\nRegeneration-Prompt: |\n  Investigate the protocol CI failure on current origin/main...\n```\n\n---\n\n## Best Practices\n\n### For Contributors\n- Always start from clean, synchronized main branch\n- Use descriptive branch names following convention\n- Fill complete PR templates with all required fields\n- Test changes locally before pushing\n- **Always rebase on the original PR branch** (never create new branches for rebase)\n- **Follow High-Quality PR Best Practices** (see section above)\n\n### PR Rebase Best Practices (Critical!)\n\n**Golden Rule**: Always rebase on the **original PR branch**, never create a new branch.\n\n#### Correct Rebase Workflow\n\n```bash\n# 1. Confirm current branch\ngit branch --show-current\n\n# 2. Confirm PR's branch name\ngh pr view <PR-number> --json headRefName --jq .headRefName\n\n# 3. Switch to correct branch if needed\ngit checkout <PR-branch-name>\n\n# 4. Rebase on the SAME branch (do NOT create new branch)\ngit fetch upstream\ngit rebase upstream/main\n\n# 5. Push to the SAME branch\ngit push -f origin <same-branch-name>\n```\n\n#### Common Mistakes to Avoid\n\n| ❌ Wrong | ✅ Correct |\n|---------|---------|\n| `git checkout -b new-branch` then rebase | Stay on original branch, rebase there |\n| Switch to different branch for rebase | Rebase on PR's own branch |\n| Skip branch confirmation | Always run `git branch --show-current` first |\n| Don't verify PR branch name | Use `gh pr view` to confirm |\n\n#### Why This Matters?\n\n1. **Clean branch history** - No duplicate branches created\n2. **Avoid confusion** - PR always linked to same branch\n3. **Reduce errors** - Won't push to wrong branch\n4. **Easy management** - All changes in one place\n\n#### Pre-Rebase Checklist\n\nBefore rebasing:\n- [ ] Run `git branch --show-current` to confirm current branch\n- [ ] Run `gh pr view <num> --json headRefName` to confirm PR branch\n- [ ] Ensure both names match before proceeding\n- [ ] If mismatch, `git checkout <PR-branch>` first\n\n#### Post-Rebase Checklist\n\nAfter rebasing:\n- [ ] Run `git log --oneline -3` to verify commits\n- [ ] Run `pnpm test` or relevant tests\n- [ ] Run `git push -f origin <branch>` to update PR\n\n#### Example: Rebase PR #48568\n\n```bash\n# Check current branch\n$ git branch --show-current\nfix/47752-final  # ✅ Correct!\n\n# Confirm PR branch\n$ gh pr view 48568 --json headRefName --jq .headRefName\nfix/47752-final  # ✅ Matches!\n\n# Rebase on same branch\ngit fetch upstream\ngit rebase upstream/main\n\n# Test\npnpm test src/infra/heartbeat-runner.timeout.test.ts\n\n# Push to same branch\ngit push -f origin fix/47752-final\n```\n\n#### Troubleshooting\n\n**Problem**: Accidentally created new branch during rebase\n\n**Solution**:\n```bash\n# Go back to original branch\ngit checkout <original-branch>\n\n# Rebase there instead\ngit rebase upstream/main\n\n# Delete the accidental branch\ngit branch -D <accidental-branch>\n\n# Push to original branch\ngit push -f origin <original-branch>\n```\n\n---\n\n### For Maintainers  \n- Regularly audit fork cleanliness\n- Update synchronization scripts as needed\n- Monitor token permissions and security\n- Document contribution workflows for team members\n\n## Limitations\n\n### GitHub Fork Restrictions\n- Cannot set full branch protection rules on forks\n- Limited automation capabilities without workflow permissions\n- Manual intervention sometimes required for complex scenarios\n\n### Workarounds\n- Use local git hooks for additional protection\n- Implement manual verification steps in workflow\n- Leverage GitHub web interface for final PR creation when needed\n\n## Maintenance\n\n### Updates\n- Regular script updates for new GitHub API changes\n- Security patches for authentication methods\n- Performance improvements for large repositories\n\n### Monitoring\n- Track success/failure rates of contribution attempts\n- Monitor GitHub API rate limit usage\n- Collect user feedback for workflow improvements\n\nFile v1.7.3:_meta.json\n\n{\n  \"ownerId\": \"kn7djfrkxdrrb6syjdv4vvtmp18252ry\",\n  \"slug\": \"github-contribution\",\n  \"version\": \"1.7.3\",\n  \"publishedAt\": 1784821527579\n}\n\nFile v1.7.3:github-contribution-workflow.md\n\n# GitHub 开源项目贡献完整工作流程\n\n## 1. Fork 和同步项目\n\n### Fork 官方仓库\n- 访问目标项目的 GitHub 页面（例如 `https://github.com/owner/repo`）\n- 点击右上角的 \"Fork\" 按钮\n- 选择你的 GitHub 账户作为 fork 目标\n\n### 克隆你的 Fork\n```bash\ngit clone https://github.com/your-username/repo.git\ncd repo\n```\n\n### 添加上游远程仓库\n```bash\ngit remote add upstream https://github formulate the official repository URL\ngit remote -v  # 验证远程仓库配置\n```\n\n### 同步 Fork 到最新状态\n```bash\n# 切换到 main/master 分支\ngit checkout main\n\n# 获取上游仓库的最新更改\ngit fetch upstream\n\n# 将上游的更改合并到本地\ngit merge upstream/main\n\n# 推送到你的 fork\ngit push origin main\n```\n\n## 2. 创建功能分支\n\n### 基于最新的 main 分支创建新分支\n```bash\n# 确保在 main 分支且已同步\ngit checkout main\ngit pull upstream main\n\n# 创建新的功能分支（使用描述性名称）\ngit checkout -b fix/issue-description\n# 或者\ngit checkout -b feature/new-functionality\n```\n\n### 分支命名约定\n- `fix/` - 用于 bug 修复\n- `feature/` - 用于新功能\n- `docs/` - 用于文档更新\n- `chore/` - 用于维护任务\n\n## 3. 开发和测试\n\n### 进行代码更改\n- 在功能分支上进行所有开发工作\n- 遵循项目的代码风格和规范\n- 编写必要的测试用例\n- 更新相关文档（如果需要）\n\n### 提交更改\n```bash\n# 查看更改状态\ngit status\n\n# 添加更改的文件\ngit add .\n\n# 提交更改（使用清晰的提交信息）\ngit commit -m \"fix: resolve issue with XYZ component\"\n\n# 推送到你的 fork\ngit push origin fix/issue-description\n```\n\n### 提交信息格式\n遵循 conventional commits 格式：\n- `fix:` - bug 修复\n- `feat:` - 新功能\n- `docs:` - 文档更新\n- `style:` - 代码格式更改\n- `refactor:` - 代码重构\n- `test:` - 测试相关\n- `chore:` - 构建过程或辅助工具的变动\n\n## 4. 创建 Pull Request\n\n### 通过 GitHub 网页界面创建 PR\n1. 访问你的 fork 仓库页面\n2. GitHub 通常会自动检测到新推送的分支并显示 \"Compare & pull request\" 按钮\n3. 点击该按钮进入 PR 创建页面\n\n### PR 标题和描述\n- **标题**: 清晰描述更改的目的（例如：\"Fix null pointer exception in auth handler\"）\n- **描述**: \n  - 说明问题的背景\n  - 描述解决方案\n  - 提及相关的 issue（使用 `Closes #123` 或 `Fixes #123`）\n  - 列出主要的更改点\n\n### PR 检查清单\n- [ ] 代码通过所有测试\n- [ ] 遵循项目代码风格\n- [ ] 包含必要的测试用例\n- [ ] 更新了相关文档\n- [ ] PR 描述清晰完整\n- [ ] 关联了相关 issue\n\n## 5. PR 审查和合并\n\n### 处理审查反馈\n- 及时响应审查者的评论\n- 根据反馈进行必要的修改\n- 使用新的提交来处理反馈（不要强制推送覆盖历史）\n\n### 更新 PR\n```bash\n# 在功能分支上进行修改\ngit add .\ngit commit -m \"address review feedback: improve error handling\"\ngit push origin fix/issue-description\n```\n\n### PR 合并后清理\n```bash\n# 切换回 main 分支\ngit checkout main\n\n# 删除本地功能分支\ngit branch -d fix/issue-description\n\n# 删除远程功能分支（可选）\ngit push origin --delete fix/issue-description\n```\n\n## 常见问题和最佳实践\n\n### 保持分支同步\n如果 PR 审查时间较长，可能需要将最新的上游更改合并到你的功能分支：\n```bash\ngit checkout main\ngit pull upstream main\ngit checkout fix/issue-description\ngit rebase main\ngit push --force-with-lease origin fix/issue-description\n```\n\n### 避免强制推送\n除非必要（如 rebase 后），避免使用 `--force` 推送，使用 `--force-with-lease` 更安全。\n\n### 小而专注的 PR\n- 每个 PR 应该解决一个具体的问题\n- 避免在一个 PR 中包含多个不相关的更改\n- 这样更容易审查和合并\n\n### 社区礼仪\n- 保持礼貌和专业的沟通\n- 及时响应审查反馈\n- 感谢维护者的审查时间\n- 遵循项目的贡献指南（CONTRIBUTING.md）\n\nFile v1.7.3:live-proof-cases.md\n\n# Live-Proof 案例库\n\n> 本文件记录真实 PR 中通过 ClawSweeper 评审、获得 `status: 👀 ready for maintainer look` 的 live-proof 实践。\n> 开发 PR 时参考本案例库，确保提供的 proof 足够充分。\n\n## 目录\n\n- [ClawSweeper 评级体系](#clawsweeper-评级体系)\n- [什么是 live-proof](#什么是-live-proof)\n- [案例一：配置验证类修复（#110051）](#案例一配置验证类修复110051)\n- [案例二：竞品对比学习（#109875）](#案例二竞品对比学习109875)\n- [失败案例：修改了不可达路径（#109885）](#失败案例修改了不可达路径109885)\n- [通用 Proof 模板](#通用-proof-模板)\n- [检查清单](#检查清单)\n\n---\n\n## ClawSweeper 评级体系\n\nClawSweeper（OpenClaw 的自动评审机器人）对 PR 给出三个维度的甲壳类评级：\n\n| 评级 | 含义 | 可合并性 |\n|------|------|----------|\n| 🦀 challenger crab | 罕见，卓越的就绪状态 | 极高 |\n| 🦞 diamond lobster | 很强，仅需少量 maintainer 审查 | 高 |\n| 🐚 platinum hermit | 良好的普通 PR，普通审查即可 | 中高 |\n| 🦐 gold shrimp | 有用信号，但 proof/confidence 仍有限 | 中 |\n| 🦪 silver shellfish | 信号薄弱，proof/validation/实现需改进 | 低 |\n| 🧂 unranked krab | 不可合并（proof 缺失或有严重问题） | 不可合并 |\n| 🌊 off-meta tidepool | 评级不适用 | N/A |\n\n### 三个评分维度\n\n| 维度 | 说明 |\n|------|------|\n| **Overall** | 综合 = proof 和 patch quality 中较弱者（短板效应） |\n| **Proof** | 真实行为证明的充分性 |\n| **Patch quality** | 代码实现质量 |\n\n> ⚠️ **关键规则**：`Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.`\n> 即使 patch 质量是 🐚 platinum hermit，如果 proof 只有 🦪 silver shellfish，整体仍是 🦪。\n\n### 状态标签\n\n| 标签 | 含义 |\n|------|------|\n| `status: 📣 needs proof` | 需要补充真实行为证明才能合并 |\n| `status: 👀 ready for maintainer look` | ClawSweeper 无 contributor 阻塞项，等待 maintainer 审查 |\n| `proof: sufficient` | Contributor 真实行为证明充分 |\n\n**目标**：获得 `status: 👀 ready for maintainer look` + `proof: sufficient`。\n\n---\n\n## 什么是 live-proof\n\nLive-proof（真实行为证明）是 ClawSweeper 要求的、证明修复**实际生效**的证据。\n\n### ❌ 不是 live-proof 的东西\n\n- 只有单元测试通过（\"X tests passed\"）\n- 纯代码阅读得出的结论（\"代码逻辑应该正确\"）\n- 声称修复有效但没有运行验证\n\n### ✅ 是 live-proof 的东西\n\n被合并的 PR 全部使用**终端命令输出**作为 proof，不用截图/视频：\n\n| Proof 类型 | 命令模式 | 适用场景 |\n|-----------|---------|---------|\n| 直接验证 | `node --import tsx -e \"...\"` | 配置验证、纯函数行为 |\n| 聚焦测试 | `node scripts/run-vitest.mjs <path>` | 运行时修复、回归测试 |\n| 完整 gate | `node scripts/check-changed.mjs -- <files>` | 多文件变更 |\n| 格式检查 | `git diff --check` / `oxfmt --check` | 代码格式 |\n| Autoreview | `autoreview --mode uncommitted` | 代码审查 |\n\n### 关键：BEFORE vs AFTER 对比\n\n最有效的 proof 是展示**修复前**和**修复后**的对比：\n\n```\nBEFORE (current main) - gateway.port: 65536 passed validation with ok: true\nAFTER - gateway.port: 65536 is rejected with clear error message\n```\n\n---\n\n## 案例一：配置验证类修复（#110051）\n\n**Issue**: #109293 - `gateway.port` 接受超出 TCP 端口范围的值\n**PR**: https://github.com/openclaw/openclaw/pull/110051\n**修复类型**: 配置 schema 收紧 + Doctor 迁移\n\n### 问题描述\n\n`gateway.port` 的 Zod schema 只有 `.positive()` 没有 `.max(65535)`，导致 `65536` 等无效端口通过验证。\n\n### 关键教训：收紧 config 验证 = 破坏性变更\n\n**这是最重要的教训。** 收紧 config schema 会让之前合法的配置变非法，必须配 Doctor 迁移！\n\n> CLAUDE.md 明确规定：\"If a config change invalidates existing files, add a matching `openclaw doctor --fix` migration.\"\n\n只加 schema 约束而不加 Doctor 迁移的后果：\n- 已有 `gateway.port: 65536` 的用户升级后直接报错，无升级路径\n- ClawSweeper 标记 `merge-risk: 🚨 compatibility`\n- 无法获得 `status: 👀 ready for maintainer look`\n\n### Doctor 迁移设计决策\n\n迁移应**替换为默认值**而非删除键：\n\n| 策略 | #109875（竞品） | #110051（我们的） |\n|------|-----------------|------------------|\n| 做法 | `delete gateway.port` | `gateway.port = DEFAULT_GATEWAY_PORT` |\n| 迁移后配置 | 无 port 键 | `port: 18789` |\n| 用户体验 | 困惑：配置里没 port，网关用什么端口？ | 明确：绑定到默认 18789 |\n\n### 提供的 Proof 内容\n\n**1. Schema validation - BEFORE vs AFTER**\n\n```sh\n# BEFORE (current main) - passes validation\n{\"ok\": true, \"config\": {\"gateway\": {\"port\": 65536}}}\n\n# AFTER - rejected\n$ node --import tsx -e \"\nimport { validateConfigObjectRaw } from './src/config/validation.ts';\nconsole.log(JSON.stringify(validateConfigObjectRaw({gateway:{port:65536}}), null, 2));\"\n{\n  \"ok\": false,\n  \"issues\": [{\n    \"path\": \"gateway.port\",\n    \"message\": \"Too big: expected number to be <=65535 (maximum: 65535)\"\n  }]\n}\n```\n\n**2. Doctor migration - 升级路径证明**\n\n```sh\n$ node --import tsx -e \"\nimport { applyLegacyDoctorMigrations } from './src/commands/doctor/shared/legacy-config-compat.js';\nconst raw = {gateway:{port:65536}};\nconst { next, changes } = applyLegacyDoctorMigrations(raw);\nconsole.log('changes:', JSON.stringify(changes));\nconsole.log('next:', JSON.stringify(next));\"\nchanges: [\"Replaced out-of-range gateway.port (65536) with default 18789...\"]\nnext: {\"gateway\":{\"port\":18789}}\n```\n\n覆盖场景：\n- port 65536（超上限）→ 替换为默认\n- port 0（低于下限）→ 替换为默认\n- port 65535（有效）→ 无迁移\n- port 65536 + bind:loopback → port 替换，bind 保留\n- 幂等性：第二次迁移无变化\n\n**3. 测试结果**\n\n```\n- node scripts/run-vitest.mjs src/config/zod-schema.gateway.test.ts - 7 tests\n- node scripts/run-vitest.mjs src/config/validation.policy.test.ts - 8 tests\n- node scripts/run-vitest.mjs src/commands/doctor/shared/legacy-config-migrate.test.ts - 158 tests\n- git diff --check - passed\n```\n\n### 评级结果\n\n| 维度 | 评级 |\n|------|------|\n| Patch quality | 🐚 platinum hermit |\n| Proof | 🦞 diamond lobster（加入 Doctor proof 后） |\n| Overall | 🦞 diamond lobster |\n\n---\n\n## 案例二：竞品对比学习（#109875）\n\n**Issue**: 同 #109293\n**PR**: https://github.com/openclaw/openclaw/pull/109875\n**结果**: 获得 `status: 👀 ready for maintainer look` + `proof: sufficient`\n\n### 它做对了什么\n\n1. **Doctor 迁移配对**：schema 收紧 + `openclaw doctor --fix` 迁移\n2. **BEFORE vs AFTER 对比**：明确展示修复前后验证输出\n3. **Doctor 迁移的完整场景证明**：6 个场景，每个都有终端输出\n4. **测试分散在正确的位置**：验证策略测试 + 迁移测试\n\n### ClawSweeper 的关键评语\n\n> `status: 👀 ready for maintainer look`: ClawSweeper has no concrete contributor-facing blocker left for this PR.\n> `proof: sufficient`: The PR body includes after-fix terminal output for raw validation and Doctor migration behavior, including invalid, valid-boundary, idempotence, and sibling-key cases.\n\n### 它的不足（我们改进的点）\n\n1. Doctor 迁移用 `delete` 而非 `replace`，用户体验较差\n2. `legacyRules` 的 `match` 没有覆盖非数字/非整数类型\n3. 迁移测试没覆盖负数端口\n\n---\n\n## 失败案例：修改了不可达路径（#109885）\n\n**Issue**: #109673 - `browser.headless` 配置被忽略\n**PR**: https://github.com/openclaw/openclaw/pull/109885（已关闭）\n**结果**: 🧂 unranked krab → 关闭\n\n### 失败原因\n\n**修改了一个正常代码路径不会走到的 fallback。**\n\n```typescript\n// resolveManagedBrowserHeadlessMode 的 fallback (line 730)\nreturn { headless: resolved.headless, source: \"default\" };  // 我改成了 resolved.headlessSource\n```\n\nClawSweeper 的批评：\n> The changed final fallback is bypassed by the normal resolved profile according to the PR's own tests, so the patch does not yet identify or repair the boundary producing the reported behavior.\n\n### 教训\n\n1. **修改前先证明 bug 在该路径**：写一个测试，在修复前应该失败。如果修复前测试就通过，说明 bug 不在这。\n2. **不要修改\"看起来不对\"但实际不影响行为的代码**：要验证改动是否真正改变运行时行为。\n3. **ClawSweeper 会读你的测试**：如果测试本身说明\"正常 profile 走早期分支\"，它就知道你的 fallback 修改无效。\n4. **找不到根因时不要硬提交**：诚实说明，关闭 PR，评论 issue 说明调查结果。\n\n### 正确的流程\n\n```\n1. 写测试复现 bug（修复前应失败）\n   ↓ 失败 = 找到了根因\n2. 修复代码\n   ↓ 测试通过\n3. 验证修复改变了运行时行为（live-proof）\n   ↓\n4. 提交 PR\n```\n\n---\n\n## 通用 Proof 模板\n\n### 配置验证类修复\n\n```markdown\n## Evidence\n\n### 1. Schema validation - BEFORE vs AFTER\n\n**BEFORE** (current main) - `<invalid input>` passed validation with `ok: true`\n\n**AFTER** - `<invalid input>` is rejected:\n\n\\`\\`\\`sh\n$ node --import tsx -e \"\nimport { validateConfigObjectRaw } from './src/config/validation.ts';\nconsole.log(JSON.stringify(validateConfigObjectRaw({<path>:<value>}), null, 2));\"\n<actual output showing ok:false + error message>\n\\`\\`\\`\n\n### 2. Doctor migration - upgrade path proof\n\n\\`\\`\\`sh\n$ node --import tsx -e \"\nimport { applyLegacyDoctorMigrations } from './src/commands/doctor/shared/legacy-config-compat.js';\nconst raw = {<path>:<invalid_value>};\nconst { next, changes } = applyLegacyDoctorMigrations(raw);\nconsole.log('changes:', JSON.stringify(changes));\nconsole.log('next:', JSON.stringify(next));\"\n<output showing repair>\n\\`\\`\\`\n\n覆盖场景：\n- 无效值 → 修复\n- 有效边界值 → 不变\n- 幂等性\n- sibling key 保留\n\n### 3. Test results\n- `node scripts/run-vitest.mjs <test-path>` - N tests passed\n- `git diff --check` - passed\n```\n\n### 运行时逻辑修复\n\n```markdown\n## Evidence\n\n- Focused proof: `node scripts/run-vitest.mjs <test-path>` - N tests passed.\n- BEFORE: <描述修复前的错误行为，最好有测试断言证明>\n- AFTER: <描述修复后的正确行为>\n- `git diff --check` - passed.\n```\n\n### Bug 复现型修复\n\n```markdown\n## Evidence\n\n### Regression test (fails before fix, passes after)\n\\`\\`\\`\nnode scripts/run-vitest.mjs <test-path>\n# Before fix: FAIL - <error>\n# After fix: PASS\n\\`\\`\\`\n\n### Live behavior proof\n<运行实际命令展示修复前后行为变化>\n```\n\n---\n\n## 检查清单\n\n### 提交 PR 前的 proof 检查\n\n- [ ] 提供了 BEFORE vs AFTER 对比（不只是 AFTER）\n- [ ] Proof 是终端命令输出，不是只有\"测试通过\"\n- [ ] 覆盖了边界值（最小、最大、无效）\n- [ ] 覆盖了幂等性（如涉及迁移）\n- [ ] 覆盖了 sibling key 保留（如涉及删除/修改配置项）\n- [ ] 如果收紧了 config 验证，配了 Doctor 迁移\n- [ ] 修复前能复现 bug（测试在修复前会失败）\n\n### 自问：修改是否真正改变运行时行为？\n\n- [ ] 我写的测试在**修复前**会失败吗？\n- [ ] 我修改的代码路径在**正常情况下**会被走到吗？\n- [ ] ClawSweeper 读完我的测试后，会认为我的修复有效吗？\n\n如果任何一项为\"否\"，**不要提交**，继续调查根因。\n\n### 达标目标\n\n提交 PR 后，目标评级：\n- ✅ `status: 👀 ready for maintainer look`\n- ✅ `proof: sufficient`\n- ✅ Overall ≥ 🐚 platinum hermit\n\n---\n\n## 经验总结\n\n### 1. 收紧配置验证必须配 Doctor 迁移\n\n这是 OpenClaw 的硬规则。任何让之前合法配置变非法的变更，都要提供 `openclaw doctor --fix` 升级路径。\n\n### 2. Proof 要展示真实运行时行为\n\nClawSweeper 明确说：\"Only unit-test claims are provided\" 是不够的。要运行实际命令展示修复效果。\n\n### 3. BEFORE vs AFTER 对比最有效\n\n明确展示\"修复前是坏的，修复后是好的\"比单纯展示\"修复后是好的\"更有说服力。\n\n### 4. 修改前先证明 bug 在该路径\n\n写一个在修复前会失败的测试。如果修复前测试就通过，说明 bug 不在你修改的地方。\n\n### 5. Doctor 迁移用替换而非删除\n\n替换为默认值比删除键更安全：用户看到的配置文件行为明确，不依赖隐式默认。\n\n### 6. 诚实面对找不到根因的情况\n\n如果代码逻辑看起来正确但 bug 仍存在，可能 bug 在运行时其他地方或已被间接修复。诚实说明，关闭 PR，评论 issue，比硬提交一个无效修复好。\n\nFile v1.7.3:skill-card.md\n\n## Description: <br>\nAutomates a GitHub contribution workflow for discovering maintainer-approved issues, synchronizing a fork, creating a feature branch, and preparing pull request guidance. <br>\n\nThis skill is ready for commercial/non-commercial use. <br>\n\n## Publisher: <br>\n[linux2010](https://clawhub.ai/user/linux2010) <br>\n\n### License/Terms of Use: <br>\nMIT-0 <br>\n\n\n## Use Case: <br>\nDevelopers and open source contributors use this skill to identify suitable GitHub issues, keep forks aligned with upstream projects, create focused feature branches, and assemble pull requests with change plans and live proof. <br>\n\n### Deployment Geography for Use: <br>\nGlobal <br>\n\n## Known Risks and Mitigations: <br>\nRisk: The sync workflow can discard local work and push the reset state to a fork. <br>\nMitigation: Use it only on disposable or backed-up fork clones, check git status first, and avoid running it where uncommitted, untracked, ignored, or unpublished work may exist. <br>\n\n\n## Reference(s): <br>\n- [ClawHub Skill Page](https://clawhub.ai/linux2010/skills/github-contribution) <br>\n- [GitHub Contribution Workflow](github-contribution-workflow.md) <br>\n- [Live-Proof Cases](live-proof-cases.md) <br>\n\n\n## Skill Output: <br>\n**Output Type(s):** [guidance, markdown, shell commands, code] <br>\n**Output Format:** [Markdown guidance with inline shell commands and a bash helper script] <br>\n**Output Parameters:** [1D] <br>\n**Other Properties Related to Output:** [Includes issue discovery commands, fork synchronization steps, change-plan templates, PR proof guidance, and contribution workflow checklists.] <br>\n\n## Skill Version(s): <br>\n1.7.3 (source: server release evidence) <br>\n\n## Ethical Considerations: <br>\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment. <br>\n\nFile v1.7.3:skill.json\n\n{\n  \"name\": \"github-contribution\",\n  \"version\": \"1.7.2\",\n  \"description\": \"Automated GitHub contribution workflow with fork protection, clean state enforcement, change plan module, and high merge success rate best practices\",\n  \"author\": \"Linux2010\",\n  \"license\": \"MIT\",\n  \"keywords\": [\n    \"github\",\n    \"contribution\",\n    \"fork\",\n    \"pr\",\n    \"protection\",\n    \"merge-success\",\n    \"quality\",\n    \"change-plan\",\n    \"bugfix\"\n  ],\n  \"repository\": {\n    \"type\": \"git\",\n    \"url\": \"https://github.com/Linux2010/openclaw-skills\"\n  }\n}\n\nArchive v1.7.2: 7 files, 22284 bytes\n\nFiles: _meta.json (138b), github-contribution-workflow.md (4039b), live-proof-cases.md (12856b), scripts/github-contribution.sh (3565b), skill-card.md (2532b), skill.json (535b), SKILL.md (25843b)\n\nFile v1.7.2:SKILL.md\n\n# GitHub Contribution Skill\n\n## Purpose\nAutomated GitHub contribution workflow with intelligent issue discovery via positive label detection. Handles fork synchronization, branch creation, PR submission while maintaining clean fork state, and provides live-proof guidance for passing automated code review.\n\n## Core Features\n\n### 1. Intelligent Issue Discovery (v1.7.0)\n- **Positive Label Detection**: Automatically identify high-value issues via maintainer-approved labels\n- **Priority Scoring**: Rank issues by contribution value and fix feasibility\n- **Smart Filtering**: Focus on queueable, reproducible, and high-impact issues\n- **Multi-Repo Support**: Discover issues across multiple target repositories\n\n### 2. Fork Protection & Synchronization\n- **Main Branch Protection**: Never commit directly to main branch\n- **Automatic Sync**: Regularly sync fork main with upstream official repository  \n- **Clean State Enforcement**: Ensure fork main branch matches official repository exactly\n- **Pollution Prevention**: Prevent local work files from contaminating main branch\n\n### 3. Automated Contribution Workflow\n- **Fork Setup**: Automatically configure upstream remote if not exists\n- **Branch Creation**: Create feature branches based on latest official code\n- **PR Submission**: Handle pull request creation with proper templates\n- **Issue Integration**: Link fixes to relevant GitHub issues\n\n### 4. Safety Measures\n- **Pre-flight Validation**: Verify fork cleanliness before starting\n- **Atomic Operations**: All changes happen in isolated feature branches\n- **Rollback Support**: Easy recovery if something goes wrong\n- **Permission Handling**: Work within GitHub token permission constraints\n\n## 🎯 Intelligent Issue Discovery (v1.7.0)\n\n### Positive Label Detection System\n\nModern repositories use automated labeling systems to identify **high-value, maintainer-approved issues**. These **positive labels** signal issues that are:\n\n- ✅ Ready for contribution (`queueable-fix`)\n- ✅ Reproducible and confirmed (`source-repro`)\n- ✅ Impact clearly assessed (`impact:*`)\n- ✅ Value-rated by maintainers (`issue-rating:`)\n\n**Golden Rule**: Prioritize issues with positive labels over random bugs.\n\n### Label Categories & Priority\n\n| Category | Label Pattern | Meaning | Priority |\n|----------|-------------|---------|----------|\n| Queueable | `*:queueable-fix`, `*:queue_fix_pr` | Marked as ready for PR work | ⭐⭐⭐⭐⭐ |\n| Reproducible | `*:source-repro`, `confirmed`, `reproducible` | Issue reproduction validated | ⭐⭐⭐⭐⭐ |\n| Impact Assessed | `impact:*`, `severity:*`, `priority:*` | Clear impact scope | ⭐⭐⭐⭐ |\n| Value Rated | `issue-rating: *`, `value:*`, `diamond`, `gold` | Official value rating | ⭐⭐⭐⭐⭐ |\n| Implementation Clear | `*:fix-shape-*`, `fix-shape-clear` | Clear implementation path | ⭐⭐⭐⭐ |\n| Contributor Welcome | `good first issue`, `help wanted`, `contributions welcome` | Explicitly inviting contributions | ⭐⭐⭐⭐ |\n| Scope Defined | `scope:*`, `area:*`, `module:*` | Clear modification scope | ⭐⭐⭐ |\n\n### OpenClaw-Specific Positive Labels\n\nOpenClaw uses **ClawSweeper** automation to identify high-value issues:\n\n```bash\n# ClawSweeper labels (HIGH PRIORITY - maintainer-validated)\ngh issue list --repo openclaw/openclaw --label \"clawsweeper:fix-shape-clear\" --state open\ngh issue list --repo openclaw/openclaw --label \"clawsweeper:queueable-fix\" --state open\ngh issue list --repo openclaw/openclaw --label \"clawsweeper:source-repro\" --state open\n\n# Impact assessment labels\ngh issue list --repo openclaw/openclaw --label \"impact:auth-provider\" --state open\n\n# Value rating labels (🦞 diamond lobster = HIGHEST VALUE)\ngh issue list --repo openclaw/openclaw --label \"issue-rating: 🦞 diamond lobster\" --state open\ngh issue list --repo openclaw/openclaw --label \"issue-rating: *\" --state open\n```\n\n**ClawSweeper Label Meanings**:\n- `clawsweeper:fix-shape-clear` → Clear implementation path identified\n- `clawsweeper:queueable-fix` → Marked as queue-able for PR work\n- `clawsweeper:source-repro` → High-confidence source-level reproduction found\n- `impact:auth-provider` → Auth/provider/model routing may break (critical)\n- `issue-rating: 🦞 diamond lobster` → Highest value issue (fix immediately)\n\n### Issue Discovery Workflow\n\n**Step 1: Explore Repository Labels**\n\n```bash\n# Discover all labels in the repository\ngh api repos/owner/repo/labels --paginate | jq '.[].name'\n\n# Filter for positive label patterns\ngh 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)'\n```\n\n**Step 2: Query Issues with Positive Labels**\n\n```bash\n# Single positive label\ngh issue list --repo owner/repo   --label \"clawsweeper:queueable-fix\"   --state open   --json number,title,labels,createdAt\n\n# Multiple positive labels (OR logic)\ngh issue list --repo owner/repo   --label \"queueable-fix,fix-shape-clear,source-repro\"   --state open   --json number,title,labels,createdAt\n\n# Value-rated issues only\ngh issue list --repo owner/repo   --label \"issue-rating: *\"   --state open   --json number,title,labels,createdAt\n```\n\n**Step 3: Prioritize by Label Combination**\n\n**Priority Tiers**:\n\n| Tier | Label Combination | Action |\n|------|------------------|--------|\n| 🦞 **Diamond** | queueable-fix + source-repro + impact:* | Fix immediately |\n| 💎 **Gold** | fix-shape-clear + impact:* | High priority |\n| 🔥 **Platinum** | source-repro + severity:critical | Urgent fix |\n| � **Silver** | good first issue + help wanted | Good start |\n| ✅ **Standard** | Single positive label | Normal queue |\n| ⚪ **Low** | No positive labels | Skip unless urgent |\n\n**Step 4: Analyze & Select**\n\n```bash\n# Get full issue details\ngh issue view <issue-number> --repo owner/repo\n\n# Check issue comments for context\ngh issue view <issue-number> --repo owner/repo --comments\n\n# Check if already being worked on\ngh pr list --repo owner/repo --search \"fixes #<issue-number>\"\n\n# Verify no existing PRs\ngh pr list --repo owner/repo --state open --search \"<issue-keyword>\"\n```\n\n### Multi-Repo Issue Discovery\n\n```bash\n# Search across multiple repositories\ngh search issues   --label \"queueable-fix,fix-shape-clear,source-repro\"   --state open   --limit 50   --json repository,title,number,url\n\n# Target specific organizations\ngh search issues   --owner openclaw   --label \"impact:*\"   --state open   --sort created   --order desc\n```\n\n### Issue Selection Decision Matrix\n\n**Proceed if issue has**:\n- ✅ At least 1 positive label (queueable/reproducible/impact)\n- ✅ Clear description and reproduction steps\n- ✅ No existing PR addressing it\n- ✅ Scope matches your expertise\n- ✅ Effort fits available time\n\n**Skip if issue has**:\n- ❌ No positive labels (unless urgent bug)\n- ❌ Unclear description or missing details\n- ❌ Existing PR in progress\n- ❌ Requires deep domain expertise you lack\n- ❌ Breaking changes or major refactoring\n\n### Quick Issue Discovery Commands\n\n```bash\n# One-liner: Find all queueable-fix issues\ngh issue list --repo openclaw/openclaw --label \"clawsweeper:queueable-fix\" --state open --limit 10\n\n# Find highest value issues (diamond rated)\ngh issue list --repo openclaw/openclaw --label \"issue-rating: 🦞 diamond lobster\" --state open\n\n# Find reproducible issues with clear implementation path\ngh issue list --repo openclaw/openclaw   --label \"clawsweeper:source-repro,clawsweeper:fix-shape-clear\"   --state open\n\n# Find impact:auth issues (critical system)\ngh issue list --repo openclaw/openclaw --label \"impact:auth-provider\" --state open\n\n# Batch discover: All positive labels\nfor label in \"clawsweeper:queueable-fix\" \"clawsweeper:fix-shape-clear\" \"clawsweeper:source-repro\"; do\n  echo \"=== $label ===\"\n  gh issue list --repo openclaw/openclaw --label \"$label\" --state open --json number,title --limit 5\ndone\n```\n\n### Integration with Contribution Workflow\n\nAfter discovering a high-value issue:\n\n1. **Validate** - Confirm issue is still open and unassigned\n2. **Comment** - Express interest, ask clarifying questions\n3. **Wait** - Get assigned before starting (respect maintainer process)\n4. **Follow Standard Workflow** - Fork → Sync → Branch → Fix → PR\n\n**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.\n\n\n## Usage\n\n### Basic Command\n```bash\n./github-contribution.sh <username> <owner/repo> <issue-number> <branch-name> [projects-root]\n```\n\n### Examples\n```bash\n# Fix issue #123 in openclaw/openclaw\n./github-contribution.sh Linux2010 openclaw/openclaw 123 fix/issue-description\n\n# Specify custom project root\n./github-contribution.sh Linux2010 openclaw/openclaw 456 fix/bug-fix /custom/path\n```\n\n## Fork Protection Best Practices\n\n### Main Branch Rules\n1. **Never commit directly** to fork's main branch\n2. **Always sync first** before creating new branches\n3. **Use feature branches** for all development work\n4. **Regular cleanup** of local pollution files\n\n### Safe Synchronization Script\n```bash\n#!/bin/bash\n# sync-fork.sh - Safe fork synchronization\n\ngit checkout main\ngit fetch upstream\ngit reset --hard upstream/main\ngit clean -fdx  # Remove all untracked files\n\n# Verify clean state\nif [[ $(git status --porcelain) ]]; then\n    echo \"❌ Warning: Working tree not clean\"\n    exit 1\nfi\necho \"✅ Fork synchronized successfully\"\n```\n\n### Local Git Configuration\n```bash\n# Prevent accidental main branch pushes\ngit config branch.main.pushRemote no_push\n\n# Set safe push default\ngit config push.default nothing\n```\n\n## Workflow Steps\n\n### Step 1: Fork Validation\n- Check if fork exists and is accessible\n- Verify upstream remote configuration\n- Validate current fork state cleanliness\n\n### Step 2: Synchronization  \n- Fetch latest from upstream official repository\n- Reset local main branch to match upstream exactly\n- Clean any untracked/local pollution files\n- Push synchronized state to fork (if permissions allow)\n\n### Step 3: Feature Branch Creation\n- Create new branch from clean main\n- Apply necessary changes and fixes\n- Commit with proper semantic format\n- Push feature branch to fork\n\n### Step 4: PR Creation\n- Generate PR with complete template\n- Link to relevant issue numbers\n- Include proper change type and scope\n- Add security impact assessment\n\n---\n\n## 🩺 Bug Fix Module: Change Plan\n\nBefore fixing any bug, **always write a change plan first**. This ensures minimal, safe changes and makes PR review easier.\n\n### The 5-Point Analysis\n\nAnswer these 5 questions in plain language before writing any code:\n\n| # | Question | Purpose |\n|---|----------|---------|\n| 1 | **Observed behavior** | What's broken? (What the user sees) |\n| 2 | **Expected behavior** | What should happen? (Correct behavior) |\n| 3 | **Suspected root cause** | Where's the bug? (Specific code location) |\n| 4 | **Safest seam to modify** | Minimal change location? (Narrowest fix) |\n| 5 | **Risk surface** | What else could break? (Impact scope) |\n\n### Change Plan Template\n\n```markdown\n## Change Plan for Issue #<number>\n\n1. **Observed behavior**:\n   <Describe what's broken - the user-visible symptom>\n\n2. **Expected behavior**:\n   <Describe what should happen instead>\n\n3. **Suspected root cause**:\n   <Point to specific file/line/function that causes the bug>\n\n4. **Safest seam to modify**:\n   <Identify the minimal code change location - smallest safe fix>\n\n5. **Risk surface**:\n   <List what could be affected by this change>\n```\n\n### Example: Issue #5968\n\n```markdown\n## Change Plan for Issue #5968\n\n1. **Observed behavior**:\n   `extract_content_or_reasoning()` crashes when `response.choices` is None, missing, or empty list.\n\n2. **Expected behavior**:\n   Function should return empty string gracefully when no usable choices exist.\n\n3. **Suspected root cause**:\n   Line `msg = response.choices[0].message` in `agent/auxiliary_client.py` assumes choices is always non-empty.\n\n4. **Safest seam to modify**:\n   Add a guard at the top of `extract_content_or_reasoning()` before accessing choices:\n   `if not getattr(response, \"choices\", None): return \"\"`\n\n5. **Risk surface**:\n   Minimal - only affects edge cases where API response is malformed.\n```\n\n### When to Use Change Plan\n\n| Scenario | Required? |\n|----------|-----------|\n| Bug fix | ✅ Always |\n| Paper-cut UX improvement | ✅ Always |\n| Feature addition | ❌ Use feature spec instead |\n| Refactoring | ❌ Use refactor plan instead |\n| Documentation fix | ❌ Not needed |\n\n### Benefits of Change Plan\n\n| Benefit | Why It Matters |\n|---------|----------------|\n| **Forces understanding** | Can't fix what you don't understand |\n| **Defines boundaries** | Prevents scope creep and \"opportunistic\" changes |\n| **Reduces risk** | Identifies potential side effects upfront |\n| **Speeds review** | Maintainer can understand intent in 20 seconds |\n| **Enables rollback** | Clear what was changed and why |\n\n### Change Plan Checklist\n\nBefore coding:\n- [ ] Can you describe the bug in one sentence?\n- [ ] Can you point to the exact line causing it?\n- [ ] Is your fix the smallest possible change?\n- [ ] Have you identified what else could break?\n- [ ] Will this change need a regression test?\n\nIf you answered \"no\" to any question, **do more investigation before coding**.\n\n---\n\n## 🧪 Live-Proof：如何让 PR 获得官方认可\n\n> **详细案例库见 [`live-proof-cases.md`](./live-proof-cases.md)** — 记录了真实 PR 中通过 ClawSweeper 评审的 live-proof 实践，开发 PR 时必读。\n\n### 什么是 live-proof？\n\nOpenClaw 的自动评审机器人 ClawSweeper 要求 PR 提供证明修复**实际生效**的证据。仅有\"单元测试通过\"不算充分 proof。\n\n**目标评级**：`status: 👀 ready for maintainer look` + `proof: sufficient` + Overall ≥ 🐚 platinum hermit\n\n### 评级体系（短板效应）\n\n`Overall = Proof 和 Patch quality 中较弱者`\n\n即使 patch 质量很高，如果 proof 不足，整体评级仍会被拉低。\n\n| 评级 | 含义 |\n|------|------|\n| 🦀 challenger crab | 卓越就绪 |\n| 🦞 diamond lobster | 很强，少量审查 |\n| 🐚 platinum hermit | 良好普通 PR |\n| 🦪 silver shellfish | 信号薄弱，需改进 |\n| 🧂 unranked krab | 不可合并 |\n\n### Live-Proof 形式\n\n被合并的 PR 全部使用**终端命令输出**（不用截图/视频）：\n\n| 类型 | 命令 | 适用 |\n|------|------|------|\n| 直接验证 | `node --import tsx -e \"...\"` | 配置验证、纯函数 |\n| 聚焦测试 | `node scripts/run-vitest.mjs <path>` | 运行时修复 |\n| 格式检查 | `git diff --check` | 代码格式 |\n\n### 最有效模式：BEFORE vs AFTER 对比\n\n```\nBEFORE (current main) - <invalid input> passed validation with ok: true\nAFTER - <invalid input> is rejected with clear error message\n```\n\n### 提交前必查\n\n- [ ] 提供了 BEFORE vs AFTER 对比（不只是 AFTER）\n- [ ] Proof 是终端命令输出，不是只有\"测试通过\"\n- [ ] 覆盖了边界值（最小、最大、无效）\n- [ ] 覆盖了幂等性（如涉及迁移）\n- [ ] **修改前能复现 bug**（测试在修复前会失败）\n- [ ] 修改的代码路径在正常情况下会被走到\n\n### 关键教训\n\n1. **收紧 config 验证 = 破坏性变更**：必须配 `openclaw doctor --fix` 迁移，否则已有配置升级后报错\n2. **Doctor 迁移用替换而非删除**：`gateway.port = DEFAULT` 比 `delete gateway.port` 更安全（配置行为明确）\n3. **修改前先证明 bug 在该路径**：写一个修复前会失败的测试；如果修复前就通过，bug 不在这\n4. **诚实面对找不到根因**：硬提交无效修复会被打 🧂 unranked krab；关闭 PR + 评论 issue 更好\n\n### 详细案例\n\n- ✅ **成功案例 #110051**：配置验证 + Doctor 迁移，`🦞 diamond lobster`\n- ✅ **成功案例 #109875**：竞品学习对象，`👀 ready for maintainer look`\n- ❌ **失败案例 #109885**：修改了不可达路径，`🧂 unranked krab` -> 关闭\n\n---\n\n## Error Handling\n\n### Common Issues & Solutions\n\n#### Fork Not Clean\n- **Problem**: Local main branch has extra commits/files\n- **Solution**: Force reset to upstream and clean untracked files\n\n#### Permission Denied (Workflow Scope)\n- **Problem**: Token lacks workflow permissions\n- **Solution**: Use web-based PR creation or update token permissions\n\n#### Upstream Not Configured  \n- **Problem**: Missing upstream remote\n- **Solution**: Auto-add upstream remote pointing to official repository\n\n#### Branch Already Exists\n- **Problem**: Feature branch already exists\n- **Solution**: Use unique branch naming or delete existing branch\n\n## Security Considerations\n\n### Token Permissions\n- **Minimum Required**: `repo` scope\n- **Optional**: `workflow` scope (for full automation)\n- **Never Grant**: Excessive permissions beyond contribution needs\n\n### Local Security\n- **File Cleanup**: Always clean working directory after contributions\n- **Credential Management**: Use secure credential storage\n- **Audit Trail**: Maintain logs of all contribution activities\n\n## Integration with Other Skills\n\n### PR Advocacy Skill\n- Hand off created PRs to PR Advocacy for monitoring\n- Share PR tracking information for continuous follow-up\n- Coordinate review response and maintenance\n\n### Document Spell Check Skill  \n- Pre-validate documentation changes before PR creation\n- Ensure all text content passes spell checking\n- Maintain documentation quality standards\n\n## High-Quality PR Best Practices (Maximize Merge Success Rate)\n\n### 🎯 Merge Success Rate Formula (Based on 30+ Merged PRs Analysis)\n\n```\nMerge Success Rate = \n  (PR Description Completeness × 0.2) +\n  (Review Response Speed × 0.25) +\n  (Test Coverage × 0.2) +\n  (Conflict Resolution Status × 0.15) +\n  (Review Resolution Rate × 0.2)\n```\n\n**Target**: > 80% success rate\n\n### ✅ 10 Success Characteristics (Must Follow 100%)\n\n1. ✅ **Complete PR Description** - Use template, fill ALL required fields\n2. ✅ **Fast Review Response** - < 30 minutes average response time\n3. ✅ **Small Focused Commits** - 1 commit solves 1 problem\n4. ✅ **100% Test Coverage** - Include edge cases and regression tests\n5. ✅ **Zero Conflicts** - Daily rebase upstream, keep CLEAN\n6. ✅ **Changelog Updated** - All user-visible changes\n7. ✅ **Security Checklist** - 5 required security questions\n8. ✅ **Human Verification Statement** - Manual test content + untested areas\n9. ✅ **Review Conversations Resolved** - 100% resolve bot review comments\n10. ✅ **Rollback Plan** - Rollback steps + known issues\n\n### 📋 Pre-Submission Checklist\n\nBefore pushing PR:\n\n**Code Quality:**\n- [ ] Title format: `type(scope): description`\n- [ ] Commit message: includes \"what\" + \"why\"\n- [ ] At least 1 new test case\n- [ ] CHANGELOG.md updated\n- [ ] 4-7 meaningful commits\n\n**CI Pre-flight (MUST pass locally):**\n- [ ] `pnpm protocol:check` - Protocol validation\n- [ ] `pnpm test` - All tests pass\n- [ ] `pnpm lint` - No lint errors\n- [ ] `pnpm tsc --noEmit` - TypeScript compilation\n\n**Review Readiness:**\n- [ ] Ready to respond within 24h\n- [ ] Greptile/Aisle Security comments addressed\n- [ ] Security questions answered (5 required)\n\n### 📊 High Success Rate PR Patterns\n\n#### Pattern 1: Security Fix Response (vincentkoc #44437)\n```\n7 commits in same day:\n1. Main fix implementation\n2. Changelog update\n3. Merge main (resolve conflicts)\n4. Tests: add coverage for review comments\n5. Fix: address Greptile suggestions\n6. Extra hardening (defensive programming)\n7. Merge main (final sync)\n```\n\n**Key Learnings:**\n- ✅ Separate commits for review responses\n- ✅ Tests and docs as separate commits\n- ✅ Frequent merge main to resolve conflicts\n- ✅ Extra hardening shows professionalism\n\n#### Pattern 2: Security Report Response (gumadeiras #44176)\n```markdown\nWhen Aisle Security reports issues:\n\n1. Quote SECURITY.md to explain why it's out of scope\n2. But still fix it (defensive programming)\n3. List specific hardening done\n4. Provide verification commands\n```\n\n**Key Learnings:**\n- ✅ Respond to security reports first\n- ✅ Explain scope判断 basis\n- ✅ Still fix it (show cooperation)\n- ✅ Provide verification method\n\n### ⚠️ Common Mistakes That Reduce Merge Rate\n\n| Mistake | Impact | Solution |\n|---------|--------|----------|\n| ❌ Missing Changelog | -20% | Always update CHANGELOG.md |\n| ❌ Slow review response (>24h) | -25% | Respond within 24h, ideally <30min |\n| ❌ Incomplete test coverage | -20% | Add tests for edge cases |\n| ❌ Merge conflicts | -15% | Daily rebase upstream |\n| ❌ Unresolved bot reviews | -20% | 100% resolve all comments |\n| ❌ CI failures | Automatic reject | Pre-flight check locally |\n\n### 🎯 Quality Metrics\n\n| Metric | Target | Current Best Practice |\n|--------|--------|----------------------|\n| **Greptile Score** | ≥ 4/5 | Address all P1/P2 issues |\n| **Aisle Security** | 0 unresolved | Respond or fix all |\n| **Test Coverage** | ≥ 1 new test | Include edge cases |\n| **CI Pass Rate** | 100% | Pre-check locally |\n| **Behind upstream** | 0 commits | Daily rebase |\n| **Response Time** | < 24h | Same day preferred |\n\n### 📝 PR Template Best Practices\n\n**Title Format:**\n```\n✅ fix(hooks): fail closed on unreadable loader paths\n✅ feat(context-engine): plumb sessionKey into all methods\n✅ docs: codify American English spelling convention\n✅ security: include accountId in session keys\n```\n\n**Commit Message Structure:**\n```\nFirst line: What was done (concise description)\n\nSecond paragraph: Why (problem background, impact)\n\nOptional: Regeneration-Prompt / AI assistance notes\n```\n\n**Example (#44411):**\n```\nfix(ci): restore generated protocol swift outputs\n\nRegenerate the Swift protocol models so PushTestResult keeps the \ntransport field required by the current gateway schema, and update \nprotocol:check to diff both generated Swift destinations because \nthe generator writes both files.\n\nRegeneration-Prompt: |\n  Investigate the protocol CI failure on current origin/main...\n```\n\n---\n\n## Best Practices\n\n### For Contributors\n- Always start from clean, synchronized main branch\n- Use descriptive branch names following convention\n- Fill complete PR templates with all required fields\n- Test changes locally before pushing\n- **Always rebase on the original PR branch** (never create new branches for rebase)\n- **Follow High-Quality PR Best Practices** (see section above)\n\n### PR Rebase Best Practices (Critical!)\n\n**Golden Rule**: Always rebase on the **original PR branch**, never create a new branch.\n\n#### Correct Rebase Workflow\n\n```bash\n# 1. Confirm current branch\ngit branch --show-current\n\n# 2. Confirm PR's branch name\ngh pr view <PR-number> --json headRefName --jq .headRefName\n\n# 3. Switch to correct branch if needed\ngit checkout <PR-branch-name>\n\n# 4. Rebase on the SAME branch (do NOT create new branch)\ngit fetch upstream\ngit rebase upstream/main\n\n# 5. Push to the SAME branch\ngit push -f origin <same-branch-name>\n```\n\n#### Common Mistakes to Avoid\n\n| ❌ Wrong | ✅ Correct |\n|---------|---------|\n| `git checkout -b new-branch` then rebase | Stay on original branch, rebase there |\n| Switch to different branch for rebase | Rebase on PR's own branch |\n| Skip branch confirmation | Always run `git branch --show-current` first |\n| Don't verify PR branch name | Use `gh pr view` to confirm |\n\n#### Why This Matters?\n\n1. **Clean branch history** - No duplicate branches created\n2. **Avoid confusion** - PR always linked to same branch\n3. **Reduce errors** - Won't push to wrong branch\n4. **Easy management** - All changes in one place\n\n#### Pre-Rebase Checklist\n\nBefore rebasing:\n- [ ] Run `git branch --show-current` to confirm current branch\n- [ ] Run `gh pr view <num> --json headRefName` to confirm PR branch\n- [ ] Ensure both names match before proceeding\n- [ ] If mismatch, `git checkout <PR-branch>` first\n\n#### Post-Rebase Checklist\n\nAfter rebasing:\n- [ ] Run `git log --oneline -3` to verify commits\n- [ ] Run `pnpm test` or relevant tests\n- [ ] Run `git push -f origin <branch>` to update PR\n\n#### Example: Rebase PR #48568\n\n```bash\n# Check current branch\n$ git branch --show-current\nfix/47752-final  # ✅ Correct!\n\n# Confirm PR branch\n$ gh pr view 48568 --json headRefName --jq .headRefName\nfix/47752-final  # ✅ Matches!\n\n# Rebase on same branch\ngit fetch upstream\ngit rebase upstream/main\n\n# Test\npnpm test src/infra/heartbeat-runner.timeout.test.ts\n\n# Push to same branch\ngit push -f origin fix/47752-final\n```\n\n#### Troubleshooting\n\n**Problem**: Accidentally created new branch during rebase\n\n**Solution**:\n```bash\n# Go back to original branch\ngit checkout <original-branch>\n\n# Rebase there instead\ngit rebase upstream/main\n\n# Delete the accidental branch\ngit branch -D <accidental-branch>\n\n# Push to original branch\ngit push -f origin <original-branch>\n```\n\n---\n\n### For Maintainers  \n- Regularly audit fork cleanliness\n- Update synchronization scripts as needed\n- Monitor token permissions and security\n- Document contribution workflows for team members\n\n## Limitations\n\n### GitHub Fork Restrictions\n- Cannot set full branch protection rules on forks\n- Limited automation capabilities without workflow permissions\n- Manual intervention sometimes required for complex scenarios\n\n### Workarounds\n- Use local git hooks for additional protection\n- Implement manual verification steps in workflow\n- Leverage GitHub web interface for final PR creation when needed\n\n## Maintenance\n\n### Updates\n- Regular script updates for new GitHub API changes\n- Security patches for authentication methods\n- Performance improvements for large repositories\n\n### Monitoring\n- Track success/failure rates of contribution attempts\n- Monitor GitHub API rate limit usage\n- Collect user feedback for workflow improvements\n\nFile v1.7.2:_meta.json\n\n{\n  \"ownerId\": \"kn7djfrkxdrrb6syjdv4vvtmp18252ry\",\n  \"slug\": \"github-contribution\",\n  \"version\": \"1.7.2\",\n  \"publishedAt\": 1784821397013\n}\n\nFile v1.7.2:github-contribution-workflow.md\n\n# GitHub 开源项目贡献完整工作流程\n\n## 1. Fork 和同步项目\n\n### Fork 官方仓库\n- 访问目标项目的 GitHub 页面（例如 `https://github.com/owner/repo`）\n- 点击右上角的 \"Fork\" 按钮\n- 选择你的 GitHub 账户作为 fork 目标\n\n### 克隆你的 Fork\n```bash\ngit clone https://github.com/your-username/repo.git\ncd repo\n```\n\n### 添加上游远程仓库\n```bash\ngit remote add upstream https://github formulate the official repository URL\ngit remote -v  # 验证远程仓库配置\n```\n\n### 同步 Fork 到最新状态\n```bash\n# 切换到 main/master 分支\ngit checkout main\n\n# 获取上游仓库的最新更改\ngit fetch upstream\n\n# 将上游的更改合并到本地\ngit merge upstream/main\n\n# 推送到你的 fork\ngit push origin main\n```\n\n## 2. 创建功能分支\n\n### 基于最新的 main 分支创建新分支\n```bash\n# 确保在 main 分支且已同步\ngit checkout main\ngit pull upstream main\n\n# 创建新的功能分支（使用描述性名称）\ngit checkout -b fix/issue-description\n# 或者\ngit checkout -b feature/new-functionality\n```\n\n### 分支命名约定\n- `fix/` - 用于 bug 修复\n- `feature/` - 用于新功能\n- `docs/` - 用于文档更新\n- `chore/` - 用于维护任务\n\n## 3. 开发和测试\n\n### 进行代码更改\n- 在功能分支上进行所有开发工作\n- 遵循项目的代码风格和规范\n- 编写必要的测试用例\n- 更新相关文档（如果需要）\n\n### 提交更改\n```bash\n# 查看更改状态\ngit status\n\n# 添加更改的文件\ngit add .\n\n# 提交更改（使用清晰的提交信息）\ngit commit -m \"fix: resolve issue with XYZ component\"\n\n# 推送到你的 fork\ngit push origin fix/issue-description\n```\n\n### 提交信息格式\n遵循 conventional commits 格式：\n- `fix:` - bug 修复\n- `feat:` - 新功能\n- `docs:` - 文档更新\n- `style:` - 代码格式更改\n- `refactor:` - 代码重构\n- `test:` - 测试相关\n- `chore:` - 构建过程或辅助工具的变动\n\n## 4. 创建 Pull Request\n\n### 通过 GitHub 网页界面创建 PR\n1. 访问你的 fork 仓库页面\n2. GitHub 通常会自动检测到新推送的分支并显示 \"Compare & pull request\" 按钮\n3. 点击该按钮进入 PR 创建页面\n\n### PR 标题和描述\n- **标题**: 清晰描述更改的目的（例如：\"Fix null pointer exception in auth handler\"）\n- **描述**: \n  - 说明问题的背景\n  - 描述解决方案\n  - 提及相关的 issue（使用 `Closes #123` 或 `Fixes #123`）\n  - 列出主要的更改点\n\n### PR 检查清单\n- [ ] 代码通过所有测试\n- [ ] 遵循项目代码风格\n- [ ] 包含必要的测试用例\n- [ ] 更新了相关文档\n- [ ] PR 描述清晰完整\n- [ ] 关联了相关 issue\n\n## 5. PR 审查和合并\n\n### 处理审查反馈\n- 及时响应审查者的评论\n- 根据反馈进行必要的修改\n- 使用新的提交来处理反馈（不要强制推送覆盖历史）\n\n### 更新 PR\n```bash\n# 在功能分支上进行修改\ngit add .\ngit commit -m \"address review feedback: improve error handling\"\ngit push origin fix/issue-description\n```\n\n### PR 合并后清理\n```bash\n# 切换回 main 分支\ngit checkout main\n\n# 删除本地功能分支\ngit branch -d fix/issue-description\n\n# 删除远程功能分支（可选）\ngit push origin --delete fix/issue-description\n```\n\n## 常见问题和最佳实践\n\n### 保持分支同步\n如果 PR 审查时间较长，可能需要将最新的上游更改合并到你的功能分支：\n```bash\ngit checkout main\ngit pull upstream main\ngit checkout fix/issue-description\ngit rebase main\ngit push --force-with-lease origin fix/issue-description\n```\n\n### 避免强制推送\n除非必要（如 rebase 后），避免使用 `--force` 推送，使用 `--force-with-lease` 更安全。\n\n### 小而专注的 PR\n- 每个 PR 应该解决一个具体的问题\n- 避免在一个 PR 中包含多个不相关的更改\n- 这样更容易审查和合并\n\n### 社区礼仪\n- 保持礼貌和专业的沟通\n- 及时响应审查反馈\n- 感谢维护者的审查时间\n- 遵循项目的贡献指南（CONTRIBUTING.md）\n\nFile v1.7.2:live-proof-cases.md\n\n# Live-Proof 案例库\n\n> 本文件记录真实 PR 中通过 ClawSweeper 评审、获得 `status: 👀 ready for maintainer look` 的 live-proof 实践。\n> 开发 PR 时参考本案例库，确保提供的 proof 足够充分。\n\n## 目录\n\n- [ClawSweeper 评级体系](#clawsweeper-评级体系)\n- [什么是 live-proof](#什么是-live-proof)\n- [案例一：配置验证类修复（#110051）](#案例一配置验证类修复110051)\n- [案例二：竞品对比学习（#109875）](#案例二竞品对比学习109875)\n- [失败案例：修改了不可达路径（#109885）](#失败案例修改了不可达路径109885)\n- [通用 Proof 模板](#通用-proof-模板)\n- [检查清单](#检查清单)\n\n---\n\n## ClawSweeper 评级体系\n\nClawSweeper（OpenClaw 的自动评审机器人）对 PR 给出三个维度的甲壳类评级：\n\n| 评级 | 含义 | 可合并性 |\n|------|------|----------|\n| 🦀 challenger crab | 罕见，卓越的就绪状态 | 极高 |\n| 🦞 diamond lobster | 很强，仅需少量 maintainer 审查 | 高 |\n| 🐚 platinum hermit | 良好的普通 PR，普通审查即可 | 中高 |\n| 🦐 gold shrimp | 有用信号，但 proof/confidence 仍有限 | 中 |\n| 🦪 silver shellfish | 信号薄弱，proof/validation/实现需改进 | 低 |\n| 🧂 unranked krab | 不可合并（proof 缺失或有严重问题） | 不可合并 |\n| 🌊 off-meta tidepool | 评级不适用 | N/A |\n\n### 三个评分维度\n\n| 维度 | 说明 |\n|------|------|\n| **Overall** | 综合 = proof 和 patch quality 中较弱者（短板效应） |\n| **Proof** | 真实行为证明的充分性 |\n| **Patch quality** | 代码实现质量 |\n\n> ⚠️ **关键规则**：`Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.`\n> 即使 patch 质量是 🐚 platinum hermit，如果 proof 只有 🦪 silver shellfish，整体仍是 🦪。\n\n### 状态标签\n\n| 标签 | 含义 |\n|------|------|\n| `status: 📣 needs proof` | 需要补充真实行为证明才能合并 |\n| `status: 👀 ready for maintainer look` | ClawSweeper 无 contributor 阻塞项，等待 maintainer 审查 |\n| `proof: sufficient` | Contributor 真实行为证明充分 |\n\n**目标**：获得 `status: 👀 ready for maintainer look` + `proof: sufficient`。\n\n---\n\n## 什么是 live-proof\n\nLive-proof（真实行为证明）是 ClawSweeper 要求的、证明修复**实际生效**的证据。\n\n### ❌ 不是 live-proof 的东西\n\n- 只有单元测试通过（\"X tests passed\"）\n- 纯代码阅读得出的结论（\"代码逻辑应该正确\"）\n- 声称修复有效但没有运行验证\n\n### ✅ 是 live-proof 的东西\n\n被合并的 PR 全部使用**终端命令输出**作为 proof，不用截图/视频：\n\n| Proof 类型 | 命令模式 | 适用场景 |\n|-----------|---------|---------|\n| 直接验证 | `node --import tsx -e \"...\"` | 配置验证、纯函数行为 |\n| 聚焦测试 | `node scripts/run-vitest.mjs <path>` | 运行时修复、回归测试 |\n| 完整 gate | `node scripts/check-changed.mjs -- <files>` | 多文件变更 |\n| 格式检查 | `git diff --check` / `oxfmt --check` | 代码格式 |\n| Autoreview | `autoreview --mode uncommitted` | 代码审查 |\n\n### 关键：BEFORE vs AFTER 对比\n\n最有效的 proof 是展示**修复前**和**修复后**的对比：\n\n```\nBEFORE (current main) - gateway.port: 65536 passed validation with ok: true\nAFTER - gateway.port: 65536 is rejected with clear error message\n```\n\n---\n\n## 案例一：配置验证类修复（#110051）\n\n**Issue**: #109293 - `gateway.port` 接受超出 TCP 端口范围的值\n**PR**: https://github.com/openclaw/openclaw/pull/110051\n**修复类型**: 配置 schema 收紧 + Doctor 迁移\n\n### 问题描述\n\n`gateway.port` 的 Zod schema 只有 `.positive()` 没有 `.max(65535)`，导致 `65536` 等无效端口通过验证。\n\n### 关键教训：收紧 config 验证 = 破坏性变更\n\n**这是最重要的教训。** 收紧 config schema 会让之前合法的配置变非法，必须配 Doctor 迁移！\n\n> CLAUDE.md 明确规定：\"If a config change invalidates existing files, add a matching `openclaw doctor --fix` migration.\"\n\n只加 schema 约束而不加 Doctor 迁移的后果：\n- 已有 `gateway.port: 65536` 的用户升级后直接报错，无升级路径\n- ClawSweeper 标记 `merge-risk: 🚨 compatibility`\n- 无法获得 `status: 👀 ready for maintainer look`\n\n### Doctor 迁移设计决策\n\n迁移应**替换为默认值**而非删除键：\n\n| 策略 | #109875（竞品） | #110051（我们的） |\n|------|-----------------|------------------|\n| 做法 | `delete gateway.port` | `gateway.port = DEFAULT_GATEWAY_PORT` |\n| 迁移后配置 | 无 port 键 | `port: 18789` |\n| 用户体验 | 困惑：配置里没 port，网关用什么端口？ | 明确：绑定到默认 18789 |\n\n### 提供的 Proof 内容\n\n**1. Schema validation - BEFORE vs AFTER**\n\n```sh\n# BEFORE (current main) - passes validation\n{\"ok\": true, \"config\": {\"gateway\": {\"port\": 65536}}}\n\n# AFTER - rejected\n$ node --import tsx -e \"\nimport { validateConfigObjectRaw } from './src/config/validation.ts';\nconsole.log(JSON.stringify(validateConfigObjectRaw({gateway:{port:65536}}), null, 2));\"\n{\n  \"ok\": false,\n  \"issues\": [{\n    \"path\": \"gateway.port\",\n    \"message\": \"Too big: expected number to be <=65535 (maximum: 65535)\"\n  }]\n}\n```\n\n**2. Doctor migration - 升级路径证明**\n\n```sh\n$ node --import tsx -e \"\nimport { applyLegacyDoctorMigrations } from './src/commands/doctor/shared/legacy-config-compat.js';\nconst raw = {gateway:{port:65536}};\nconst { next, changes } = applyLegacyDoctorMigrations(raw);\nconsole.log('changes:', JSON.stringify(changes));\nconsole.log('next:', JSON.stringify(next));\"\nchanges: [\"Replaced out-of-range gateway.port (65536) with default 18789...\"]\nnext: {\"gateway\":{\"port\":18789}}\n```\n\n覆盖场景：\n- port 65536（超上限）→ 替换为默认\n- port 0（低于下限）→ 替换为默认\n- port 65535（有效）→ 无迁移\n- port 65536 + bind:loopback → port 替换，bind 保留\n- 幂等性：第二次迁移无变化\n\n**3. 测试结果**\n\n```\n- node scripts/run-vitest.mjs src/config/zod-schema.gateway.test.ts - 7 tests\n- node scripts/run-vitest.mjs src/config/validation.policy.test.ts - 8 tests\n- node scripts/run-vitest.mjs src/commands/doctor/shared/legacy-config-migrate.test.ts - 158 tests\n- git diff --check - passed\n```\n\n### 评级结果\n\n| 维度 | 评级 |\n|------|------|\n| Patch quality | 🐚 platinum hermit |\n| Proof | 🦞 diamond lobster（加入 Doctor proof 后） |\n| Overall | 🦞 diamond lobster |\n\n---\n\n## 案例二：竞品对比学习（#109875）\n\n**Issue**: 同 #109293\n**PR**: https://github.com/openclaw/openclaw/pull/109875\n**结果**: 获得 `status: 👀 ready for maintainer look` + `proof: sufficient`\n\n### 它做对了什么\n\n1. **Doctor 迁移配对**：schema 收紧 + `openclaw doctor --fix` 迁移\n2. **BEFORE vs AFTER 对比**：明确展示修复前后验证输出\n3. **Doctor 迁移的完整场景证明**：6 个场景，每个都有终端输出\n4. **测试分散在正确的位置**：验证策略测试 + 迁移测试\n\n### ClawSweeper 的关键评语\n\n> `status: 👀 ready for maintainer look`: ClawSweeper has no concrete contributor-facing blocker left for this PR.\n> `proof: sufficient`: The PR body includes after-fix terminal output for raw validation and Doctor migration behavior, including invalid, valid-boundary, idempotence, and sibling-key cases.\n\n### 它的不足（我们改进的点）\n\n1. Doctor 迁移用 `delete` 而非 `replace`，用户体验较差\n2. `legacyRules` 的 `match` 没有覆盖非数字/非整数类型\n3. 迁移测试没覆盖负数端口\n\n---\n\n## 失败案例：修改了不可达路径（#109885）\n\n**Issue**: #109673 - `browser.headless` 配置被忽略\n**PR**: https://github.com/openclaw/openclaw/pull/109885（已关闭）\n**结果**: 🧂 unranked krab → 关闭\n\n### 失败原因\n\n**修改了一个正常代码路径不会走到的 fallback。**\n\n```typescript\n// resolveManagedBrowserHeadlessMode 的 fallback (line 730)\nreturn { headless: resolved.headless, source: \"default\" };  // 我改成了 resolved.headlessSource\n```\n\nClawSweeper 的批评：\n> The changed final fallback is bypassed by the normal resolved profile according to the PR's own tests, so the patch does not yet identify or repair the boundary producing the reported behavior.\n\n### 教训\n\n1. **修改前先证明 bug 在该路径**：写一个测试，在修复前应该失败。如果修复前测试就通过，说明 bug 不在这。\n2. **不要修改\"看起来不对\"但实际不影响行为的代码**：要验证改动是否真正改变运行时行为。\n3. **ClawSweeper 会读你的测试**：如果测试本身说明\"正常 profile 走早期分支\"，它就知道你的 fallback 修改无效。\n4. **找不到根因时不要硬提交**：诚实说明，关闭 PR，评论 issue 说明调查结果。\n\n### 正确的流程\n\n```\n1. 写测试复现 bug（修复前应失败）\n   ↓ 失败 = 找到了根因\n2. 修复代码\n   ↓ 测试通过\n3. 验证修复改变了运行时行为（live-proof）\n   ↓\n4. 提交 PR\n```\n\n---\n\n## 通用 Proof 模板\n\n### 配置验证类修复\n\n```markdown\n## Evidence\n\n### 1. Schema validation - BEFORE vs AFTER\n\n**BEFORE** (current main) - `<invalid input>` passed validation with `ok: true`\n\n**AFTER** - `<invalid input>` is rejected:\n\n\\`\\`\\`sh\n$ node --import tsx -e \"\nimport { validateConfigObjectRaw } from './src/config/validation.ts';\nconsole.log(JSON.stringify(validateConfigObjectRaw({<path>:<value>}), null, 2));\"\n<actual output showing ok:false + error message>\n\\`\\`\\`\n\n### 2. Doctor migration - upgrade path proof\n\n\\`\\`\\`sh\n$ node --import tsx -e \"\nimport { applyLegacyDoctorMigrations } from './src/commands/doctor/shared/legacy-config-compat.js';\nconst raw = {<path>:<invalid_value>};\nconst { next, changes } = applyLegacyDoctorMigrations(raw);\nconsole.log('changes:', JSON.stringify(changes));\nconsole.log('next:', JSON.stringify(next));\"\n<output showing repair>\n\\`\\`\\`\n\n覆盖场景：\n- 无效值 → 修复\n- 有效边界值 → 不变\n- 幂等性\n- sibling key 保留\n\n### 3. Test results\n- `node scripts/run-vitest.mjs <test-path>` - N tests passed\n- `git diff --check` - passed\n```\n\n### 运行时逻辑修复\n\n```markdown\n## Evidence\n\n- Focused proof: `node scripts/run-vitest.mjs <test-path>` - N tests passed.\n- BEFORE: <描述修复前的错误行为，最好有测试断言证明>\n- AFTER: <描述修复后的正确行为>\n- `git diff --check` - passed.\n```\n\n### Bug 复现型修复\n\n```markdown\n## Evidence\n\n### Regression test (fails before fix, passes after)\n\\`\\`\\`\nnode scripts/run-vitest.mjs <test-path>\n# Before fix: FAIL - <error>\n# After fix: PASS\n\\`\\`\\`\n\n### Live behavior proof\n<运行实际命令展示修复前后行为变化>\n```\n\n---\n\n## 检查清单\n\n### 提交 PR 前的 proof 检查\n\n- [ ] 提供了 BEFORE vs AFTER 对比（不只是 AFTER）\n- [ ] Proof 是终端命令输出，不是只有\"测试通过\"\n- [ ] 覆盖了边界值（最小、最大、无效）\n- [ ] 覆盖了幂等性（如涉及迁移）\n- [ ] 覆盖了 sibling key 保留（如涉及删除/修改配置项）\n- [ ] 如果收紧了 config 验证，配了 Doctor 迁移\n- [ ] 修复前能复现 bug（测试在修复前会失败）\n\n### 自问：修改是否真正改变运行时行为？\n\n- [ ] 我写的测试在**修复前**会失败吗？\n- [ ] 我修改的代码路径在**正常情况下**会被走到吗？\n- [ ] ClawSweeper 读完我的测试后，会认为我的修复有效吗？\n\n如果任何一项为\"否\"，**不要提交**，继续调查根因。\n\n### 达标目标\n\n提交 PR 后，目标评级：\n- ✅ `status: 👀 ready for maintainer look`\n- ✅ `proof: sufficient`\n- ✅ Overall ≥ 🐚 platinum hermit\n\n---\n\n## 经验总结\n\n### 1. 收紧配置验证必须配 Doctor 迁移\n\n这是 OpenClaw 的硬规则。任何让之前合法配置变非法的变更，都要提供 `openclaw doctor --fix` 升级路径。\n\n### 2. Proof 要展示真实运行时行为\n\nClawSweeper 明确说：\"Only unit-test claims are provided\" 是不够的。要运行实际命令展示修复效果。\n\n### 3. BEFORE vs AFTER 对比最有效\n\n明确展示\"修复前是坏的，修复后是好的\"比单纯展示\"修复后是好的\"更有说服力。\n\n### 4. 修改前先证明 bug 在该路径\n\n写一个在修复前会失败的测试。如果修复前测试就通过，说明 bug 不在你修改的地方。\n\n### 5. Doctor 迁移用替换而非删除\n\n替换为默认值比删除键更安全：用户看到的配置文件行为明确，不依赖隐式默认。\n\n### 6. 诚实面对找不到根因的情况\n\n如果代码逻辑看起来正确但 bug 仍存在，可能 bug 在运行时其他地方或已被间接修复。诚实说明，关闭 PR，评论 issue，比硬提交一个无效修复好。\n\nFile v1.7.2:skill-card.md\n\n## Description: <br>\nAutomated GitHub contribution workflow guidance for issue discovery, fork synchronization, branch creation, pull request preparation, and live-proof evidence. <br>\n\nThis skill is ready for commercial/non-commercial use. <br>\n\n## Publisher: <br>\n[linux2010](https://clawhub.ai/user/linux2010) <br>\n\n### License/Terms of Use: <br>\nMIT-0 <br>\n\n\n## Use Case: <br>\nDevelopers and open source contributors use this skill to choose suitable GitHub issues, keep forks synchronized, prepare focused branches, and assemble pull requests with validation evidence. <br>\n\n### Deployment Geography for Use: <br>\nGlobal <br>\n\n## Known Risks and Mitigations: <br>\nRisk: The helper workflow can run destructive Git operations such as hard resets and untracked file cleanup in a repository. <br>\nMitigation: Run it only in a disposable or fully backed-up clone, and verify the repository path, current branch, remotes, and uncommitted work before execution. <br>\nRisk: Fork synchronization and rebase guidance can overwrite branch state if used on the wrong branch or with unsafe force-push behavior. <br>\nMitigation: Confirm the target branch before rebasing or pushing, prefer the original pull request branch, and use force-with-lease rather than destructive push defaults. <br>\nRisk: GitHub token use may expose excessive repository permissions if broad scopes are granted. <br>\nMitigation: Use the minimum required GitHub permissions for the contribution task and store credentials through a secure credential manager. <br>\n\n\n## Reference(s): <br>\n- [ClawHub skill page](https://clawhub.ai/linux2010/skills/github-contribution) <br>\n- [Live-proof case study PR #110051](https://github.com/openclaw/openclaw/pull/110051) <br>\n- [Live-proof case study PR #109875](https://github.com/openclaw/openclaw/pull/109875) <br>\n\n\n## Skill Output: <br>\n**Output Type(s):** [guidance, markdown, shell commands, configuration] <br>\n**Output Format:** [Markdown guidance with inline shell commands and checklist-style workflows] <br>\n**Output Parameters:** [1D] <br>\n**Other Properties Related to Output:** [Includes an optional shell helper script for fork setup and synchronization.] <br>\n\n## Skill Version(s): <br>\n1.7.2 (source: server release metadata) <br>\n\n## Ethical Considerations: <br>\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment. <br>\n\nFile v1.7.2:skill.json\n\n{\n  \"name\": \"github-contribution\",\n  \"version\": \"1.7.0\",\n  \"description\": \"Automated GitHub contribution workflow with fork protection, clean state enforcement, change plan module, and high merge success rate best practices\",\n  \"author\": \"Linux2010\",\n  \"license\": \"MIT\",\n  \"keywords\": [\n    \"github\",\n    \"contribution\",\n    \"fork\",\n    \"pr\",\n    \"protection\",\n    \"merge-success\",\n    \"quality\",\n    \"change-plan\",\n    \"bugfix\"\n  ],\n  \"repository\": {\n    \"type\": \"git\",\n    \"url\": \"https://github.com/Linux2010/openclaw-skills\"\n  }\n}\n\nArchive v1.7.1: 7 files, 22205 bytes\n\nFiles: _meta.json (138b), github-contribution-workflow.md (4039b), live-proof-cases.md (12856b), scripts/github-contribution.sh (3565b), skill-card.md (2389b), skill.json (535b), SKILL.md (25843b)\n\nFile v1.7.1:SKILL.md\n\n# GitHub Contribution Skill\n\n## Purpose\nAutomated GitHub contribution workflow with intelligent issue discovery via positive label detection. Handles fork synchronization, branch creation, PR submission while maintaining clean fork state, and provides live-proof guidance for passing automated code review.\n\n## Core Features\n\n### 1. Intelligent Issue Discovery (v1.7.0)\n- **Positive Label Detection**: Automatically identify high-value issues via maintainer-approved labels\n- **Priority Scoring**: Rank issues by contribution value and fix feasibility\n- **Smart Filtering**: Focus on queueable, reproducible, and high-impact issues\n- **Multi-Repo Support**: Discover issues across multiple target repositories\n\n### 2. Fork Protection & Synchronization\n- **Main Branch Protection**: Never commit directly to main branch\n- **Automatic Sync**: Regularly sync fork main with upstream official repository  \n- **Clean State Enforcement**: Ensure fork main branch matches official repository exactly\n- **Pollution Prevention**: Prevent local work files from contaminating main branch\n\n### 3. Automated Contribution Workflow\n- **Fork Setup**: Automatically configure upstream remote if not exists\n- **Branch Creation**: Create feature branches based on latest official code\n- **PR Submission**: Handle pull request creation with proper templates\n- **Issue Integration**: Link fixes to relevant GitHub issues\n\n### 4. Safety Measures\n- **Pre-flight Validation**: Verify fork cleanliness before starting\n- **Atomic Operations**: All changes happen in isolated feature branches\n- **Rollback Support**: Easy recovery if something goes wrong\n- **Permission Handling**: Work within GitHub token permission constraints\n\n## 🎯 Intelligent Issue Discovery (v1.7.0)\n\n### Positive Label Detection System\n\nModern repositories use automated labeling systems to identify **high-value, maintainer-approved issues**. These **positive labels** signal issues that are:\n\n- ✅ Ready for contribution (`queueable-fix`)\n- ✅ Reproducible and confirmed (`source-repro`)\n- ✅ Impact clearly assessed (`impact:*`)\n- ✅ Value-rated by maintainers (`issue-rating:`)\n\n**Golden Rule**: Prioritize issues with positive labels over random bugs.\n\n### Label Categories & Priority\n\n| Category | Label Pattern | Meaning | Priority |\n|----------|-------------|---------|----------|\n| Queueable | `*:queueable-fix`, `*:queue_fix_pr` | Marked as ready for PR work | ⭐⭐⭐⭐⭐ |\n| Reproducible | `*:source-repro`, `confirmed`, `reproducible` | Issue reproduction validated | ⭐⭐⭐⭐⭐ |\n| Impact Assessed | `impact:*`, `severity:*`, `priority:*` | Clear impact scope | ⭐⭐⭐⭐ |\n| Value Rated | `issue-rating: *`, `value:*`, `diamond`, `gold` | Official value rating | ⭐⭐⭐⭐⭐ |\n| Implementation Clear | `*:fix-shape-*`, `fix-shape-clear` | Clear implementation path | ⭐⭐⭐⭐ |\n| Contributor Welcome | `good first issue`, `help wanted`, `contributions welcome` | Explicitly inviting contributions | ⭐⭐⭐⭐ |\n| Scope Defined | `scope:*`, `area:*`, `module:*` | Clear modification scope | ⭐⭐⭐ |\n\n### OpenClaw-Specific Positive Labels\n\nOpenClaw uses **ClawSweeper** automation to identify high-value issues:\n\n```bash\n# ClawSweeper labels (HIGH PRIORITY - maintainer-validated)\ngh issue list --repo openclaw/openclaw --label \"clawsweeper:fix-shape-clear\" --state open\ngh issue list --repo openclaw/openclaw --label \"clawsweeper:queueable-fix\" --state open\ngh issue list --repo openclaw/openclaw --label \"clawsweeper:source-repro\" --state open\n\n# Impact assessment labels\ngh issue list --repo openclaw/openclaw --label \"impact:auth-provider\" --state open\n\n# Value rating labels (🦞 diamond lobster = HIGHEST VALUE)\ngh issue list --repo openclaw/openclaw --label \"issue-rating: 🦞 diamond lobster\" --state open\ngh issue list --repo openclaw/openclaw --label \"issue-rating: *\" --state open\n```\n\n**ClawSweeper Label Meanings**:\n- `clawsweeper:fix-shape-clear` → Clear implementation path identified\n- `clawsweeper:queueable-fix` → Marked as queue-able for PR work\n- `clawsweeper:source-repro` → High-confidence source-level reproduction found\n- `impact:auth-provider` → Auth/provider/model routing may break (critical)\n- `issue-rating: 🦞 diamond lobster` → Highest value issue (fix immediately)\n\n### Issue Discovery Workflow\n\n**Step 1: Explore Repository Labels**\n\n```bash\n# Discover all labels in the repository\ngh api repos/owner/repo/labels --paginate | jq '.[].name'\n\n# Filter for positive label patterns\ngh 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)'\n```\n\n**Step 2: Query Issues with Positive Labels**\n\n```bash\n# Single positive label\ngh issue list --repo owner/repo   --label \"clawsweeper:queueable-fix\"   --state open   --json number,title,labels,createdAt\n\n# Multiple positive labels (OR logic)\ngh issue list --repo owner/repo   --label \"queueable-fix,fix-shape-clear,source-repro\"   --state open   --json number,title,labels,createdAt\n\n# Value-rated issues only\ngh issue list --repo owner/repo   --label \"issue-rating: *\"   --state open   --json number,title,labels,createdAt\n```\n\n**Step 3: Prioritize by Label Combination**\n\n**Priority Tiers**:\n\n| Tier | Label Combination | Action |\n|------|------------------|--------|\n| 🦞 **Diamond** | queueable-fix + source-repro + impact:* | Fix immediately |\n| 💎 **Gold** | fix-shape-clear + impact:* | High priority |\n| 🔥 **Platinum** | source-repro + severity:critical | Urgent fix |\n| � **Silver** | good first issue + help wanted | Good start |\n| ✅ **Standard** | Single positive label | Normal queue |\n| ⚪ **Low** | No positive labels | Skip unless urgent |\n\n**Step 4: Analyze & Select**\n\n```bash\n# Get full issue details\ngh issue view <issue-number> --repo owner/repo\n\n# Check issue comments for context\ngh issue view <issue-number> --repo owner/repo --comments\n\n# Check if already being worked on\ngh pr list --repo owner/repo --search \"fixes #<issue-number>\"\n\n# Verify no existing PRs\ngh pr list --repo owner/repo --state open --search \"<issue-keyword>\"\n```\n\n### Multi-Repo Issue Discovery\n\n```bash\n# Search across multiple repositories\ngh search issues   --label \"queueable-fix,fix-shape-clear,source-repro\"   --state open   --limit 50   --json repository,title,number,url\n\n# Target specific organizations\ngh search issues   --owner openclaw   --label \"impact:*\"   --state open   --sort created   --order desc\n```\n\n### Issue Selection Decision Matrix\n\n**Proceed if issue has**:\n- ✅ At least 1 positive label (queueable/reproducible/impact)\n- ✅ Clear description and reproduction steps\n- ✅ No existing PR addressing it\n- ✅ Scope matches your expertise\n- ✅ Effort fits available time\n\n**Skip if issue has**:\n- ❌ No positive labels (unless urgent bug)\n- ❌ Unclear description or missing details\n- ❌ Existing PR in progress\n- ❌ Requires deep domain expertise you lack\n- ❌ Breaking changes or major refactoring\n\n### Quick Issue Discovery Commands\n\n```bash\n# One-liner: Find all queueable-fix issues\ngh issue list --repo openclaw/openclaw --label \"clawsweeper:queueable-fix\" --state open --limit 10\n\n# Find highest value issues (diamond rated)\ngh issue list --repo openclaw/openclaw --label \"issue-rating: 🦞 diamond lobster\" --state open\n\n# Find reproducible issues with clear implementation path\ngh issue list --repo openclaw/openclaw   --label \"clawsweeper:source-repro,clawsweeper:fix-shape-clear\"   --state open\n\n# Find impact:auth issues (critical system)\ngh issue list --repo openclaw/openclaw --label \"impact:auth-provider\" --state open\n\n# Batch discover: All positive labels\nfor label in \"clawsweeper:queueable-fix\" \"clawsweeper:fix-shape-clear\" \"clawsweeper:source-repro\"; do\n  echo \"=== $label ===\"\n  gh issue list --repo openclaw/openclaw --label \"$label\" --state open --json number,title --limit 5\ndone\n```\n\n### Integration with Contribution Workflow\n\nAfter discovering a high-value issue:\n\n1. **Validate** - Confirm issue is still open and unassigned\n2. **Comment** - Express interest, ask clarifying questions\n3. **Wait** - Get assigned before starting (respect maintainer process)\n4. **Follow Standard Workflow** - Fork → Sync → Branch → Fix → PR\n\n**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.\n\n\n## Usage\n\n### Basic Command\n```bash\n./github-contribution.sh <username> <owner/repo> <issue-number> <branch-name> [projects-root]\n```\n\n### Examples\n```bash\n# Fix issue #123 in openclaw/openclaw\n./github-contribution.sh Linux2010 openclaw/openclaw 123 fix/issue-description\n\n# Specify custom project root\n./github-contribution.sh Linux2010 openclaw/openclaw 456 fix/bug-fix /custom/path\n```\n\n## Fork Protection Best Practices\n\n### Main Branch Rules\n1. **Never commit directly** to fork's main branch\n2. **Always sync first** before creating new branches\n3. **Use feature branches** for all development work\n4. **Regular cleanup** of local pollution files\n\n### Safe Synchronization Script\n```bash\n#!/bin/bash\n# sync-fork.sh - Safe fork synchronization\n\ngit checkout main\ngit fetch upstream\ngit reset --hard upstream/main\ngit clean -fdx  # Remove all untracked files\n\n# Verify clean state\nif [[ $(git status --porcelain) ]]; then\n    echo \"❌ Warning: Working tree not clean\"\n    exit 1\nfi\necho \"✅ Fork synchronized successfully\"\n```\n\n### Local Git Configuration\n```bash\n# Prevent accidental main branch pushes\ngit config branch.main.pushRemote no_push\n\n# Set safe push default\ngit config push.default nothing\n```\n\n## Workflow Steps\n\n### Step 1: Fork Validation\n- Check if fork exists and is accessible\n- Verify upstream remote configuration\n- Validate current fork state cleanliness\n\n### Step 2: Synchronization  \n- Fetch latest from upstream official repository\n- Reset local main branch to match upstream exactly\n- Clean any untracked/local pollution files\n- Push synchronized state to fork (if permissions allow)\n\n### Step 3: Feature Branch Creation\n- Create new branch from clean main\n- Apply necessary changes and fixes\n- Commit with proper semantic format\n- Push feature branch to fork\n\n### Step 4: PR Creation\n- Generate PR with complete template\n- Link to relevant issue numbers\n- Include proper change type and scope\n- Add security impact assessment\n\n---\n\n## 🩺 Bug Fix Module: Change Plan\n\nBefore fixing any bug, **always write a change plan first**. This ensures minimal, safe changes and makes PR review easier.\n\n### The 5-Point Analysis\n\nAnswer these 5 questions in plain language before writing any code:\n\n| # | Question | Purpose |\n|---|----------|---------|\n| 1 | **Observed behavior** | What's broken? (What the user sees) |\n| 2 | **Expected behavior** | What should happen? (Correct behavior) |\n| 3 | **Suspected root cause** | Where's the bug? (Specific code location) |\n| 4 | **Safest seam to modify** | Minimal change location? (Narrowest fix) |\n| 5 | **Risk surface** | What else could break? (Impact scope) |\n\n### Change Plan Template\n\n```markdown\n## Change Plan for Issue #<number>\n\n1. **Observed behavior**:\n   <Describe what's broken - the user-visible symptom>\n\n2. **Expected behavior**:\n   <Describe what should happen instead>\n\n3. **Suspected root cause**:\n   <Point to specific file/line/function that causes the bug>\n\n4. **Safest seam to modify**:\n   <Identify the minimal code change location - smallest safe fix>\n\n5. **Risk surface**:\n   <List what could be affected by this change>\n```\n\n### Example: Issue #5968\n\n```markdown\n## Change Plan for Issue #5968\n\n1. **Observed behavior**:\n   `extract_content_or_reasoning()` crashes when `response.choices` is None, missing, or empty list.\n\n2. **Expected behavior**:\n   Function should return empty string gracefully when no usable choices exist.\n\n3. **Suspected root cause**:\n   Line `msg = response.choices[0].message` in `agent/auxiliary_client.py` assumes choices is always non-empty.\n\n4. **Safest seam to modify**:\n   Add a guard at the top of `extract_content_or_reasoning()` before accessing choices:\n   `if not getattr(response, \"choices\", None): return \"\"`\n\n5. **Risk surface**:\n   Minimal - only affects edge cases where API response is malformed.\n```\n\n### When to Use Change Plan\n\n| Scenario | Required? |\n|----------|-----------|\n| Bug fix | ✅ Always |\n| Paper-cut UX improvement | ✅ Always |\n| Feature addition | ❌ Use feature spec instead |\n| Refactoring | ❌ Use refactor plan instead |\n| Documentation fix | ❌ Not needed |\n\n### Benefits of Change Plan\n\n| Benefit | Why It Matters |\n|---------|----------------|\n| **Forces understanding** | Can't fix what you don't understand |\n| **Defines boundaries** | Prevents scope creep and \"opportunistic\" changes |\n| **Reduces risk** | Identifies potential side effects upfront |\n| **Speeds review** | Maintainer can understand intent in 20 seconds |\n| **Enables rollback** | Clear what was changed and why |\n\n### Change Plan Checklist\n\nBefore coding:\n- [ ] Can you describe the bug in one sentence?\n- [ ] Can you point to the exact line causing it?\n- [ ] Is your fix the smallest possible change?\n- [ ] Have you identified what else could break?\n- [ ] Will this change need a regression test?\n\nIf you answered \"no\" to any question, **do more investigation before coding**.\n\n---\n\n## 🧪 Live-Proof：如何让 PR 获得官方认可\n\n> **详细案例库见 [`live-proof-cases.md`](./live-proof-cases.md)** — 记录了真实 PR 中通过 ClawSweeper 评审的 live-proof 实践，开发 PR 时必读。\n\n### 什么是 live-proof？\n\nOpenClaw 的自动评审机器人 ClawSweeper 要求 PR 提供证明修复**实际生效**的证据。仅有\"单元测试通过\"不算充分 proof。\n\n**目标评级**：`status: 👀 ready for maintainer look` + `proof: sufficient` + Overall ≥ 🐚 platinum hermit\n\n### 评级体系（短板效应）\n\n`Overall = Proof 和 Patch quality 中较弱者`\n\n即使 patch 质量很高，如果 proof 不足，整体评级仍会被拉低。\n\n| 评级 | 含义 |\n|------|------|\n| 🦀 challenger crab | 卓越就绪 |\n| 🦞 diamond lobster | 很强，少量审查 |\n| 🐚 platinum hermit | 良好普通 PR |\n| 🦪 silver shellfish | 信号薄弱，需改进 |\n| 🧂 unranked krab | 不可合并 |\n\n### Live-Proof 形式\n\n被合并的 PR 全部使用**终端命令输出**（不用截图/视频）：\n\n| 类型 | 命令 | 适用 |\n|------|------|------|\n| 直接验证 | `node --import tsx -e \"...\"` | 配置验证、纯函数 |\n| 聚焦测试 | `node scripts/run-vitest.mjs <path>` | 运行时修复 |\n| 格式检查 | `git diff --check` | 代码格式 |\n\n### 最有效模式：BEFORE vs AFTER 对比\n\n```\nBEFORE (current main) - <invalid input> passed validation with ok: true\nAFTER - <invalid input> is rejected with clear error message\n```\n\n### 提交前必查\n\n- [ ] 提供了 BEFORE vs AFTER 对比（不只是 AFTER）\n- [ ] Proof 是终端命令输出，不是只有\"测试通过\"\n- [ ] 覆盖了边界值（最小、最大、无效）\n- [ ] 覆盖了幂等性（如涉及迁移）\n- [ ] **修改前能复现 bug**（测试在修复前会失败）\n- [ ] 修改的代码路径在正常情况下会被走到\n\n### 关键教训\n\n1. **收紧 config 验证 = 破坏性变更**：必须配 `openclaw doctor --fix` 迁移，否则已有配置升级后报错\n2. **Doctor 迁移用替换而非删除**：`gateway.port = DEFAULT` 比 `delete gateway.port` 更安全（配置行为明确）\n3. **修改前先证明 bug 在该路径**：写一个修复前会失败的测试；如果修复前就通过，bug 不在这\n4. **诚实面对找不到根因**：硬提交无效修复会被打 🧂 unranked krab；关闭 PR + 评论 issue 更好\n\n### 详细案例\n\n- ✅ **成功案例 #110051**：配置验证 + Doctor 迁移，`🦞 diamond lobster`\n- ✅ **成功案例 #109875**：竞品学习对象，`👀 ready for maintainer look`\n- ❌ **失败案例 #109885**：修改了不可达路径，`🧂 unranked krab` -> 关闭\n\n---\n\n## Error Handling\n\n### Common Issues & Solutions\n\n#### Fork Not Clean\n- **Problem**: Local main branch has extra commits/files\n- **Solution**: Force reset to upstream and clean untracked files\n\n#### Permission Denied (Workflow Scope)\n- **Problem**: Token lacks workflow permissions\n- **Solution**: Use web-based PR creation or update token permissions\n\n#### Upstream Not Configured  \n- **Problem**: Missing upstream remote\n- **Solution**: Auto-add upstream remote pointing to official repository\n\n#### Branch Already Exists\n- **Problem**: Feature branch already exists\n- **Solution**: Use unique branch naming or delete existing branch\n\n## Security Considerations\n\n### Token Permissions\n- **Minimum Required**: `repo` scope\n- **Optional**: `workflow` scope (for full automation)\n- **Never Grant**: Excessive permissions beyond contribution needs\n\n### Local Security\n- **File Cleanup**: Always clean working directory after contributions\n- **Credential Management**: Use secure credential storage\n- **Audit Trail**: Maintain logs of all contribution activities\n\n## Integration with Other Skills\n\n### PR Advocacy Skill\n- Hand off created PRs to PR Advocacy for monitoring\n- Share PR tracking information for continuous follow-up\n- Coordinate review response and maintenance\n\n### Document Spell Check Skill  \n- Pre-validate documentation changes before PR creation\n- Ensure all text content passes spell checking\n- Maintain documentation quality standards\n\n## High-Quality PR Best Practices (Maximize Merge Success Rate)\n\n### 🎯 Merge Success Rate Formula (Based on 30+ Merged PRs Analysis)\n\n```\nMerge Success Rate = \n  (PR Description Completeness × 0.2) +\n  (Review Response Speed × 0.25) +\n  (Test Coverage × 0.2) +\n  (Conflict Resolution Status × 0.15) +\n  (Review Resolution Rate × 0.2)\n```\n\n**Target**: > 80% success rate\n\n### ✅ 10 Success Characteristics (Must Follow 100%)\n\n1. ✅ **Complete PR Description** - Use template, fill ALL required fields\n2. ✅ **Fast Review Response** - < 30 minutes average response time\n3. ✅ **Small Focused Commits** - 1 commit solves 1 problem\n4. ✅ **100% Test Coverage** - Include edge cases and regression tests\n5. ✅ **Zero Conflicts** - Daily rebase upstream, keep CLEAN\n6. ✅ **Changelog Updated** - All user-visible changes\n7. ✅ **Security Checklist** - 5 required security questions\n8. ✅ **Human Verification Statement** - Manual test content + untested areas\n9. ✅ **Review Conversations Resolved** - 100% resolve bot review comments\n10. ✅ **Rollback Plan** - Rollback steps + known issues\n\n### 📋 Pre-Submission Checklist\n\nBefore pushing PR:\n\n**Code Quality:**\n- [ ] Title format: `type(scope): description`\n- [ ] Commit message: includes \"what\" + \"why\"\n- [ ] At least 1 new test case\n- [ ] CHANGELOG.md updated\n- [ ] 4-7 meaningful commits\n\n**CI Pre-flight (MUST pass locally):**\n- [ ] `pnpm protocol:check` - Protocol validation\n- [ ] `pnpm test` - All tests pass\n- [ ] `pnpm lint` - No lint errors\n- [ ] `pnpm tsc --noEmit` - TypeScript compilation\n\n**Review Readiness:**\n- [ ] Ready to respond within 24h\n- [ ] Greptile/Aisle Security comments addressed\n- [ ] Security questions answered (5 required)\n\n### 📊 High Success Rate PR Patterns\n\n#### Pattern 1: Security Fix Response (vincentkoc #44437)\n```\n7 commits in same day:\n1. Main fix implementation\n2. Changelog update\n3. Merge main (resolve conflicts)\n4. Tests: add coverage for review comments\n5. Fix: address Greptile suggestions\n6. Extra hardening (defensive programming)\n7. Merge main (final sync)\n```\n\n**Key Learnings:**\n- ✅ Separate commits for review responses\n- ✅ Tests and docs as separate commits\n- ✅ Frequent merge main to resolve conflicts\n- ✅ Extra hardening shows professionalism\n\n#### Pattern 2: Security Report Response (gumadeiras #44176)\n```markdown\nWhen Aisle Security reports issues:\n\n1. Quote SECURITY.md to explain why it's out of scope\n2. But still fix it (defensive programming)\n3. List specific hardening done\n4. Provide verification commands\n```\n\n**Key Learnings:**\n- ✅ Respond to security reports first\n- ✅ Explain scope判断 basis\n- ✅ Still fix it (show cooperation)\n- ✅ Provide verification method\n\n### ⚠️ Common Mistakes That Reduce Merge Rate\n\n| Mistake | Impact | Solution |\n|---------|--------|----------|\n| ❌ Missing Changelog | -20% | Always update CHANGELOG.md |\n| ❌ Slow review response (>24h) | -25% | Respond within 24h, ideally <30min |\n| ❌ Incomplete test coverage | -20% | Add tests for edge cases |\n| ❌ Merge conflicts | -15% | Daily rebase upstream |\n| ❌ Unresolved bot reviews | -20% | 100% resolve all comments |\n| ❌ CI failures | Automatic reject | Pre-flight check locally |\n\n### 🎯 Quality Metrics\n\n| Metric | Target | Current Best Practice |\n|--------|--------|----------------------|\n| **Greptile Score** | ≥ 4/5 | Address all P1/P2 issues |\n| **Aisle Security** | 0 unresolved | Respond or fix all |\n| **Test Coverage** | ≥ 1 new test | Include edge cases |\n| **CI Pass Rate** | 100% | Pre-check locally |\n| **Behind upstream** | 0 commits | Daily rebase |\n| **Response Time** | < 24h | Same day preferred |\n\n### 📝 PR Template Best Practices\n\n**Title Format:**\n```\n✅ fix(hooks): fail closed on unreadable loader paths\n✅ feat(context-engine): plumb sessionKey into all methods\n✅ docs: codify American English spelling convention\n✅ security: include accountId in session keys\n```\n\n**Commit Message Structure:**\n```\nFirst line: What was done (concise description)\n\nSecond paragraph: Why (problem background, impact)\n\nOptional: Regeneration-Prompt / AI assistance notes\n```\n\n**Example (#44411):**\n```\nfix(ci): restore generated protocol swift outputs\n\nRegenerate the Swift protocol models so PushTestResult keeps the \ntransport field required by the current gateway schema, and update \nprotocol:check to diff both generated Swift destinations because \nthe generator writes both files.\n\nRegeneration-Prompt: |\n  Investigate the protocol CI failure on current origin/main...\n```\n\n---\n\n## Best Practices\n\n### For Contributors\n- Always start from clean, synchronized main branch\n- Use descriptive branch names following convention\n- Fill complete PR templates with all required fields\n- Test changes locally before pushing\n- **Always rebase on the original PR branch** (never create new branches for rebase)\n- **Follow High-Quality PR Best Practices** (see section above)\n\n### PR Rebase Best Practices (Critical!)\n\n**Golden Rule**: Always rebase on the **original PR branch**, never create a new branch.\n\n#### Correct Rebase Workflow\n\n```bash\n# 1. Confirm current branch\ngit branch --show-current\n\n# 2. Confirm PR's branch name\ngh pr view <PR-number> --json headRefName --jq .headRefName\n\n# 3. Switch to correct branch if needed\ngit checkout <PR-branch-name>\n\n# 4. Rebase on the SAME branch (do NOT create new branch)\ngit fetch upstream\ngit rebase upstream/main\n\n# 5. Push to the SAME branch\ngit push -f origin <same-branch-name>\n```\n\n#### Common Mistakes to Avoid\n\n| ❌ Wrong | ✅ Correct |\n|---------|---------|\n| `git checkout -b new-branch` then rebase | Stay on original branch, rebase there |\n| Switch to diffe\n\nArchive v1.7.0: 7 files, 22199 bytes\n\nFiles: _meta.json (138b), github-contribution-workflow.md (4039b), live-proof-cases.md (12856b), scripts/github-contribution.sh (3565b), skill-card.md (2368b), skill.json (535b), SKILL.md (25843b)\n\nArchive v1.6.0: 6 files, 14804 bytes\n\nFiles: _meta.json (138b), github-contribution-workflow.md (4039b), scripts/github-contribution.sh (3565b), skill-card.md (2076b), skill.json (495b), SKILL.md (23595b)\n\nArchive v1.5.1: 6 files, 14875 bytes\n\nFiles: _meta.json (138b), github-contribution-workflow.md (4039b), scripts/github-contribution.sh (3565b), skill-card.md (2302b), skill.json (495b), SKILL.md (23595b)\n\nArchive v1.5.0: 6 files, 14889 bytes\n\nFiles: _meta.json (138b), github-contribution-workflow.md (4039b), scripts/github-contribution.sh (3565b), skill-card.md (1931b), skill.json (495b), SKILL.md (22042b)\n\nArchive v1.4.0: 6 files, 12397 bytes\n\nFiles: _meta.json (138b), github-contribution-workflow.md (4039b), scripts/github-contribution.sh (3565b), skill-card.md (2051b), skill.json (495b), SKILL.md (15878b)\n\nArchive v1.3.0: 5 files, 10054 bytes\n\nFiles: github-contribution-workflow.md (4039b), scripts/github-contribution.sh (3565b), skill.json (450b), SKILL.md (12912b), _meta.json (138b)","readmeExcerpt":"Skill: Github Contribution Owner: linux2010 Summary: Automated GitHub contribution workflow with intelligent issue discovery via positive label detection. Use when: (1) Contributing to open source projects, (2)... Tags: contribution:1.0.3, fork:1.0.3, github:1.0.3, github, contribution, opensource, pr:1.0.0, latest:1.7.4, protection:1.0.3 Version history: v1.7.4 | 2026-07-23T15:45:59.174Z | auto GitHub Contribution S","codeSnippets":[],"executableExamples":[{"language":"bash","snippet":"# ClawSweeper labels (HIGH PRIORITY - maintainer-validated)\ngh issue list --repo openclaw/openclaw --label \"clawsweeper:fix-shape-clear\" --state open\ngh issue list --repo openclaw/openclaw --label \"clawsweeper:queueable-fix\" --state open\ngh issue list --repo openclaw/openclaw --label \"clawsweeper:source-repro\" --state open\n\n# Impact assessment labels\ngh issue list --repo openclaw/openclaw --label \"impact:auth-provider\" --state open\n\n# Value rating labels (🦞 diamond lobster = HIGHEST VALUE)\ngh issue list --repo openclaw/openclaw --label \"issue-rating: 🦞 diamond lobster\" --state open\ngh issue list --repo openclaw/openclaw --label \"issue-rating: *\" --state open"},{"language":"bash","snippet":"# Discover all labels in the repository\ngh api repos/owner/repo/labels --paginate | jq '.[].name'\n\n# Filter for positive label patterns\ngh 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)'"},{"language":"bash","snippet":"# Single positive label\ngh issue list --repo owner/repo   --label \"clawsweeper:queueable-fix\"   --state open   --json number,title,labels,createdAt\n\n# Multiple positive labels (OR logic)\ngh issue list --repo owner/repo   --label \"queueable-fix,fix-shape-clear,source-repro\"   --state open   --json number,title,labels,createdAt\n\n# Value-rated issues only\ngh issue list --repo owner/repo   --label \"issue-rating: *\"   --state open   --json number,title,labels,createdAt"},{"language":"bash","snippet":"# Get full issue details\ngh issue view <issue-number> --repo owner/repo\n\n# Check issue comments for context\ngh issue view <issue-number> --repo owner/repo --comments\n\n# Check if already being worked on\ngh pr list --repo owner/repo --search \"fixes #<issue-number>\"\n\n# Verify no existing PRs\ngh pr list --repo owner/repo --state open --search \"<issue-keyword>\""},{"language":"bash","snippet":"# Search across multiple repositories\ngh search issues   --label \"queueable-fix,fix-shape-clear,source-repro\"   --state open   --limit 50   --json repository,title,number,url\n\n# Target specific organizations\ngh search issues   --owner openclaw   --label \"impact:*\"   --state open   --sort created   --order desc"},{"language":"bash","snippet":"# One-liner: Find all queueable-fix issues\ngh issue list --repo openclaw/openclaw --label \"clawsweeper:queueable-fix\" --state open --limit 10\n\n# Find highest value issues (diamond rated)\ngh issue list --repo openclaw/openclaw --label \"issue-rating: 🦞 diamond lobster\" --state open\n\n# Find reproducible issues with clear implementation path\ngh issue list --repo openclaw/openclaw   --label \"clawsweeper:source-repro,clawsweeper:fix-shape-clear\"   --state open\n\n# Find impact:auth issues (critical system)\ngh issue list --repo openclaw/openclaw --label \"impact:auth-provider\" --state open\n\n# Batch discover: All positive labels\nfor label in \"clawsweeper:queueable-fix\" \"clawsweeper:fix-shape-clear\" \"clawsweeper:source-repro\"; do\n  echo \"=== $label ===\"\n  gh issue list --repo openclaw/openclaw --label \"$label\" --state open --json number,title --limit 5\ndone"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"# GitHub Contribution Skill\n\n## Purpose\nAutomated GitHub contribution workflow with intelligent issue discovery via positive label detection. Handles fork synchronization, branch creation, PR submission while maintaining clean fork state, and provides live-proof guidance for passing automated code review.\n\n## Core Features\n\n### 1. Intelligent Issue Discovery (v1.7.2)\n- **Positive Label Detection**: Automatically identify high-value issues via maintainer-approved labels\n- **Priority Scoring**: Rank issues by contribution value and fix feasibility\n- **Smart Filtering**: Focus on queueable, reproducible, and high-impact issues\n- **Multi-Repo Support**: Discover issues across multiple target repositories\n\n### 2. Fork Protection & Synchronization\n- **Main Branch Protection**: Never commit directly to main branch\n- **Automatic Sync**: Regularly sync fork main with upstream official repository  \n- **Clean State Enforcement**: Ensure fork main branch matches official repository exactly\n- **Pollution Prevention**: Prevent local work files from contaminating main branch\n\n### 3. Automated Contribution Workflow\n- **Fork Setup**: Automatically configure upstream remote if not exists\n- **Branch Creation**: Create feature branches based on latest official code\n- **PR Submission**: Handle pull request creation with proper templates\n- **Issue Integration**: Link fixes to relevant GitHub issues\n\n### 4. Safety Measures\n- **Pre-flight Validation**: Verify fork cleanliness before starting\n- **Atomic Operations**: All changes happen in isolated feature branches\n- **Rollback Support**: Easy recovery if something goes wrong\n- **Permission Handling**: Work within GitHub token permission constraints\n\n## 🎯 Intelligent Issue Discovery (v1.7.2)\n\n### Positive Label Detection System\n\nModern repositories use automated labeling systems to identify **high-value, maintainer-approved issues**. These **positive labels** signal issues that are:\n\n- ✅ Ready for contribution (`queueable-fix`)\n- ✅ Reproducible and confirmed (`source-repro`)\n- ✅ Impact clearly assessed (`impact:*`)\n- ✅ Value-rated by maintainers (`issue-rating:`)\n\n**Golden Rule**: Prioritize issues with positive labels over random bugs.\n\n### Label Categories & Priority\n\n| Category | Label Pattern | Meaning | Priority |\n|----------|-------------|---------|----------|\n| Queueable | `*:queueable-fix`, `*:queue_fix_pr` | Marked as ready for PR work | ⭐⭐⭐⭐⭐ |\n| Reproducible | `*:source-repro`, `confirmed`, `reproducible` | Issue reproduction validated | ⭐⭐⭐⭐⭐ |\n| Impact Assessed | `impact:*`, `severity:*`, `priority:*` | Clear impact scope | ⭐⭐⭐⭐ |\n| Value Rated | `issue-rating: *`, `value:*`, `diamond`, `gold` | Official value rating | ⭐⭐⭐⭐⭐ |\n| Implementation Clear | `*:fix-shape-*`, `fix-shape-clear` | Clear implementation path | ⭐⭐⭐⭐ |\n| Contributor Welcome | `good first issue`, `help wanted`, `contributions welcome` | Explicitly inviting contributions | ⭐⭐⭐⭐ |\n| Scope Defined | `scope:*`, `area:*`, `module:*` | Clear mod"},{"path":"_meta.json","content":"{\n  \"ownerId\": \"kn7djfrkxdrrb6syjdv4vvtmp18252ry\",\n  \"slug\": \"github-contribution\",\n  \"version\": \"1.7.4\",\n  \"publishedAt\": 1784821559174\n}"},{"path":"github-contribution-workflow.md","content":"# GitHub 开源项目贡献完整工作流程\n\n## 1. Fork 和同步项目\n\n### Fork 官方仓库\n- 访问目标项目的 GitHub 页面（例如 `https://github.com/owner/repo`）\n- 点击右上角的 \"Fork\" 按钮\n- 选择你的 GitHub 账户作为 fork 目标\n\n### 克隆你的 Fork\n```bash\ngit clone https://github.com/your-username/repo.git\ncd repo\n```\n\n### 添加上游远程仓库\n```bash\ngit remote add upstream https://github formulate the official repository URL\ngit remote -v  # 验证远程仓库配置\n```\n\n### 同步 Fork 到最新状态\n```bash\n# 切换到 main/master 分支\ngit checkout main\n\n# 获取上游仓库的最新更改\ngit fetch upstream\n\n# 将上游的更改合并到本地\ngit merge upstream/main\n\n# 推送到你的 fork\ngit push origin main\n```\n\n## 2. 创建功能分支\n\n### 基于最新的 main 分支创建新分支\n```bash\n# 确保在 main 分支且已同步\ngit checkout main\ngit pull upstream main\n\n# 创建新的功能分支（使用描述性名称）\ngit checkout -b fix/issue-description\n# 或者\ngit checkout -b feature/new-functionality\n```\n\n### 分支命名约定\n- `fix/` - 用于 bug 修复\n- `feature/` - 用于新功能\n- `docs/` - 用于文档更新\n- `chore/` - 用于维护任务\n\n## 3. 开发和测试\n\n### 进行代码更改\n- 在功能分支上进行所有开发工作\n- 遵循项目的代码风格和规范\n- 编写必要的测试用例\n- 更新相关文档（如果需要）\n\n### 提交更改\n```bash\n# 查看更改状态\ngit status\n\n# 添加更改的文件\ngit add .\n\n# 提交更改（使用清晰的提交信息）\ngit commit -m \"fix: resolve issue with XYZ component\"\n\n# 推送到你的 fork\ngit push origin fix/issue-description\n```\n\n### 提交信息格式\n遵循 conventional commits 格式：\n- `fix:` - bug 修复\n- `feat:` - 新功能\n- `docs:` - 文档更新\n- `style:` - 代码格式更改\n- `refactor:` - 代码重构\n- `test:` - 测试相关\n- `chore:` - 构建过程或辅助工具的变动\n\n## 4. 创建 Pull Request\n\n### 通过 GitHub 网页界面创建 PR\n1. 访问你的 fork 仓库页面\n2. GitHub 通常会自动检测到新推送的分支并显示 \"Compare & pull request\" 按钮\n3. 点击该按钮进入 PR 创建页面\n\n### PR 标题和描述\n- **标题**: 清晰描述更改的目的（例如：\"Fix null pointer exception in auth handler\"）\n- **描述**: \n  - 说明问题的背景\n  - 描述解决方案\n  - 提及相关的 issue（使用 `Closes #123` 或 `Fixes #123`）\n  - 列出主要的更改点\n\n### PR 检查清单\n- [ ] 代码通过所有测试\n- [ ] 遵循项目代码风格\n- [ ] 包含必要的测试用例\n- [ ] 更新了相关文档\n- [ ] PR 描述清晰完整\n- [ ] 关联了相关 issue\n\n## 5. PR 审查和合并\n\n### 处理审查反馈\n- 及时响应审查者的评论\n- 根据反馈进行必要的修改\n- 使用新的提交来处理反馈（不要强制推送覆盖历史）\n\n### 更新 PR\n```bash\n# 在功能分支上进行修改\ngit add .\ngit commit -m \"address review feedback: improve error handling\"\ngit push origin fix/issue-description\n```\n\n### PR 合并后清理\n```bash\n# 切换回 main 分支\ngit checkout main\n\n# 删除本地功能分支\ngit branch -d fix/issue-description\n\n# 删除远程功能分支（可选）\ngit push origin --delete fix/issue-description\n```\n\n## 常见问题和最佳实践\n\n### 保持分支同步\n如果 PR 审查时间较长，可能需要将最新的上游更改合并到你的功能分支：\n```bash\ngit checkout main\ngit pull upstream main\ngit checkout fix/issue-description\ngit rebase main\ngit push --force-with-lease origin fix/issue-description\n```\n\n### 避免强制推送\n除非必要（如 rebase 后），避免使用 `--force` 推送，使用 `--force-with-lease` 更安全。\n\n### 小而专注的 PR\n- 每个 PR 应该解决一个具体的问题\n- 避免在一个 PR 中包含多个不相关的更改\n- 这样更容易审查和合并\n\n### 社区礼仪\n- 保持礼貌和专业的沟通\n- 及时响应审查反馈\n- 感谢维护者的审查时间\n- 遵循项目的贡献指南（CONTRIBUTING.md）"},{"path":"live-proof-cases.md","content":"# Live-Proof 案例库\n\n> 本文件记录真实 PR 中通过 ClawSweeper 评审、获得 `status: 👀 ready for maintainer look` 的 live-proof 实践。\n> 开发 PR 时参考本案例库，确保提供的 proof 足够充分。\n\n## 目录\n\n- [ClawSweeper 评级体系](#clawsweeper-评级体系)\n- [什么是 live-proof](#什么是-live-proof)\n- [案例一：配置验证类修复（#110051）](#案例一配置验证类修复110051)\n- [案例二：竞品对比学习（#109875）](#案例二竞品对比学习109875)\n- [失败案例：修改了不可达路径（#109885）](#失败案例修改了不可达路径109885)\n- [通用 Proof 模板](#通用-proof-模板)\n- [检查清单](#检查清单)\n\n---\n\n## ClawSweeper 评级体系\n\nClawSweeper（OpenClaw 的自动评审机器人）对 PR 给出三个维度的甲壳类评级：\n\n| 评级 | 含义 | 可合并性 |\n|------|------|----------|\n| 🦀 challenger crab | 罕见，卓越的就绪状态 | 极高 |\n| 🦞 diamond lobster | 很强，仅需少量 maintainer 审查 | 高 |\n| 🐚 platinum hermit | 良好的普通 PR，普通审查即可 | 中高 |\n| 🦐 gold shrimp | 有用信号，但 proof/confidence 仍有限 | 中 |\n| 🦪 silver shellfish | 信号薄弱，proof/validation/实现需改进 | 低 |\n| 🧂 unranked krab | 不可合并（proof 缺失或有严重问题） | 不可合并 |\n| 🌊 off-meta tidepool | 评级不适用 | N/A |\n\n### 三个评分维度\n\n| 维度 | 说明 |\n|------|------|\n| **Overall** | 综合 = proof 和 patch quality 中较弱者（短板效应） |\n| **Proof** | 真实行为证明的充分性 |\n| **Patch quality** | 代码实现质量 |\n\n> ⚠️ **关键规则**：`Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.`\n> 即使 patch 质量是 🐚 platinum hermit，如果 proof 只有 🦪 silver shellfish，整体仍是 🦪。\n\n### 状态标签\n\n| 标签 | 含义 |\n|------|------|\n| `status: 📣 needs proof` | 需要补充真实行为证明才能合并 |\n| `status: 👀 ready for maintainer look` | ClawSweeper 无 contributor 阻塞项，等待 maintainer 审查 |\n| `proof: sufficient` | Contributor 真实行为证明充分 |\n\n**目标**：获得 `status: 👀 ready for maintainer look` + `proof: sufficient`。\n\n---\n\n## 什么是 live-proof\n\nLive-proof（真实行为证明）是 ClawSweeper 要求的、证明修复**实际生效**的证据。\n\n### ❌ 不是 live-proof 的东西\n\n- 只有单元测试通过（\"X tests passed\"）\n- 纯代码阅读得出的结论（\"代码逻辑应该正确\"）\n- 声称修复有效但没有运行验证\n\n### ✅ 是 live-proof 的东西\n\n被合并的 PR 全部使用**终端命令输出**作为 proof，不用截图/视频：\n\n| Proof 类型 | 命令模式 | 适用场景 |\n|-----------|---------|---------|\n| 直接验证 | `node --import tsx -e \"...\"` | 配置验证、纯函数行为 |\n| 聚焦测试 | `node scripts/run-vitest.mjs <path>` | 运行时修复、回归测试 |\n| 完整 gate | `node scripts/check-changed.mjs -- <files>` | 多文件变更 |\n| 格式检查 | `git diff --check` / `oxfmt --check` | 代码格式 |\n| Autoreview | `autoreview --mode uncommitted` | 代码审查 |\n\n### 关键：BEFORE vs AFTER 对比\n\n最有效的 proof 是展示**修复前**和**修复后**的对比：\n\n```\nBEFORE (current main) - gateway.port: 65536 passed validation with ok: true\nAFTER - gateway.port: 65536 is rejected with clear error message\n```\n\n---\n\n## 案例一：配置验证类修复（#110051）\n\n**Issue**: #109293 - `gateway.port` 接受超出 TCP 端口范围的值\n**PR**: https://github.com/openclaw/openclaw/pull/110051\n**修复类型**: 配置 schema 收紧 + Doctor 迁移\n\n### 问题描述\n\n`gateway.port` 的 Zod schema 只有 `.positive()` 没有 `.max(65535)`，导致 `65536` 等无效端口通过验证。\n\n### 关键教训：收紧 config 验证 = 破坏性变更\n\n**这是最重要的教训。** 收紧 config schema 会让之前合法的配置变非法，必须配 Doctor 迁移！\n\n> CLAUDE.md 明确规定：\"If a config change invalidates existing files, add a matching `openclaw doctor --fix` migration.\"\n\n只加 schema 约束而不加 Doctor 迁移的后果：\n- 已有 `gateway.port: 65536` 的用户升级后直接报错，无升级路径\n- ClawSweeper 标记 `merge-risk: 🚨 compatibility`\n- 无法获得 `status: 👀 ready for maintainer look`\n\n### Doctor 迁移设计决策\n\n迁移应**替换为默"},{"path":"skill-card.md","content":"## Description:\n\nGithub Contribution helps agents discover maintainer-approved GitHub issues, prepare clean fork branches, and produce pull request contribution guidance with proof expectations.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[linux2010](https://clawhub.ai/user/linux2010)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and coding agents use this skill to identify suitable GitHub issues, prepare a synchronized fork and feature branch, and draft contribution-ready pull requests with concrete validation evidence.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The workflow can reset and clean a local repository, which may discard uncommitted work or untracked files.\n\nMitigation: Run it only in disposable or freshly cloned fork directories, check git status first, and back up or commit any local work before execution.\n\nRisk: The workflow may encourage broader GitHub token permissions than are needed for normal contribution tasks.\n\nMitigation: Prefer existing GitHub CLI or SSH authentication, or use fine-grained credentials limited to the relevant fork or repository.\n\nRisk: The automation depends on repository branch conventions and upstream remote state.\n\nMitigation: Manually verify the target repository, fork, upstream remote, and branch names before allowing push or pull request actions.\n\n## Reference(s):\n\n- [ClawHub Skill Page](https://clawhub.ai/linux2010/skills/github-contribution)\n- [Publisher Profile](https://clawhub.ai/user/linux2010)\n- [Skill Instructions](artifact/SKILL.md)\n- [Contribution Workflow](artifact/github-contribution-workflow.md)\n- [Live Proof Cases](artifact/live-proof-cases.md)\n- [Automation Script](artifact/scripts/github-contribution.sh)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, code, shell commands, guidance]\n\n**Output Format:** [Markdown guidance with inline shell commands and code snippets]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [May include repository-specific command sequences, PR text, checklists, and validation evidence templates.]\n\n## Skill Version(s):\n\n1.7.4 (source: server release evidence)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment."}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":"Automated GitHub contribution workflow with intelligent issue discovery via positive label detection. Use when: (1) Contributing to open source projects, (2)... Skill: Github Contribution Owner: linux2010 Summary: Automated GitHub contribution workflow with intelligent issue discovery via positive label detection. Use when: (1) Contributing to open source projects, (2)... Tags: contribution:1.0.3, fork:1.0.3, github:1.0.3, github, contribution, opensource, pr:1.0.0, latest:1.7.4, protection:1.0.3 Version history: v1.7.4 | 2026-07-23T15:45:59.174Z | auto GitHub Contribution S","editorialQuality":{"score":100,"threshold":65,"status":"ready","wordCount":1587,"uniquenessScore":46,"reasons":[]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-09T10:52:30.035Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-09T10:52:30.035Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-09T13:07:28.867Z","emptyReason":null},"items":[{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-10T18:48:31.762Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}