Harden cicd-diagnostics skill scripts with preflight checks and error handling

Summary

The cicd-diagnostics skill scripts fail with cryptic subprocess errors when local prerequisites are missing, misdiagnose failures by not distinguishing continue-on-error steps from job-killing failures, and require numerous permission patterns due to the agent orchestrating individual script calls.

Changes

utils/github_api.py — Error handling and preflight

• Add DiagnosticError exception class replacing cryptic subprocess failures with actionable error messages
• Add preflight_check() function validating Python 3.8+, gh CLI installed, gh authenticated, and running from a dotCMS/core checkout
• Add _run_gh() wrapper that detects auth failures, rate limits, and 404s with clear resolution guidance

diagnose.py — New single entry point (key addition)

• Single command gathers all evidence: preflight, metadata, jobs, annotations, logs, error extraction
• Progressive subcommands: --metadata, --jobs, --annotations, --logs [JOB_ID], --evidence [JOB_ID]
• Eliminates need for agents to orchestrate individual scripts, set variables, or chain commands
• One permission pattern covers everything: Bash(python3 .claude/skills/cicd-diagnostics/*)

fetch-jobs.py — Step-level continue-on-error detection

• Shows ALL jobs with status (not just failed jobs) — eliminates ad-hoc JSON parsing
• Step-level detail for failed jobs with continue-on-error detection
• Correctly excludes GitHub Actions cleanup steps (Post ..., Complete job) from the heuristic
• Labels steps: FAIL <- likely caused job failure vs FAIL (continue-on-error — did NOT cause job failure)
• Notes masked errors as real issues worth investigating separately

SKILL.md — Rewritten for accuracy

• Triage-first approach: check known issues before deep investigation
• diagnose.py as primary tool with progressive subcommands documented
• Explicit guidance against ad-hoc python3 -c and redundant gh commands
• continue-on-error analysis: how to distinguish masked errors from job-killing failures
• Diagnosis report writes to workspace directory, not project root

WORKFLOWS.md — Trunk deployment documentation

• Documents all deployment steps with continue-on-error flags
• Artifact-run-id propagation chain for build reuse scenarios
• Documents the diagnostic trap: CLI Deploy errors visible in logs but masked by continue-on-error

.claude/settings.json — Permissions

• Add python3 .claude/skills/cicd-diagnostics/* permission for diagnostic scripts
• Add gh auth status, gh repo view, python3 --version, ls for preflight

Improved error extraction in diagnose.py

• Catches npm error, npm ERR!, FATAL:, BUILD FAILURE in addition to ##[error] lines
• Previously only ##[error] was extracted, missing npm 403 errors that were the actual failure cause

Root cause of the misdiagnosis

The original skill diagnosed a trunk deployment failure (run 23469253088) as a maven-repo artifact issue in the CLI Deploy step. The actual failure was:

1. CLI Deploy (deploy-jfrog) has continue-on-error: true — its maven-repo error was visible in logs but could NOT fail the job
2. SDKs Publish was the step that actually failed the job — with npm error 403 Forbidden (version 1.2.5-next.1 already published)
3. The skill latched onto the first ##[error] it found without checking whether the step had continue-on-error

Test plan

• Run diagnose.py 23469253088 from a dotCMS/core checkout — should show SDKs Publish as primary failure, maven-repo as secondary
• Run diagnose.py 23469253088 --jobs — should show step-level detail with FAIL <- likely caused job failure on Step 11
• Run diagnose.py 23469253088 --logs 68289775927 — should show npm 403 errors alongside ##[error] lines
• Verify preflight fails gracefully outside a dotCMS/core checkout
• Verify only Bash(python3 .claude/skills/cicd-diagnostics/*) permission is needed for full diagnosis

🤖 Generated with Claude Code

Start with .claude/skills/cicd-diagnostics/utils/github_api.py and diagnose.py, then read fetch-jobs.py, SKILL.md, and WORKFLOWS.md to understand the diagnostic flow and failure classification. Run the listed commands for workflow 23469253088 and verify preflight errors, step-level continue-on-error labels, npm error extraction, workspace reporting, and the documented permission pattern.