docs(github-contributor): add high-quality PR formula and investigation workflow

- Add 10-point high-quality PR formula based on real-world success cases - Add investigation phase workflow (post to issue before PR) - Add git history tracing techniques (git log, git blame) - Add evidence-loop pattern (reproduce → trace → link → post) - Add high-quality PR case study reference - Update PR checklist with investigation steps - Emphasize separation of concerns (detailed analysis in issue, fix summary in PR) Key principles: - Deep investigation before coding - Minimal, surgical fixes - Professional communication - No internal/irrelevant details in PR Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-11 13:58:58 +08:00
parent 6dc2805f03
commit 29f85d27c3
3 changed files with 717 additions and 140 deletions
--- a/github-contributor/SKILL.md
+++ b/github-contributor/SKILL.md
@@ -118,6 +118,23 @@ gh search repos "topic:cli" --sort=stars --limit=20

 ## PR Excellence

+### The High-Quality PR Formula
+
+Based on real-world successful contributions to major open-source projects:
+
+```
+1. Deep investigation (post to issue, not PR)
+2. Minimal, surgical fix (only change what's necessary)
+3. Regression test (prevent future breakage)
+4. CHANGELOG entry (if project uses it)
+5. End-to-end validation (prove bug exists, prove fix works)
+6. Clear PR structure (~50 lines, focused)
+7. Professional communication
+8. Separate concerns (detailed analysis in issue, fix summary in PR)
+9. No internal/irrelevant details
+10. Responsive to feedback
+```
+
 ### Before Writing Code

 ```
@@ -127,6 +144,38 @@ Pre-PR Checklist:
 - [ ] Comment on issue to claim it
 - [ ] Understand project conventions
 - [ ] Set up development environment
+- [ ] Trace through git history for context
+- [ ] Identify root cause with evidence
+```
+
+### Investigation Phase (Post to Issue)
+
+**Do this BEFORE coding**:
+
+1. **Reproduce the bug** with exact commands and output
+2. **Trace git history** to understand context
+   ```bash
+   git log --all --grep="keyword" --oneline
+   git blame file.ts | grep "relevant_line"
+   ```
+3. **Link related issues/PRs** that provide context
+4. **Post detailed analysis to issue** (not PR)
+   - Timeline of related changes
+   - Root cause explanation
+   - Why previous approaches didn't work
+
+**Example structure**:
+```markdown
+## Investigation
+
+I traced this through the codebase history:
+
+1. [Date]: #[PR] introduced [feature]
+2. [Date]: #[PR] added [workaround] because [reason]
+3. [Date]: #[PR] changed [parameter]
+4. Now: Safe to [fix] because [explanation]
+
+[Detailed evidence with code references]
 ```

 ### Writing the PR
