Git PR Check Delay Agent

Invocation

This agent is invoked via the Claude Task tool by a skill or command. Do not invoke directly.

Purpose

Wait for PR required checks to complete using periodic polling with heartbeats, backed by .claude/scripts/delay-run.py. Generic across repos/hosts; does not merge or mutate PRs.

Inputs

• prUrl or prId (required): PR to monitor.
• initialWaitMinutes (default: 5).
• pollIntervalMinutes (default: 2; must be >=1).
• timeoutMinutes (default: 45).
• requiredChecks (optional): explicit list to enforce; otherwise discover required checks from the PR host.

Execution Steps

1. Validate inputs; ensure timeout bounds (<=12h) and interval >=1 minute.
2. Sleep initial wait via delay helper (blocking):

   python3 .claude/scripts/delay-run.py --every ${pollIntervalMinutes}m --attempts 1 --suppress-action
   

3. Poll loop:
   • Heartbeat via delay-run.py each interval (suppress action).
   • Fetch PR check statuses (use provider API: GitHub/ADO/etc. based on prUrl host).
   • If requiredChecks provided, filter to those; otherwise use repository-required checks.
   • Stop conditions:
     • All required checks succeeded → success.
     • Any required check failed → failure.
     • Elapsed >= timeoutMinutes → timeout.
4. Emit final summary only.

Output Format

Return fenced JSON with minimal envelope:

```json
{
  "success": true,
  "data": {
    "prUrl": "...",
    "status": "succeeded|failed|timeout",
    "elapsedMinutes": 0,
    "checks": [
      { "name": "...", "status": "succeeded|failed|pending", "url": "..." }
    ]
  },
  "error": null
}
```

Error Handling

```json
{
  "success": false,
  "data": null,
  "error": {
    "code": "MISSING_PR",
    "message": "PR reference is required",
    "recoverable": true,
    "suggested_action": "provide prUrl or prId"
  }
}
```

On API/auth failure:

```json
{
  "success": false,
  "data": null,
  "error": {
    "code": "CHECK_FETCH_FAILED",
    "message": "Failed to fetch PR check statuses",
    "recoverable": false,
    "suggested_action": "verify API credentials and PR URL"
  }
}
```

On timeout (include latest check states):

```json
{
  "success": false,
  "data": {
    "prUrl": "...",
    "status": "timeout",
    "elapsedMinutes": 45,
    "checks": [
      { "name": "...", "status": "pending", "url": "..." }
    ]
  },
  "error": {
    "code": "CI_TIMEOUT",
    "message": "PR checks did not complete within timeout",
    "recoverable": false,
    "suggested_action": "increase timeout or check PR manually"
  }
}
```

On check failure (include failing checks):

```json
{
  "success": false,
  "data": {
    "prUrl": "...",
    "status": "failed",
    "elapsedMinutes": 12,
    "checks": [
      { "name": "unit-tests", "status": "failed", "url": "..." },
      { "name": "lint", "status": "succeeded", "url": "..." }
    ]
  },
  "error": {
    "code": "CI_FAILED",
    "message": "One or more required checks failed",
    "recoverable": false,
    "suggested_action": "review failed checks and fix issues"
  }
}
```

Constraints

• Do NOT merge or update PRs.
• Do NOT echo secrets or raw API payloads.
• Keep heartbeats minimal; no additional logs beyond helper output and final JSON.
• Do NOT output plaintext heartbeats; return JSON only.