docs(github-contributor): add evidence-loop, redaction, and merge-ready PR guidance

github-contributor/SKILL.md

@@ -7,6 +7,11 @@ description: Strategic guide for becoming an effective GitHub contributor. Cover
 
 Strategic guide for becoming an effective GitHub contributor and building your open-source reputation.
 
+## Prerequisites
+
+- Install GitHub CLI and verify availability: `gh --version`
+- Authenticate before running commands: `gh auth status || gh auth login`
+
 ## The Strategy
 
 **Core insight**: Many open-source projects have room for improvement. By contributing high-quality PRs, you:
@@ -102,7 +107,7 @@ Opportunity signals:
 
 ```bash
 # GitHub search for good first issues
-gh search issues "good first issue" --language=python --sort=created
+gh search issues "good first issue" --language=python --sort=created --state=open
 
 # Search by topic
 gh search repos "topic:cli" --sort=stars --limit=20
@@ -129,15 +134,23 @@ Pre-PR Checklist:
 **Title**: Clear, conventional format
 
 ```
-feat: Add support for YAML config files
-fix: Resolve race condition in connection pool
-docs: Update installation instructions for Windows
-refactor: Extract validation logic into separate module
+feat(config): add support for YAML config files
+fix(pool): resolve race condition in connection pool
+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.
+
+- 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.
+
 **Description**: Structured and thorough
 
-```markdown
+````markdown
 ## Summary
 [What this PR does in 1-2 sentences]
 
@@ -148,12 +161,48 @@ refactor: Extract validation logic into separate module
 - [Change 1]
 - [Change 2]
 
+## 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]
+
 ## Testing
 [How you tested this]
 
 ## Screenshots (if UI)
 [Before/After images]
-```
+````
 
 ### After Submitting
 
@@ -217,6 +266,9 @@ Contribution Workflow:
 - [ ] Comment on issue to claim
 - [ ] 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
@@ -232,13 +284,13 @@ Contribution Workflow:
 gh repo fork owner/repo --clone
 
 # Create PR
-gh pr create --title "feat: ..." --body "..."
+gh pr create --title "feat(scope): ..." --body "..."
 
 # Check PR status
 gh pr status
 
 # View project issues
-gh issue list --repo owner/repo --label "good first issue"
+gh issue list --repo owner/repo --label "good first issue" --state=open
 ```
 
 ### Commit Message Format

github-contributor/references/communication_templates.md

@@ -82,7 +82,7 @@ After:
 
 ### Feature Addition
 
-```markdown
+````markdown
 ## Summary
 
 Implements #[issue number]
@@ -112,7 +112,7 @@ result = new_feature(...)
 ## Migration Guide (if breaking)
 
 [Instructions for users to migrate]
-```
+````
 
 ### Documentation Update
 
@@ -133,6 +133,92 @@ Improves documentation for [area].
 [Screenshot or link to rendered docs]
 ```
 
+### Required PR Addendum
+
+Use this block in every PR description.
+
+````markdown
+## Evidence Loop
+
+Command:
+```bash
+# Baseline (before fix)
+[command]
+
+# Fixed (after fix, same command)
+[command]
+```
+
+Raw output:
+```text
+[baseline output]
+```
+
+```text
+[fixed output]
+```
+
+## Comparison (Baseline vs Fixed vs Reference)
+
+| Case | Command / Scenario | Result | Evidence |
+|------|--------------------|--------|----------|
+| Baseline | `[same command]` | Fail | [raw output block] |
+| Fixed | `[same command]` | Pass | [raw output block] |
+| Reference | [spec, issue, or main behavior] | Expected | [link or note] |
+
+## Sources/Attribution
+
+- [Issue, docs, benchmark source, or code reference]
+
+## Risks
+
+- [Risk and impact]
+
+## Rollback Plan
+
+- Revert commit(s): [hash]
+- Restore previous behavior with: [command]
+````
+
+## Reproducible PR Comment
+
+Use this template when maintainers ask for proof or rerun details.
+
+````markdown
+Validated with the same command before and after the fix.
+
+### Command
+```bash
+[command]
+```
+
+### Environment
+- OS: [name/version]
+- Runtime: [language/runtime + version]
+- Commit: [sha]
+- Runner: [local shell or CI job URL]
+
+### Baseline Output (before fix)
+```text
+[raw output]
+```
+
+### Fixed Output (after fix, same command)
+```text
+[raw output]
+```
+
+### Reference Output / Expected Behavior
+```text
+[spec output or expected result]
+```
+
+### Redaction Check
+- [x] Removed local absolute paths (for example, `/Users/...`)
+- [x] Removed tokens/secrets
+- [x] Removed internal URLs/hostnames
+````
+
 ## Responding to Reviews
 
 ### Accepting Feedback