@@ -140,76 +189,151 @@ docs(readme): update installation instructions for Windows
 refactor(validation): extract validation logic into separate module
 ```

-**Evidence loop**: Prove the change with a reproducible fail -> fix -> pass loop.
+**Keep PR description focused** (~50 lines):
+- Summary (1-2 sentences)
+- Root cause (technical, with code refs)
+- Changes (bullet list)
+- Why it's safe
+- Testing approach
+- Related issues

- Reproduce the failure with one command.
- Apply the fix.
- Rerun the exact same command and capture the passing output.
- Compare baseline vs fixed vs reference behavior.
- Redact local paths, secrets, tokens, and internal hostnames before posting logs or screenshots.
+**Move detailed investigation to issue comments**, not PR.

-**Description**: Structured and thorough
+### Evidence Loop
+
+**Critical**: Prove the change with a reproducible fail → fix → pass loop.
+
+1. **Reproduce failure** with original version
+   ```bash
+   # Test with original version
+   npm install -g package@original-version
+   [command that triggers bug]
+   # Capture: error messages, exit codes, timestamps
+   ```
+
+2. **Apply fix** and test with patched version
+   ```bash
+   # Test with fixed version
+   npm install -g package@fixed-version
+   [same command]
+   # Capture: success output, normal exit codes
+   ```
+
+3. **Document both** with timestamps, PIDs, exit codes, logs
+
+4. **Redact sensitive info**:
+   - Local absolute paths (`/Users/...`, `/home/...`)
+   - Secrets/tokens/API keys
+   - Internal URLs/hostnames
+   - Recheck every pasted block before submitting
+
+**Description**: Focused and reviewable (~50 lines)

 ````markdown
 ## Summary
-[What this PR does in 1-2 sentences]
+[1-2 sentences: what this fixes and why]

-## Motivation
-[Why this change is needed]
+## Root Cause
+[Technical explanation with code references]

 ## Changes
- [Change 1]
- [Change 2]
+- [Actual code changes]
+- [Tests added]
+- [Docs updated]

-## Evidence Loop
-Command:
-```bash
-# Baseline (before fix)
-[command]
-
-# Fixed (after fix, same command)
-[command]
-```
-
-Raw output:
-```text
-[paste baseline output]
-```
-
-```text
-[paste fixed output]
-```
-
-## Comparison
-| Case | Command / Scenario | Result | Evidence |
-|------|--------------------|--------|----------|
-| Baseline | `[same command]` | Fail | [raw output block] |
-| Fixed | `[same command]` | Pass | [raw output block] |
-| Reference | [spec, issue, or main branch behavior] | Expected | [link or note] |
-
-## Sources/Attribution
- [Issue, docs, or code references]
-
-## Risks
- [Potential downside and impact]
-
-## Rollback Plan
- Revert commit(s): [hash]
- Restore previous behavior with: [command]
+## Why This Is Safe
+[Explain why it won't break anything]

 ## Testing
-[How you tested this]

-## Screenshots (if UI)
-[Before/After images]
+### Test 1: Reproduce Bug (Original Version)
+Command: `[command]`
+Result:
+```text
+[failure output with timestamps, exit codes]
+```
+
+### Test 2: Validate Fix (Patched Version)
+Command: `[same command]`
+Result:
+```text
+[success output with timestamps, exit codes]
+```
+
+## Related
+- Fixes #[issue]
+- Related: #[other issues/PRs]
 ````

+**What NOT to include in PR**:
+- ❌ Detailed timeline analysis (put in issue)
+- ❌ Historical context (put in issue)
+- ❌ Internal tooling mentions
+- ❌ Speculation or uncertainty
+- ❌ Walls of text (>100 lines)
+
+### Code Changes Best Practices
+
+**Minimal, surgical fixes**:
+- ✅ Only change what's necessary to fix the bug
+- ✅ Add regression test to prevent future breakage
+- ✅ Update CHANGELOG if project uses it
+- ❌ Don't refactor surrounding code
+- ❌ Don't add "improvements" beyond the fix
+- ❌ Don't change unrelated files
+
+**Example** (OpenClaw PR #39763):
+```
+Files changed: 2
+- src/infra/process-respawn.ts (3 lines removed, 1 added)
+- src/infra/process-respawn.test.ts (regression test added)
+
+Result: 278K star project, clean approval
+```
+
+### Separation of Concerns
+
+**Issue comments**: Detailed investigation
+- Timeline analysis
+- Historical context
+- Related PRs/issues
+- Root cause deep dive
+
+**PR description**: Focused on the fix
+- Summary (1-2 sentences)
+- Root cause (technical)
+- Changes (bullet list)
+- Testing validation
+- ~50 lines total
+
+**Separate test comment**: End-to-end validation
+- Test with original version (prove bug)
+- Test with fixed version (prove fix)
+- Full logs with timestamps
+
 ### After Submitting

- Respond to feedback promptly
+- Monitor CI results
+- Respond to feedback promptly (within 24 hours)
 - Make requested changes quickly
 - Be grateful for reviews
- Don't argue, discuss
+- Don't argue, discuss professionally
+- If you need to update PR:
+  - Add new commits (don't force push during review)
+  - Explain what changed in comment
+  - Re-request review when ready
+
+**Professional responses**:
+```
+✅ "Good point! I've updated the implementation to..."
+✅ "Thanks for catching that. Fixed in commit abc123."
+✅ "I see what you mean. I chose this approach because...
+    Would you prefer if I changed it to...?"
+
+❌ "That's just your opinion."
+❌ "It works on my machine."
+❌ "This is how I always do it."
+```

 ## Building Reputation

@@ -243,35 +367,70 @@ Level 4: Maintainer status

 ### Don't

- Submit drive-by PRs without context
+- Submit drive-by PRs without investigation
+- Include detailed timeline in PR (put in issue)
+- Mention internal tooling or infrastructure
 - Argue with maintainers
 - Ignore code style guidelines
 - Make massive changes without discussion
 - Ghost after submitting
+- Refactor code unrelated to the fix
+- Add "improvements" beyond what was requested
+- Force push during review (unless asked)

 ### Do

+- Investigate thoroughly BEFORE coding
+- Post detailed analysis to issue, not PR
+- Keep PR focused and minimal (~50 lines)
 - Start with small, focused PRs
 - Follow project conventions exactly
+- Add regression tests
+- Update CHANGELOG if project uses it
 - Communicate proactively
 - Accept feedback gracefully
 - Build relationships over time
+- Test with both original and fixed versions
+- Redact sensitive info from logs

 ## Workflow Template

 ```
