# Contribution Pipeline

> Full issue-to-PR lifecycle with 5-phase gated pipeline. Produces contributions maintainers look forward to — project-aware, thoroughly tested, security-gated, well-documented. Skill bundle with sub-skills for security, test quality, documentation, clean-room verification, and vault integration.

- Skill: `magnus919/contribution-pipeline` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds@latest add magnus919/contribution-pipeline`
- Raw SKILL.md: https://api.skillmd.com/api/skills/magnus919/contribution-pipeline/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: magnus919 (https://skillmd.com/u/magnus919)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/magnus919/contribution-pipeline

---


# Contribution Pipeline

Full lifecycle from assigned issue to merged PR. Five phases with concrete, falsifiable gates — no LLM-judged rubber stamps. Every phase produces an artifact that the next phase consumes. Every gate has a criterion that can fail.

**This is a skill bundle.** The orchestrator routes to sub-skills for specialized domains:

| Sub-Skill | Domain | When Loaded |
|---|---|---|
| `contribution-security` | Static analysis, secrets scanning, disclosure policies | P3.5 Security Gate |
| `contribution-test-quality` | Test design, change-detector prevention, scorecard | P2 Test Quality Gate |
| `contribution-documentation` | Code comments, commits, CHANGELOG, README, Mermaid | P2 Documentation + P4 PR Body |
| `contribution-clean-room` | Docker/VM verification, CI fingerprinting, environment classification | P3 Clean-Room Verification |
| `contribution-vault-integration` | Project fingerprint caching, knowledge graph persistence | P0 Caching + Cross-session |

---

## Trigger Patterns

The skill accepts input through four patterns:

| Pattern | Input | Example |
|---|---|---|
| **Issue-driven** (primary) | Issue URL or `owner/repo#number` | `https://github.com/org/repo/issues/42` |
| **Discovery-driven** | Repo URL + issue description | "Found a bug in org/repo: X crashes when Y is null" |
| **Kanban-driven** | Kanban card with `issue_url` + `repo` metadata | Card body parsed from structured fields |
| **Cohort-driven** | Multiple issue URLs sharing root cause | Consolidation detected → omnibus PR pattern |

**Pre-flight checks before any phase begins:**
- Issue exists and is open (not closed, not a discussion/RFC)
- No open PR already handles this issue
- No WIP PR in flight for this project (WIP limit: 1 per project, except <10-line fixes)
- Project's AI contribution policy allows agent-assisted contributions (check AGENTS.md, AI_POLICY.md)
- **If this is a follow-up to an existing PR, verify that PR's merge status first.** A PR with `state: MERGED` means branch fresh from main — do NOT push follow-up commits to a merged branch. A PR with `state: OPEN` means push to the same branch and update the PR body. Check via `gh pr view <number> --json state,mergedAt`.

---

## Quick Reference

| Phase | What It Produces | Gate (Falsifiable) | Time Budget |
|---|---|---|---|
| **P0: Muster & Orientation** | Project fingerprint (cached) | Can you describe what maintainers ACTUALLY enforce? | 5 min |
| **P1: Comprehension** | Reproduction trace + root-cause + baseline | Does repro script produce FAIL on target branch? | 15 min |
| **P2: Design & Implementation** | Working branch (tests fail before fix, pass after) | `git stash && cleanroom test run` green + test quality scorecard ≥6/8 | 30 min |
| **P3: Clean-Room Verification** | Verification report + CI divergence surface | All checks pass in isolation | 10 min |
| **P3.5: Security Gate** | Static analysis + secrets scan report | Zero critical/high findings. Zero secrets. | Auto |
| **P4: PR Creation** | Filled template + Conventional Commit + Mermaid | PR open, CI green, SLA disclosed | 5 min |
| **Post-PR** | CI monitoring + staleness handling | PR merged (skill-level Done) | Passive |

**Skill-level Done: PR is MERGED** — not just created. Post-PR is a passive responsibility tracked across sessions.

---

## Phase Definitions

See `references/phase-definitions.md` for the complete specification of each phase: required artifacts, gate criteria, rollback rules, and fallback paths.

See `references/gate-criteria.md` for the concrete, falsifiable criteria at every phase transition.

See `references/trigger-patterns.md` for the four input patterns with parsing, validation, and branching logic.

See `references/project-fingerprint-template.md` for the 8-field conventions card produced by P0.

See `references/remote-docker-verification.md` for the sync-build-recreate-test sequence when the build target is a remote Docker host (P3 clean-room verification).

See `references/patch-recovery.md` for recovery procedures when the `patch` tool corrupts a file (P2 implementation).

---

## Cross-Cutting Rules

1. **Every gate is falsifiable.** "Do you understand?" is not a gate. "Does the reproduction script produce a FAIL on the target branch?" is a gate.

2. **Project fingerprint caching.** P0 output cached per-project with HEAD hash. Subsequent PRs to the same project skip P0. Staleness check: compare cached HEAD hash against current. TTL: 1 hour.

3. **WIP limit: one PR per project.** Maintainer attention is the bottleneck, not code generation throughput. Exception: changes under 10 lines bypass the limit.

