Qv Devops Why My Pr Not

devops-why-my-pr-not

Self-service triage for the two most common DevOps support questions:

1. "Why aren't my CI checks running?" — use the canonical CI label and gate docs below; they define which labels, trust rules, and fork restrictions control job execution.
2. "Why can't I merge?" — use the current approval workflow, CODEOWNERS, and branch-protection state; they define required approvals and merge conditions.

The skill cross-references the live PR state (via gh) against the canonical repo docs that describe the rules:

• docs/ci/LABELS.md — every CI-relevant label, fork-ci environment, fork-approval, and what each gates.
• docs/ci/TEAMS.md — the four teams + the two pods (DevOps, SDK).
• .github/CODEOWNERS — merge-approval routing.
• .github/workflows/check-approvals.yml — current approval check and minimum approval configuration.
• .github/teams/devops.json, .github/teams/sdk.json — pod leads + members.

The docs are the source of truth. The skill quotes them; it does not re-derive their rules.

When to use this skill

Use when:

• A developer asks "why aren't my checks running on PR #N?"
• A developer asks "why can't I merge PR #N?" / "what's blocking my PR?"
• A reviewer asks "what does this PR still need before I can merge it?"
• User invokes /qv-devops-why-my-pr-not <PR URL>

Do NOT use when:

• Reviewing a PR for correctness — use /qv-devops-pr-review or /qv-pr-review.
• Generating a PR description — use /qv-devops-pr-create or /qv-sdk-pr-create.
• Listing all open PRs in the pod — use /qv-devops-pr-status or /qv-sdk-pr-status.

Inputs

• Required: PR URL or <owner>/<repo>#<num> shorthand (defaults owner/repo to tetherto/qvac if only #<num> is given).
• Optional: focus hint — --ci, --merge, or --both (default --both).

If the PR identifier is missing, ask once. Nothing else to ask up-front.

Prerequisites

• gh CLI installed and authenticated (gh auth status). The token needs repo scope to read PR metadata, checks, and reviews on tetherto/qvac.
• read:org is not required by the skill itself. If privileged fork jobs fail while recording qvac/fork-verified, check fork-approval logs — the gate job uses github.token with statuses: write (not PAT_TOKEN).

The skill does not require a checked-out worktree. All inspection is via gh.

Safety rules

This skill follows the repository working agreement: read-only by default, with each remote mutation requiring explicit user authorization.

• Read-only with respect to the user's local working tree. No git switch, git checkout, git reset, git restore, git stash, git pull, git merge, git rebase, git cherry-pick, git clean, gh pr checkout, or any write inside the user's working tree.
• Read-only with respect to the PR's GitHub state by default. No gh pr edit, no gh api ... -X POST/PATCH/PUT/DELETE, no gh pr comment, no gh pr review without explicit user confirmation per call.
• Mutations are plan-then-apply. When the diagnosis suggests a fix that the user could perform (apply a label, post /review, request re-review from a teammate, rebase to drop a merge conflict), print the exact gh command, wait for the user to type "yes" / "go" / "apply", then execute. A blanket "do everything" is not accepted — confirm per command.
• Never approve the fork-ci environment on the user's behalf. That gate is intentionally not self-service. The skill may suggest who to ask (merge/release team), never click approve for them.

Efficiency rules

Cap at 6 shell calls for a normal diagnosis. Cache fetched data once per invocation under /tmp/why-pr-<num>-<short-sha>.json so repeat queries within the same session do not re-hit GitHub.

If a single call covers multiple needs (e.g. gh pr view --json already lists labels and reviews), do not re-fetch.

Workflow

1. Parse and validate the PR identifier

Accept any of:

• https://github.com/tetherto/qvac/pull/12345
• tetherto/qvac#12345
• #12345 → resolves to tetherto/qvac#12345
• bare 12345 → resolves to tetherto/qvac#12345

Extract <owner>, <repo>, <num>. Reject if any are missing. Print the resolved canonical URL.

2. Read the canonical docs (once per session, cached)

Before fetching the PR, ensure you've read these in this turn (or already have them in context):

• docs/ci/LABELS.md
• docs/ci/TEAMS.md

These are short. Read them in full. Quote them in findings, do not paraphrase from memory — the rules drift over time and the doc is authoritative.

Read check-approvals.yml when an approval finding is triggered rather than relying on remembered thresholds.

For pod ownership, read .github/teams/devops.json / .github/teams/sdk.json on demand when computing "who can approve fork-ci" or "who is in your CODEOWNERS path."

3. Fetch live PR state

Single call:

gh pr view <num> -R <owner>/<repo> --json number,title,state,isDraft,labels,author,baseRefName,headRefName,headRefOid,headRepositoryOwner,headRepository,mergeable,mergeStateStatus,reviewDecision,reviews,statusCheckRollup,latestReviews,files

Cache the JSON to /tmp/why-pr-<num>-<short-sha>.json. Pull headRefOid for any subsequent commits/<sha>/... calls.

