Teach review agents to validate workflow and action changes explicitly

[coisa]

Problem

Workflow and GitHub Action changes are high-risk because many failures only appear after the workflow is merged or after a bot-authored commit exercises the automation path. In PR #237, review found that the predictable-conflict workflow could push a branch update with GITHUB_TOKEN without dispatching required tests for the new commit. That is the same class of issue we previously hit with wiki pointer commits.

We need the review workflow, review skill, and/or a dedicated validation skill to make this kind of workflow validation explicit instead of relying on ad hoc reviewer memory.

Proposal

Add guidance and, where useful, a dedicated workflow-validation skill/checklist for PRs that modify:

• .github/workflows/**
• .github/actions/**
• resources/github-actions/**
• workflow-related docs that describe permissions, dispatching, branch protection, sync behavior, or release automation

The guidance should require reviewers/agents to design an executable validation strategy for the changed automation, even when GitHub cannot run the exact new workflow until after merge.

Expected Behavior

When a PR changes workflow automation, the review agent should ask and answer questions such as:

• Does this workflow push commits with GITHUB_TOKEN?
• If yes, do required checks run or get mirrored for the bot-authored commit?
• Are required permissions declared both in the reusable workflow and the consumer wrapper?
• Are local composite action paths available from the repository/ref used by the workflow?
• Does the workflow work for same-repository PRs, fork PRs, push events, manual dispatch, and workflow_call where applicable?
• Can the script be exercised with a local harness, fake gh, fake git, or a temporary repository?
• If a true GitHub run is required, should we open a temporary validation PR/branch and close it after recording evidence?

Suggested Implementation Strategy

Start by updating the existing pull-request-review skill and review-guardian agent because they already own rigorous PR review. If the checklist becomes large enough, split it into a dedicated github-actions-validation skill later.

Recommended additions:

1. Add a workflow-change review block to pull-request-review.
2. Teach review-guardian to treat workflow/action/script changes as requiring executable validation notes.
3. Add examples for validation harnesses, such as:
   • bash -n for shell scripts;
   • YAML parsing or actionlint when available;
   • fake gh/git wrappers for local action scripts;
   • temporary repositories for merge/conflict behavior;
   • explicit GitHub validation PRs when local simulation cannot cover the behavior.
4. Require the PR body or review comment to record the validation strategy and result.
5. Add a rule that bot-authored commits pushed by workflows must dispatch or mirror required checks when branch protection depends on them.

Requirements

• Workflow/action PR reviews MUST include an explicit validation strategy.
• The review process MUST call out bot-authored commit side effects, especially required checks not running after GITHUB_TOKEN pushes.
• The guidance MUST cover both reusable workflows and packaged consumer wrappers.
• The guidance MUST explain when local simulation is sufficient and when a temporary validation PR is warranted.
• The guidance MUST avoid requiring noisy temporary PRs for every workflow change when deterministic local validation is enough.

Non-goals

• Building a full workflow emulator.
• Replacing GitHub Actions CI with local-only validation.
• Requiring every documentation-only workflow note to open a temporary PR.

Acceptance Criteria

Functional Criteria

• pull-request-review or a new dedicated skill includes a workflow/action validation checklist.
• review-guardian references the checklist for PRs touching .github/workflows, .github/actions, or resources/github-actions.
• The checklist explicitly covers GITHUB_TOKEN push side effects and required-check dispatch/mirroring.
• The checklist includes examples of local harness validation and temporary validation PR usage.
• The PR review contract asks reviewers to record validation evidence or residual workflow risk.

Regression Criteria

• Add or update tests/docs for the skill content if the repository has a validation path for packaged skills/agents.
• Run the appropriate docs/style checks after updating the skill/agent content.