4. **Clean-room failure → comprehension, not implementation.** If P3 fails, the agent didn't understand the problem. Roll back to P1, not P2.

5. **"No defect the agent could reasonably catch."** Not "zero defects." Design preferences and edge case interpretations legitimately require human review.

6. **Honest SLA disclosure.** At PR creation: "I don't run continuously — responses within 24-48h." No aspirational promises that can't be kept.

7. **PR verbosity scales to change size.** ~50 + (lines_changed × 0.5) words max, capped at 500. A one-liner gets a 3-line PR body.

8. **Documentation written alongside code.** Commit messages, code comments, and inline docs happen during P2 implementation — not in a separate post-hoc phase.

9. **Safe-to-fail exits at every phase.** If the agent hits a blocker, report what's known and escalate. Don't generate increasingly wrong work.

10. **Templates lie. Merged PRs tell truth.** P0 must study 3-5 recently merged PRs from different contributors — not just read CONTRIBUTING.md.

11. **Triage test infrastructure before P3.** Before attempting clean-room verification, check what's available: `docker compose ps` for running fixtures, `which pytest` for test runner, `pip list 2>/dev/null | grep pytest` for package availability. If the full integration suite can't run, run the subset that can and document the gap in the PR body. A documented partial verification is better than a skipped gate or a fabricated pass.

---

## Sub-Skill Loading

At the appropriate phase, load the sub-skill for specialized domain guidance.
**If the sub-skill is not installed, use the fallback — do not skip the gate.**

| Phase | Sub-Skill | What It Provides | Fallback When Missing |
|---|---|---|---|
| P2 test quality | `contribution-test-quality` | Test design, change-detector prevention, 8-point scorecard | Manual scorecard: check each of the 8 criteria from gate-criteria.md via AST scan and heuristics |
| P2 documentation | `contribution-documentation` | Code comments, commits, CHANGELOG, README conventions | Follow project's merged PRs for documentation patterns. Conventional Commits with DCO sign-off. |
| P3 clean-room | `contribution-clean-room` | Docker/VM verification, CI fingerprinting, environment classification | See `references/remote-docker-verification.md`. Sync code, build, recreate, run test suite. Report what was verified and what wasn't. |
| P3.5 security | `contribution-security` | semgrep config, secrets scan, dependency check | Run `git diff main -- <changed-files>` and grep for: secrets patterns (`password`, `secret`, `key`, `token`, `AKIA`, `-----BEGIN`), debug artifacts (`print`, `pdb`, `breakpoint`), local paths (`/Users`, `/home/`, hostnames). If no new deps, skip dep check. |
| P0/P4 persistence | `contribution-vault-integration` | Project fingerprint caching, knowledge graph persistence | Skip — fingerprint freshness is checked by P0 staleness check. No vault write required. |

---

## Pitfalls

- **Don't skip P0 even on familiar projects.** The cached fingerprint may be stale. Run the staleness check before proceeding.
- **Don't create a PR until CI-equivalent verification passes.** "Ready for review" with red CI is the fastest way to lose maintainer trust.
- **Don't let the reproduction script pass before the fix.** If the test passes on the unmodified branch, the test is tautological — go back to P1.
- **Don't fill PR templates with N/A sections just to satisfy the gate.** If the change is trivial, use short-form and apologize in a comment.
- **Don't proceed past P1 if you can't reproduce.** File a "could not reproduce, here's what I tried" comment and stop.
- **Don't add Mermaid diagrams to one-line fixes.** The complexity threshold is 4+ sequential steps with branching.
- **Don't run builds outside disposable containers.** See contribution-security sub-skill for isolation requirements.
- **Enrich pipeline results before caching, not after.** If P2 adds metadata to pre-existing pipeline outputs (quality scores, classification results, verification flags), call the enrichment function BEFORE `_set_cache()` or equivalent. Caching a result before enriching it means all subsequent cache hits return stale data without the new field. Pattern: `result = _enrich(result); _set_cache(url, result); return result` — not `_set_cache(url, result); return _enrich(result)`.
- **Triage test infrastructure before assuming tests will run.** At P3, check: is Docker running? Are fixture containers deployed? Is pytest installed in the target environment? If integration tests require containers that aren't available, fall back to unit tests, or run the subset of tests that work in the current environment and clearly report what was verified vs. skipped.
- **Recover from patch corruption by rewinding, not patching more.** If the `patch` tool corrupts a file (lint fails after patch, or the file structure is broken), do NOT try to patch the corrupted state — the match context is now unreliable. Instead: (1) restore the file from git (`git checkout <path>`), (2) re-read the current file content to get fresh line numbers and context, (3) re-apply the edit with more surrounding context. For files under 200 lines, it's faster to rewrite entirely. If the file is >500 lines and heavily modified, escalate.

---

## Cross-Reference

- **`opensource-contributions`** — OSS etiquette, phase references (0-4), default posture
- **`hermes-contrib`** — Hermes-Agent-specific conventions, PR templates, privacy rules
- **`github-pr-workflow`** — PR lifecycle, branch naming, conventional commits
- **`github-issues`** — Issue filing, labeling, agent disclosure
- **`github-code-review`** — Code review response patterns