Then fetch checks (one call):

gh pr checks <num> -R <owner>/<repo> --json name,state,conclusion,workflow,link

If a required commit status is not represented in the check rollup, use one more call:

gh api "repos/<owner>/<repo>/commits/<headRefOid>/status"

4. Run the CI-not-running diagnosis (--ci / --both)

Walk down this checklist in order. Stop at the first match per dimension; print all matches across the checklist.

For each match, print what the rule says (one short quote pulled from the cite) plus what the user should do (a single concrete action).

5. Run the merge-blocked diagnosis (--merge / --both)

Walk this checklist in order, same rule: stop at first match per dimension, print all matches.

When suggesting reviewers, use current CODEOWNERS and team files for the touched paths. Do not infer reviewers from an obsolete tier model.

6. Render the report

Print one consolidated report. Two top-level sections (omit a section if the user asked for a single dimension).

PR: <owner>/<repo>#<num> — <title>
Author: @<login>   Base: <baseRefName>   Head: <headRefName>@<short-sha>
State: <state> | Draft: <isDraft> | Mergeable: <mergeable>/<mergeStateStatus> | Review: <reviewDecision>
Labels: <comma-separated>

── CI: are checks running? ──────────────────────────────────────────
[<symbol>] <C#> <one-line summary>
   Rule:    <one-line quote from cited doc>
   Action:  <one concrete next step>
   Cite:    <relative link>

[<symbol>] <C#> ...

(or "✓ All expected checks are running.")

── Merge: can it land? ───────────────────────────────────────────────
[<symbol>] <M#> <one-line summary>
   Rule:    <one-line quote from cited doc>
   Action:  <one concrete next step>
   Cite:    <relative link>

[<symbol>] <M#> ...

(or "✓ All merge requirements satisfied.")

── Suggested next actions ───────────────────────────────────────────
1. <concrete action> — <user-friendly description>
2. ...

Use simple symbols: [!] for blocking, [~] for soft (e.g. waiting), [i] for informational, [✓] for satisfied. No emojis (per repo convention).

7. Plan-then-apply mutations (only if user opts in)

The skill MAY propose at most one mutation per finding. Each proposal prints the exact command and waits for explicit confirmation. Examples:

• Apply safe-to-test (only after the user confirms they have audited the fork's diff):

  gh pr edit <num> -R <owner>/<repo> --add-label safe-to-test
  

• Re-trigger approval bot:

  gh pr comment <num> -R <owner>/<repo> --body "/review"
  

• Request re-review from a specific approver:

  gh api -X POST repos/<owner>/<repo>/pulls/<num>/requested_reviewers \
    -f reviewers='["<login>"]'
  

• Mark draft PR as ready for review:

  gh pr ready <num> -R <owner>/<repo>
  

Never propose approving the fork-ci environment on the user's own PR. If privileged fork jobs are waiting, the suggestion is "ask a merge/release-team member to approve the pending fork-ci deployment" — not "I'll approve it for you."

After any mutation, re-run step 3 (single gh pr view) and re-render only the section(s) that changed. Print one verification line: Verified: <label X> now present | reviewers <Y, Z> requested | etc.

8. Stop conditions (fail-stop)

Stop and report (do not guess) when:

• gh auth status reports unauthenticated → tell the user to run gh auth login.
• The PR JSON returns 404 → wrong number / wrong repo / private repo.
• The skill needs to read branch protection but the user lacks permission (HTTP 403) → state the limitation; the merge-blocked diagnosis falls back to "what we can see from PR state alone".
• The diagnosis returns zero findings AND the user clearly believes something is broken → say so; offer to dump the raw PR JSON for the user to inspect.

Quality checklist

Before printing the final report, verify:

• Each finding cites a real rule from docs/ci/LABELS.md, docs/ci/TEAMS.md, approval-check-worker.yml, or CODEOWNERS — not from memory.
• Each finding has both a "Rule" (one-line quote) and an "Action" (one concrete step).
• Suggested approvers come from current CODEOWNERS and team configuration, not memory.
• No mutation has been executed without an explicit per-command confirmation.
• fork-ci approval was never proposed for self-application.
• Total gh shell calls ≤ 6 for a read-only diagnosis (≤ 8 if a mutation + verification was performed).

References

• Label catalogue: docs/ci/LABELS.md
• Team catalogue: docs/ci/TEAMS.md
• Fork CI trust model: docs/ci/LABELS.md (fork-ci, fork-approval, qvac/fork-verified)
• Approval check: .github/workflows/check-approvals.yml
• Merge-routing: .github/CODEOWNERS
• DevOps pod metadata: .github/teams/devops.json
• SDK pod metadata: .github/teams/sdk.json
• Repository working agreement (mutation policy): AGENTS.md
• Generic PR review skill: .agents/skills/qv-pr-review/SKILL.md
• DevOps PR review skill: .agents/skills/qv-devops-pr-review/SKILL.md