-Contribution Workflow:
+High-Quality Contribution Workflow:
+
+Investigation Phase:
 - [ ] Find project with "good first issue"
 - [ ] Read contribution guidelines
 - [ ] Comment on issue to claim
+- [ ] Reproduce bug with original version
+- [ ] Trace git history for context
+- [ ] Identify root cause with evidence
+- [ ] Post detailed analysis to issue
+
+Implementation Phase:
 - [ ] Fork and set up locally
- [ ] Make focused changes
- [ ] Run evidence loop (reproduce fail -> apply fix -> rerun same command pass)
- [ ] Add baseline vs fixed vs reference comparison
- [ ] Redact paths/secrets/internal hosts in logs and screenshots
- [ ] Test thoroughly
- [ ] Write clear PR description
- [ ] Respond to review feedback
+- [ ] Make minimal, focused changes
+- [ ] Add regression test
+- [ ] Update CHANGELOG (if applicable)
+- [ ] Follow project conventions exactly
+
+Validation Phase:
+- [ ] Test with original version (prove bug exists)
+- [ ] Test with fixed version (prove fix works)
+- [ ] Document both with timestamps/logs
+- [ ] Redact paths/secrets/internal hosts
+
+Submission Phase:
+- [ ] Write focused PR description (~50 lines)
+- [ ] Link to detailed issue analysis
+- [ ] Post end-to-end test results
+- [ ] Ensure CI passes
+
+Review Phase:
+- [ ] Respond to feedback within 24 hours
+- [ ] Make requested changes quickly
+- [ ] Don't force push during review
+- [ ] Thank reviewers
 - [ ] Celebrate when merged! 🎉
 ```

@@ -310,3 +469,28 @@ Types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`
 - `references/pr_checklist.md` - Complete PR quality checklist
 - `references/project_evaluation.md` - How to evaluate projects
 - `references/communication_templates.md` - Issue/PR templates
+- `references/high_quality_pr_case_study.md` - Real-world successful PR walkthrough (OpenClaw #39763)
+
+## Success Indicators
+
+You know you have a high-quality PR when:
+
+- ✅ Maintainers understand the problem immediately
+- ✅ Reviewers can verify the fix easily
+- ✅ CI passes on first try
+- ✅ No "can you explain..." questions
+- ✅ Minimal back-and-forth
+- ✅ Quick approval
+
+## Key Metrics for Quality PRs
+
+Based on successful contributions to major projects:
+
+- **Files changed**: 1-3 (focused scope)
+- **Lines changed**: 10-50 (minimal fix)
+- **PR description**: ~50 lines (concise)
+- **Issue investigation**: 100-300 lines (thorough)
+- **Time to first draft**: 2-3 days (proper investigation)
+- **Time to ready**: 3-5 days (including validation)
+- **Response time**: <24 hours (professional)
+