Merge Ready

Merge Ready

Use this skill as the final gate before calling a PR/pull request ready for review, merge, or closure.

This skill coordinates existing project workflows. It does not replace:

• qa-team for outside-in scenario authoring and execution
• quality-audit for iterative SEEK -> VALIDATE -> FIX review
• default-workflow for substantive fixes discovered while making the PR/pull request merge-ready

Use pr-description-template.md to update the PR/pull request description with the required evidence.

Platform scope

The top-level merge-readiness contract is platform-neutral. Use platform-specific commands and terminology only inside the matching platform path:

• GitHub: GitHub pull requests, GitHub Actions, gh, GitHub issues, review conversations, and branch protection.
• Azure DevOps/AzDO: Azure DevOps, AzDO, Azure Repos pull requests, Azure Pipelines, az repos, az pipelines, Azure Boards work items, PR threads, and branch policies.

When the platform cannot be detected, inspect the repository remote, PR URL, or available CLI context first. If the platform still cannot be proven, report NOT_MERGE_READY with a platform-access blocker instead of assuming GitHub behavior.

Platform detection signals:

• GitHub: github.com remotes or PR URLs, gh repo view, gh pr status, or hosting metadata that identifies a GitHub repository.
• Azure DevOps/AzDO: dev.azure.com or *.visualstudio.com remotes or PR URLs, Azure Repos remote paths, az repos pr show, or hosting metadata that identifies an Azure DevOps project/repository.

Required outcome

A PR/pull request is merge-ready only when all of the following are true:

1. qa-team scenarios were written or updated, validated with gadugi-test validate, and actually run with gadugi-test run.
2. User-facing docs were updated when the change affects APIs, configuration, deployment, CLI behavior, or other external surfaces.
3. quality-audit completed at least 3 SEEK -> VALIDATE -> FIX cycles, continued past 3 if critical or high findings remained, and ended on a clean final cycle.
4. Checks/build validation for the current head revision passed according to the active platform and repository policy.
5. PR/pull request metadata is complete and reviewable.
6. Required reviews/approvals are satisfied, with no outstanding requested changes.
7. Merge conflicts are absent.
8. Required policies/protection rules are satisfied.
9. Required linked work items/issues are present or explicitly not applicable under project policy.
10. Required comments/threads are resolved or explicitly acknowledged as non-blocking.
11. Final merge/close verification is documented for the intended outcome, and, if a merge or close action was performed, the platform state confirms it.
12. The PR/pull request description contains concrete evidence for all other criteria, including scope.
13. The diff contains no unrelated changes.

If any criterion is missing, stale, inaccessible, or blocked by external approval, check, or policy state, the PR/pull request is not merge-ready.

Non-negotiable guardrails

• Do not treat "scenario YAML exists" as sufficient. The scenarios must be validated and run.
• Do not claim docs are irrelevant without checking the changed surfaces.
• Do not accept fewer than 3 quality-audit cycles.
• Do not accept a quality-audit result unless the final cycle is clean.
• Do not accept pending, failing, cancelled, stale, or unavailable checks/build validation.
• Do not mark a PR/pull request merge-ready until the description itself is updated with evidence.
• Do not bypass policies/protection rules, required checks, required approvals, or required linked work item rules.
• Do not silently ignore blockers such as missing environment access, missing PR/pull request access, missing test tooling, missing CLI authentication, or missing platform permissions. Report them explicitly.

Workflow

1. Establish PR/pull request context

Identify the target PR/pull request from $ARGUMENTS if provided; otherwise use the current branch's PR/pull request.

Gather:

• platform and repository/project identity
• PR/pull request ID, URL, title, source branch, target branch, and current description
• changed files and current diff scope
• whether the change touches external or user-facing surfaces
• current checks/build validation status for the current head revision
• metadata, reviews/approvals, mergeability, policies/protection, linked work items/issues, and comments/threads

GitHub path

Use GitHub-specific commands only when the PR is a GitHub pull request.

gh pr view "$PR" --json number,url,title,body,headRefName,baseRefName,mergeStateStatus,mergeable,reviewDecision,isDraft,closingIssuesReferences
gh pr diff "$PR" --name-only
gh pr checks "$PR"
git diff --name-only "origin/$(gh pr view "$PR" --json baseRefName --jq .baseRefName)"...HEAD

For unresolved review conversations or branch protection details, use gh pr view, gh api, the GitHub UI, or authorized repository settings evidence. Record the exact source used.

Azure DevOps/AzDO path

Use AzDO-specific commands only when the PR is an Azure Repos pull request.

az repos pr show --id "$PR_ID" --output json
az repos pr policy list --id "$PR_ID" --output table
az repos pr work-item list --id "$PR_ID" --output table
az repos pr reviewer list --id "$PR_ID" --output table
az repos pr show --id "$PR_ID" --query "{source:sourceRefName,target:targetRefName,mergeStatus:mergeStatus,status:status,title:title}" --output json