github-contributor/references/pr_checklist.md

@@ -44,6 +44,20 @@ refactor/extract-validation-logic
 - [ ] No unnecessary changes (whitespace, imports)
 - [ ] Comments explain "why", not "what"
 
+### Evidence Loop
+
+- [ ] Reproduce the failure with one command and capture baseline output
+- [ ] Apply the fix
+- [ ] Rerun the exact same command and capture passing output
+- [ ] Add baseline vs fixed vs reference comparison
+
+### Redaction Gate
+
+- [ ] Remove local absolute paths (for example, `/Users/...`) from logs and screenshots
+- [ ] Remove secrets/tokens/API keys from logs and screenshots
+- [ ] Remove internal URLs/hostnames from logs and screenshots
+- [ ] Recheck every pasted block before submitting
+
 ### Documentation
 
 - [ ] README updated (if applicable)
@@ -59,6 +73,9 @@ refactor/extract-validation-logic
 - [ ] Testing approach
 - [ ] Screenshots (for UI changes)
 - [ ] Related issues linked
+- [ ] Sources/Attribution section added
+- [ ] Risks section added
+- [ ] Rollback Plan section added
 
 ## PR Title Format
 
@@ -76,7 +93,7 @@ chore(deps): update lodash to 4.17.21
 
 ## PR Description Template
 
-```markdown
+````markdown
 ## Summary
 
 Brief description of what this PR does.
@@ -93,6 +110,47 @@ Closes #123
 - Change 2
 - Change 3
 
+## Evidence Loop
+
+Command:
+```bash
+# Baseline (before fix)
+[command]
+
+# Fixed (after fix, same command)
+[command]
+```
+
+Raw output:
+```text
+[baseline output]
+```
+
+```text
+[fixed output]
+```
+
+## Comparison (Baseline vs Fixed vs Reference)
+
+| Case | Command / Scenario | Result | Evidence |
+|------|--------------------|--------|----------|
+| Baseline | `[same command]` | Fail | [raw output block] |
+| Fixed | `[same command]` | Pass | [raw output block] |
+| Reference | [spec, issue, or main behavior] | Expected | [link or note] |
+
+## Sources/Attribution
+
+- [Issue, docs, benchmark source, or code reference]
+
+## Risks
+
+- [Risk and impact]
+
+## Rollback Plan
+
+- Revert commit(s): [hash]
+- Restore previous behavior with: [command]
+
 ## Testing
 
 How did you test this change?
@@ -112,6 +170,16 @@ How did you test this change?
 - [ ] Tests pass
 - [ ] Documentation updated
 - [ ] Code follows project style
+````
+
+## Comparison Table Template
+
+```markdown
+| Case | Command / Scenario | Result | Evidence |
+|------|--------------------|--------|----------|
+| Baseline | `[same command]` | Fail | [raw output block] |
+| Fixed | `[same command]` | Pass | [raw output block] |
+| Reference | [spec, issue, or main behavior] | Expected | [link or note] |
 ```
 
 ## After Submitting