gh-address-review-threads

name

gh-address-review-threads

description

Inspect unresolved GitHub PR review threads on the open pull request for the current branch, decide whether to accept, reject, defer, or defer outdated threads, post acknowledgement and completion replies with gh CLI, apply accepted fixes, and resolve completed threads. Use when Codex needs to read open PR review threads, summarize the planned direction or rejection, perform the work, then post a completion reply and resolve the finished threads.

Address Review Threads

Use this skill to handle unresolved GitHub PR review threads on the current branch with a manifest-gated collect -> build -> validate -> apply workflow.

Use When

• an open PR for the current branch has unresolved review threads
• final thread decisions, final reply wording, pushes, and resolution stay local
• mini workers are used only for narrow packet analysis or small isolated fixes

Execution Roots

• <skill-dir>: directory containing this SKILL.md
• <python-bin>: concrete interpreter path; on Windows prefer a non-WindowsApps Python
• <runtime-root>: <repo-root>/.codex/tmp/packet-workflow/gh-address-review-threads/<run-id>/
• <manifest-json>: <runtime-root>/manifest.json
• <eval-log-json>: <repo-root>/.codex/tmp/evaluation_logs/gh-address-review-threads/<run-id>.json

Entry

1. Run gh auth status; stop if authentication is missing.
2. Collect the pre-push snapshot with <python-bin> -B <skill-dir>/scripts/collect_review_threads.py --repo <repo-root> --output <pre-context-json>.
3. Create the run manifest with <python-bin> -B <skill-dir>/scripts/manage_review_thread_run.py start --repo-root <repo-root> --context <pre-context-json>.
4. Build pre-push packets with <python-bin> -B <skill-dir>/scripts/build_review_packets.py --context <manifest.pre.context> --repo-root <repo-root> --output-dir <manifest.pre.packet_dir> --result-output <manifest.pre.build_result>.
5. Initialize the evaluation log, then merge the pre-push build result with write_evaluation_log.py phase --phase build --phase-label pre.
6. Read the active phase orchestrator.json first, then global_packet.json, then the relevant thread-batch or thread packet.
7. Draft the raw ack plan locally, validate it, and record it with record-plan --phase ack.
8. Apply the normalized ack plan, write <manifest.ack.result>, and record the live apply result with record-apply --phase ack --result <manifest.ack.result>.
9. After real validation runs for accepted work, record the commands with record-validation.
10. After the accepted work is pushed, run post-push, rebuild post-push packets with --previous-context and --reconciliation-input, seed the complete plan with reconcile_outdated_threads.py --reconciliation-input <manifest.post.reconciliation_input>, validate it, record it with record-plan --phase complete, then apply and record complete.
11. Merge phase results as each phase completes; when build runs twice, use --phase-label pre and --phase-label post so evaluation metrics do not overwrite each other. After the last apply result, write <manifest.evaluation.final> with the local final observations and run <python-bin> -B <skill-dir>/scripts/write_evaluation_log.py finalize --log <eval-log-json> --final <manifest.evaluation.final>.

Continue Only If

• manage_review_thread_run.py allows the next transition.
• ack is posted and recorded as ack-applied before validation recording, post-push staging, or further accepted-thread work.
• the run-start git worktree snapshot still matches before ack-applied; record-plan --phase ack and record-apply --phase ack stop on pre-ack drift
• ack_mode=skip is used only to preserve an already-correct exact managed ack reply for that thread.
• ack_mode=add and ack_mode=update keep an explicit decision line in ack_body that matches the planned decision.
• adoptable unmarked replies may be used as update fallback targets, but they are never enough to justify ack_mode=skip.
• record-apply sees apply_succeeded=true, fingerprint_match=true, and a non-dry-run result for live runs.
• apply_thread_action_plan.py consumes only normalized validator output.
• packet_worker_map is the runtime routing authority.
• packet_sizing.json and build-result.json spawn_plan_preview stay evaluation-side only.
• manifest state.accepted_threads is the run-local ack-applied accepted set, while post-push accepted provenance lives in reconciliation-input.json.
• same-run accepted non-outdated auto-resolve uses post-push HEAD delta evidence from the manifest reconciliation input, not the full PR base-to-head diff.
• same-run outdated auto-resolve has accepted-before-push provenance, current-HEAD evidence, and real validation evidence.
• broad or cross-cutting fixes stay local even when delegation is allowed for narrow analysis.

Stop When

• gh auth is missing, there is no open PR, or a reply target is missing
• the manifest gate rejects record-plan, record-apply, record-validation, or post-push
• context_fingerprint changed and packets need recollection
• ownership, validation path, or outdated recheck is ambiguous
• code-edit delegation guardrails fail; keep the implementation local instead of forcing delegation

Final Response

• list accepted, rejected, deferred, and defer-outdated threads
• state what changed and which validation ran
• include the PR URL
• if blocked, name the blocker precisely

References

• references/review-threads-contract.md
• references/comment-contract.md
• references/thread-action-contract.md
• references/delegation-playbook.md
• references/gh-address-review-threads-evaluation-contract.md
• references/architecture-note.md
• <python-bin> -B <skill-dir>/scripts/smoke_gh_address_review_threads.py --repo-root <repo-root>
• <python-bin> -B <skill-dir>/scripts/smoke_gh_address_review_threads.py --synthetic