avifenesh/pr-stall-detector

Skill: pr-stall-detector

Description

Detect agent-cairn PRs that have stalled (no activity ≥90 min) and classify the failure mode to route to appropriate recovery agent.

Stalled PRs cause critical delays in the Cairn development pipeline. This skill identifies which PRs have gone cold and why, enabling rapid diagnosis and targeted recovery.

Trigger

• Automated cron: "Detect stalled agent-cairn PRs and dispatch recovery"
• Manual: User asks "Check for stalled PRs"

Inclusion

on-demand

Allowed Tools

• cairn.shell
• cairn.readFile
• cairn.grep
• cairn.spawnSubagent
• cairn.publishToFeed

Algorithm

Phase 1: Detection

For each open agent-cairn PR:

1. Check last_activity_at timestamp against stall threshold (90 min)
2. Calculate gap = now - last_activity_at
3. If gap < threshold, PR is active (skip)
4. If gap >= threshold, PR is stalled (proceed to classification)

Phase 2: Classification

Identify the failure mode using priority-ordered rules:

| Priority | Mode | Condition | Score | |----------|------|-----------|-------| | 1 | CI Failing | CI status = "failure" AND gap >= threshold | 90 | | 2 | Review Debt | Unresolved threads > 0 AND gap >= 180min | 75 | | 3 | Merge Conflict | MergeableState in ["dirty", "behind"] | 80 | | 4 | Draft Limbo | Draft for 24h+ with CI passing | 40 | | 5 | Unknown | No clear cause identified | 50 |

Phase 3: Dispatch & Action

Based on classification:

• ci_failing: Spawn PM to fix CI and re-run checks
• review_debt: Spawn PM to address review threads
• merge_conflict: Spawn worker to rebase branch
• draft_limbo: Send notification to owner
• unknown: Log warning for manual investigation

Configuration

Required environment variables in .env.cairn:

PR_STALL_THRESHOLD_MINUTES=90       # No activity threshold (90 min = 3 ticks)
PR_STALL_COOLDOWN_MINUTES=30        # Cooldown between re-dispatch
PR_STALL_MAX_RETRIES=3              # Circuit-breaker threshold
PR_STALL_DRAFT_HOURS=24             # Draft age threshold
PR_STALL_DRY_RUN=false              # Log-only mode (no dispatch)

Integration

• PR Poller: Provides last_activity_at from GitHub
• PR Store: Tracks stall metadata (detected_at, classified_as, cooldown_until)
• Orchestrator: Runs as 30-minute cron job
• Recovery Agents: PM (CI/review fixes), Worker (rebase), Notification

Testing

Covered by 15+ test cases in pr_detector_test.go:

• ✅ All 5 classification modes
• ✅ Priority ordering (ci_failing > review_debt > ...)
• ✅ Edge cases: nil PR, zero timestamps, clock skew
• ✅ Score calculation validation
• ✅ 100% code coverage