💡 PR Pipeline Deadlock Root-Cause Attribution Engine

[github-actions[bot]]

Summary

When a stalled PR is detected by the daily health check, run a diagnostic cascade through every gate in the review pipeline (CI status, advisory bot reviews, maintainer-comment gate, hold gate, automation budget, review cycle) to identify the specific blocker and sub-cause — instead of just reporting that a PR is stalled. Attach structured root-cause attribution to the health-check issue so maintainers can resolve deadlocks in minutes rather than hours of manual gate-by-gate inspection.

Market Signal

GitHub shipped the async merge API (GA Oct 1 2026) and Copilot Agent merge (preview Sept 2026) that autonomously handle review feedback and merge conflicts — the platform is moving toward self-diagnosing pipelines. CodeRabbit added auto-fix PRs for failed CI (Oct 2026). The industry expectation is that automation should diagnose its own failures, not just report symptoms. Cursor's security review agent (Sept 2026) now blocks CI on findings with structured attribution — the "what is blocking and why" pattern is becoming table stakes.

User Signal

Daily stalled-PR health checks (#2016, #1990, #1986) detect symptoms but never attribute causes. Multiple bugs trace to gate blockers that took days of manual diagnosis:

• A lost fix-bot-comment run is never retried — a bot comment stays undispositioned and the PR stalls at the maintainer-comment gate forever (#2009) #2017: undispositioned bot comment strands PR at the maintainer-comment gate forever
• CodeRabbit's Security Architecture Review is throttled separately from its code review — findings in both sections must be addressed, and an in-place edit after disposition must re-open the comment #2008: CodeRabbit's separate security throttle blocks gate independently of its code review
• Advisory gate cannot count Graphite's check-run clean pass: every clean PR waits out the 20-minute timeout #2005: advisory gate cannot count Graphite's check-run clean pass — every clean PR waits out the 20-minute timeout
• 10 of 11 open PRs have never received an approving review: the advisory quorum is unmeetable, the disposition gate revokes what does issue, and nothing reports why #1894: 10 of 11 PRs never received an approving review — the advisory quorum was unmeetable
• Recurring bot quota/trial notices (Codex usage limits, Qodo trial, CodeRabbit review-limit) still block approval — add info_status_patterns; fix stale maintainer-resolve refusal message #1932: recurring bot quota/trial notices block approval with no automated path to clear them

The diagnostic data is computable today — maintainer-comment-gate.sh, advisory-review-gate.sh, hold-gate.sh, ci-status.sh, pr-automation-budget.sh, and review-cycle.sh are all pure-logic scripts — but it is never assembled into a single root-cause report.

Technical Opportunity

All gate functions are already implemented as pure-logic scripts under scripts/lib/:

• ci-status.sh — required vs non-required context evaluation
• advisory-review-gate.sh — bot review readiness check
• maintainer-comment-gate.sh — undispositioned comment detection
• hold-gate.sh — hold classification (budget-exhaustion, cycle-cap, rate-limit-only, manual)
• pr-automation-budget.sh — automation budget/cycle state
• review-cycle.sh — review cycle progression

A root-cause engine (scripts/lib/pr-deadlock-diagnose.sh) would source each gate, call its check function against a stalled PR, and produce structured JSONL output per gate with status (PASS/BLOCKED/DEGRADED), specific sub-cause, and suggested remediation action. The stall detector (pr-stall-detect.sh) already identifies candidate PRs — this adds a second diagnostic pass that explains WHY each is stalled.

Assessment

Dimension	Score	Rationale
Feasibility	high	All gate functions exist as pure-logic scripts; the diagnostic engine is a composition layer, not new logic
Impact	high	Directly reduces the human time to diagnose and resolve the most common PR pipeline failure mode
Urgency	high	Stalled-PR health checks fire daily; the deadlock pattern recurs weekly with new bot integrations

Adversarial Review

Strongest objection: The gate scripts were designed for real-time pass/fail decisions, not diagnostic reporting. Retrofitting them to expose sub-causes (not just binary verdicts) may require refactoring each gate to return structured diagnostics instead of exit codes.

Rebuttal: The refactoring is incremental — each gate already logs its reason to stderr or step summary. Capturing that diagnostic output into a structured format is a matter of wrapping the existing functions, not rewriting them. Start with the top 3 blockers by frequency (maintainer-comment-gate, advisory-review-gate, CI-status) and expand. The pr-stall-detect.sh already outputs a candidate list that the diagnostic pass can iterate over.

Suggested Next Step

Instrument the top-3 gate scripts (maintainer-comment-gate.sh, advisory-review-gate.sh, ci-status.sh) to return structured JSON diagnostics alongside their boolean verdict, then build a wrapper in scripts/lib/pr-deadlock-diagnose.sh that iterates over stalled PR candidates and assembles a per-PR root-cause report for the health-check issue.