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": "cwy",
  "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 or service-hardening findings block merge under the 0B+0I+0m gate — fix before QA-2. No backlog deferral to a later phase or sprint.
3. Final pass: PASS with final quality report and merge recommendation.

Do not treat QA as single-shot.

CI Monitoring

Preferred repo-specific flow:

• use atm gh monitor status to verify monitor health when available
• use atm gh monitor pr <PR> --start-timeout 120 to start or attach a PR monitor when available
• use atm gh pr report <PR> --json for one-shot structured status when available

Fallback when repo-specific atm gh tooling is unavailable or not yet wired:

• gh pr checks <PR> --watch
• gh pr view <PR> --json mergeStateStatus,reviewDecision

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

• Every completed QA round posts to the PR when a PR exists — QA-1, QA-2, and later. Do not keep results coordinator-only, ATM-only, or parent-only.
• Chain of evidence: each PR post must be auditable — Machine Status JSON plus human tables listing all open findings (Blocking, Important, Minor). Codex path also sends the same payload to ATM (see ATM Coordination).
• First QA pass usually posts FAIL with full findings — use --request-changes when appropriate.
• Fix-pass updates post revised status and the full remaining finding list.
• Final pass posts PASS closeout with residual risks and readiness.
• Rendered reports must include a fenced JSON Machine Status block.
• Finding tables must not omit Important or Minor rows when those findings are open — counts alone are insufficient.

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.

Chain of evidence (dual publish): when a PR exists, the completion summary sent to the coordinator (ATM in Codex; parent session in Cursor) must carry the same Machine Status JSON and finding tables as the PR comment for that qa_pass. PR-only or coordinator-only QA is invalid.

Cursor orchestration overlay (cursor-quality-mgr)

When .cursor/skills/cursor-orchestration governs the session:

• Parent spawns all reviewers; cursor-quality-mgr enforces spawn proof only.
• Spawn gate fail → next_action: parent_respawn_reviewers
• Finding fail (valid reviewer JSON, open findings) → next_action: triage_and_fix
• PASS → next_action: none

Machine Status rendered keys (PR + parent):

Key	Type	Notes
reviewer_spawn_gate	string	pass | fail
reviewer_manifest	array	{agent, task_id, spawn_actor, verdict, findings}
missing_reviewers	array	spawn-gate fail only
unparsed_reviewers	array	spawn-gate fail only
evidence_chain	object	pr_comment_url, coordinator_task_id, triage.ttl_paths

sc-compose input vars use reviewer_manifest_json and evidence_chain_json (render inputs); templates emit reviewer_manifest and evidence_chain.

Cursor $_VARS for PR posts must always populate reviewer_spawn_gate, reviewer_manifest_json (array string), and evidence_chain_json — optional template defaults are for codex-only callers.