For PR threads or build validation details that are not exposed by the installed CLI version, use the Azure DevOps UI or authorized REST API evidence. Record the exact source used.

If no PR/pull request exists yet, you may still prepare evidence, but the final verdict must remain blocked until the PR/pull request exists and platform checks/build validation status is available.

2. Satisfy the QA criterion with qa-team

Invoke qa-team and ensure it covers the changed behavior from an external user perspective.

Required deliverables:

• scenario file path(s)
• proof that gadugi-test validate succeeded
• proof that gadugi-test run succeeded
• target environment used for the run (local or deployed)
• evidence location or execution output summary

Minimum commands:

gadugi-test validate path/to/scenario.yaml
gadugi-test run path/to/scenario.yaml

If the environment needed to run the scenario does not exist, stop and report a blocker. Do not downgrade this to "definition only".

3. Satisfy the docs criterion

Inspect the changed files and decide whether the PR/pull request changes any user-facing surface:

• APIs
• configuration
• deployment or operations flow
• CLI or TUI behavior
• user-visible workflows

If yes, update the corresponding docs and add links to those docs in the PR/pull request description.

If no, list the changed surfaces you checked and explain why each is internal-only. For example: "Changed surfaces reviewed: rust_runner.py, smart-orchestrator.yaml -- both are internal orchestration plumbing with no CLI/API/config impact."

4. Satisfy the quality-audit criterion

Invoke quality-audit and require the full iterative loop:

• minimum 3 cycles
• each cycle is SEEK -> VALIDATE (multi-agent consensus) -> FIX
• continue past 3 cycles if critical or high findings remain
• final cycle must be clean: zero critical or high findings, and zero medium findings that pose correctness or security risks

Every fix uncovered during this audit must follow default-workflow. If the audit finds issues that require code or docs changes, switch to default-workflow for those fixes, complete the work, then return to this skill and resume verification.

Capture in the PR/pull request description:

• cycle count
• confirmed findings per cycle
• fixes applied
• convergence summary
• explicit statement that the final cycle was clean (zero critical/high findings, zero medium correctness/security findings)

5. Verify platform merge-readiness aspects

Collect explicit evidence for every aspect below before declaring MERGE_READY.

6. Enforce scope

Review the diff and confirm the PR/pull request is focused on the intended change. If unrelated changes are present, report them as blockers and do not mark the PR/pull request ready.

Platform-neutral evidence is enough for scope when it names the source and target branches and lists changed files. Use the platform diff, local Git diff, or both.

7. Update the PR/pull request description

This step must not be performed until steps 2-6 have all completed and evidence has been collected. Do not update the description with placeholder or anticipated evidence.

Use pr-description-template.md and replace every placeholder with actual evidence. Keep the wording concise, but make the evidence concrete enough that a reviewer can verify the work without guessing.

If the description already has useful sections, merge the evidence into the existing structure instead of duplicating headings.

GitHub path

gh pr edit "$PR" --body-file pr-description.md

Azure DevOps/AzDO path

az repos pr update --id "$PR_ID" --description "$(cat pr-description.md)"

If the platform CLI cannot update the description safely, update it through the authorized UI/API and record that evidence source.

8. Return a binary verdict

End with one of these outcomes:

• MERGE_READY: every criterion passed, required evidence was added to the PR/pull request description, and no platform blocker remains
• NOT_MERGE_READY: one or more blockers remain

Use this format:

Verdict: MERGE_READY | NOT_MERGE_READY

Platform: GitHub | Azure DevOps/AzDO | unknown

Criteria:

- QA-team: pass | fail
- Docs: pass | fail | not-applicable
- Quality-audit: pass | fail
- Checks/build validation: pass | fail
- Metadata: pass | fail
- Reviews/approvals: pass | fail
- Merge conflicts: pass | fail
- Policies/protection: pass | fail
- Linked work items/issues: pass | fail | not-applicable
- Comments/threads: pass | fail | not-applicable
- Final merge/close verification: pass | fail | not-performed
- Scope: pass | fail
- Description evidence: pass | fail

Blockers:

- <concrete missing item or `none`>

When to stop and hand back a blocker

Stop and report NOT_MERGE_READY when any of these are true:

• no runnable environment exists for the required gadugi scenario
• the PR/pull request or checks/build validation status cannot be accessed
• platform access or authentication cannot prove required metadata, reviews/approvals, mergeability, policies/protection, linked work items/issues, comments/threads, or final state
• quality-audit has not converged to a clean final cycle
• docs changes are needed but not yet written
• checks/build validation is pending, failing, cancelled, stale, skipped without policy support, or unavailable
• required reviews/approvals, linked work items/issues, comments/threads, or policies/protection remain unsatisfied
• merge conflicts are present or mergeability cannot be determined
• final merge/close action is blocked by permissions, external approval, required waiting period, or platform policy
• the diff contains unrelated changes

Do not substitute promises or TODOs for evidence.