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:

Trigger Patterns

The skill accepts input through four patterns:

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

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.

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