quality-management-gh

name	quality-management-gh
version	1.0.0
description	Reusable QA orchestration skill for GitHub PRs. Use for multi-pass QA, CI monitoring, and template-driven findings and final quality reports.

Quality Management (GitHub)

This skill defines a reusable quality-management workflow for teams that run QA across one or more passes before merge.

Scope

Use this skill when you need to:

• run QA in multiple passes (IN-FLIGHT, FAIL, PASS)
• monitor CI progression for a PR
• publish structured findings to PR plus ATM
• publish a final QA closeout report on PASS

This skill is intentionally generic. Team-specific teammate names, branch policy, and background-agent ownership stay in the repo’s quality-mgr agent prompt.

Required QA Status Contract

Every QA update, both ATM and PR, must include:

• sprint or task identifier
• branch, commit, PR number
• verdict (PASS | FAIL | IN-FLIGHT)
• deliverable completion (complete, total, percent)
• finding counts by severity (blocking, important, minor)
• blocking ids with concise summaries
• next required action plus owner
• merge readiness (ready | not ready) plus reason

Use fenced JSON for machine-readable status payloads:

{
  "sprint": "M.1",
  "task": "mailbox-locking",
  "branch": "feature/pM-s1-mailbox-locking",
  "commit": "abc1234",
  "pr": 123,
  "verdict": "FAIL",
  "deliverables": {
    "complete": 9,
    "total": 11,
    "percent": 82
  },
  "findings": {
    "blocking": 1,
    "important": 2,
    "minor": 0
  },
  "blocking_ids": ["QA-001"],
  "next_action": "Fix lock acquisition rollback semantics",
  "owner": "comp",
  "merge_readiness": "not ready",
  "merge_reason": "Blocking findings remain"
}

QA Lifecycle (Multi-Pass)

1. Initial pass: usually FAIL with findings.
   • If Rust best-practices review is in scope, run it in QA-1 only.
2. Fix passes: IN-FLIGHT or FAIL while fixes are in progress.
   • QA-2 and later rounds must not re-run Rust best-practices review on the same sprint branch.
   • Unresolved QA-1 RBP findings that are not fixed in the first fix round carry to the next phase backlog instead of being re-raised in later rounds.
3. Final pass: PASS with final quality report and merge recommendation.

Do not treat QA as single-shot.

CI Monitoring

Standard GitHub CLI (preferred, authoritative):

• gh run list --limit 1 --workflow <workflow> --json for workflow status
• gh run watch --exit-status <run-id> for run monitoring
• gh pr checks <PR> --watch for check suite monitoring
• gh pr view <PR> --json mergeStateStatus,reviewDecision,statusCheckRollup for one-shot structured status

Use the standard gh pr / gh run commands directly; no custom wrapper is required.

If monitoring cannot start, include the failure in QA status and proceed with one-shot PR report data.

Findings Report to PR (Blocking)

Template:

• .claude/skills/quality-management-gh/findings-report.md.j2

Recommended flow:

1. Gather findings from QA agents.
2. Render markdown from the template with required variables.
3. When rechecking prior findings, include a resolved-findings section for items closed since the previous pass.
4. Post to the PR as a blocking review or status comment.

Suggested commands:

• blocking review: sc-compose render --root .claude/skills/quality-management-gh --file findings-report.md.j2 --var-file <vars.json> | gh pr review <PR> --request-changes --body-file -
• in-flight update: sc-compose render --root .claude/skills/quality-management-gh --file findings-report.md.j2 --var-file <vars.json> | gh pr comment <PR> --body-file -

Fallback when render fails:

• post plain markdown preserving the same machine-status fields

<vars.json> must be a flat JSON map of strings for sc-compose. Use raw JSON strings for array-valued machine-status fields, for example:

• blocking_ids_json: "[\"QA-001\"]"

Use numeric strings for count fields so the templates can render them as JSON numbers without quotes.

Final Quality Report to PR (Closeout)

Template:

• .claude/skills/quality-management-gh/quality-report.md.j2

Recommended flow:

1. Confirm final QA pass and summarize validation scope.
2. Render markdown from the template with required variables.
3. Post as final closeout review or comment.

Suggested command:

• sc-compose render --root .claude/skills/quality-management-gh --file quality-report.md.j2 --var-file <vars.json> | gh pr review <PR> --approve --body-file -

Use the final template only for PASS closeout.

PR Update Conventions

• First QA pass posts detailed findings with FAIL and should use --request-changes.
• Fix-pass updates revise status and open findings.
• Final pass posts PASS closeout with residual risk and readiness and should use --approve.
• Do not keep QA results ATM-only when a PR exists; append every completed QA update to the PR.
• Rendered reports must include a fenced JSON block for machine parsing.

ATM Coordination Protocol

For each task:

1. immediate acknowledgement
2. execute QA work
3. send completion or status summary
4. receiver acknowledgement

No silent processing.