holistic-repo-verification

holistic-repo-verification

MANDATORY: Use this skill before claiming any repository work is complete, before creating PRs, and before reporting that "CI is green."

Wrong skill? Pre-commit code quality → pre-commit-gate. Output verification → output-verification. Completion gate → verification-before-completion.

When to Use

• Before a major release or after large refactoring
• After merging multiple feature branches
• When CI passes but something still feels wrong
• Periodic health check on repo consistency

The Core Principle

A repository is only "green" when ALL status indicators are green.

This includes:

• CI workflow (.github/workflows/ci.yml)
• GitHub Pages deployment (pages build and deployment)
• Any other custom workflows in .github/workflows/
• GitHub Pages status via API

Never claim "CI passes" when only checking the CI workflow. That's a narrow, incomplete verification.

Verification Checklist

1. Check ALL GitHub Actions Workflows

# List all workflow runs for the repo (most recent first)
gh api /repos/{owner}/{repo}/actions/runs --jq '.workflow_runs[:10] | .[] | "\(.name): \(.conclusion) (\(.display_title))"'

Or via GitHub API:

GET /repos/{owner}/{repo}/actions/runs?per_page=10

Check for:

• CI workflow: must show conclusion: success
• pages build and deployment workflow: must show conclusion: success
• Any other workflows: must show conclusion: success

2. Check GitHub Pages Status (if repo uses Pages)

gh api /repos/{owner}/{repo}/pages --jq '.status'

Or via GitHub API:

GET /repos/{owner}/{repo}/pages

Expected: status: built (not errored or building)

3. Verify No Failing Workflow Runs

Look at the most recent run of EACH distinct workflow. All must pass.

Common Failures and Fixes

Pages "Upload artifact" Failure

Symptom: CI passes but Pages fails with tar errors about files being "removed before we read it"

Cause: Symlinks in the repository pointing to external directories that don't exist on GitHub runners

Fix: Replace symlinks with actual file copies

Pages Build Failure

Symptom: status: errored on Pages API

Cause: Various - check the workflow run logs for specific errors

Fix: Examine the failing job's logs via:

GET /repos/{owner}/{repo}/actions/runs/{run_id}/jobs

Reporting Format

When verifying repository health, report like this:

## Repository Health: {repo-name}

| Workflow | Status | Run # |
|----------|--------|-------|
| CI | ✅ success | 169 |
| pages build and deployment | ✅ success | 128 |

GitHub Pages: ✅ built

**Overall Status: GREEN** ✅

If failing: add ### Failing Workflow Details with workflow name, run #, error.

Failure Modes

Failure	Fix
Checking only most recent workflow run, not most recent of EACH workflow	List all distinct workflows, check latest run of each
Claiming "all green" while a workflow is still running	Wait for completion — "in progress" is not "success"
Only checking GitHub Actions — missing Azure DevOps pipelines	Use the appropriate CI/CD API for the repo's hosting platform
Not waiting for Pages deployment after push	Pages builds are async — poll until status is built or errored

Success Criteria

ALL workflow runs conclusion: success · GitHub Pages status: built (if applicable) · no failure/cancelled/errored.

If failing: Identify failing workflow → get specific error from job logs → fix root cause (not re-run) → wait for ALL workflows → re-check holistically.

Companion Skills

• completeness-check: Quick scope check (lighter than this)
• pre-commit-gate: Pre-commit quality gate
• verification-before-completion: Task completion verification
• output-verification: Verifying generated output
• exhaustive-audit-validation: Deep audit (this is repo-level)
• measurement-integrity: Metric integrity checks